FileSmith
Give your Foundry folders a little color and your prep less clicking.
For GMs who want a better way to organize their world content.
Features · Preview · Installation · Compatibility · API · Roadmap · Community · AI Use · License
Feature Index
| Feature | Why it matters |
|---|---|
| Folder Appearance | Give factions, locations, and adventure chapters their own colors and shading. |
| Multi-Selection | Select a handful of entries or a whole range and organize them together holding shift or control. |
| Folder Drag-and-Drop | Move a complete folder tree while keeping everything nested inside it, much like moving folders in Windows. |
| Clipboard & Organization | Copy, cut, paste, duplicate, and tidy up through familiar right-click menus. |
| Move Undo | Put the last FileSmith move back where it started. |
FileSmith helps you organize Actors, Items, Journal Entries, Playlists, and other world content directly in Foundry's sidebar. Uploaded image and audio files stay in Foundry's FilePicker. GMs organize the content; players see folder styling on folders they already have permission to view.
Preview
Features
Folder Appearance
Make a busy sidebar easier to read at a glance.
Start with Foundry's folder color, then add a soft wash or mist to document rows. Carry a theme through nested folders and their documents, fade lighter or darker with depth, or blend toward a second color. Folder headers and document rows have independent shading patterns.
Multi-Selection
Organize a whole encounter's worth of entries in one pass.
FileSmith lets you move or delete several folders and documents at once.
Select folders and documents together with familiar click, Ctrl/Cmd-click, and Shift-click gestures. Drag an already-selected row to move the group, or use Copy Selected, Cut Selected, and Move Selected To Root from its context menu.
Selection is GM-only and stays within one directory at a time, including entries in different folders. Each directory has its own double-click setting, so you can keep click-to-select where you want it and restore Foundry's normal one-click behavior elsewhere if needed.
Folder Drag-and-Drop
Move the folder and keep its contents together.
Drop a folder onto another folder to nest it there, onto a document to use that document's folder, or onto the directory background to move it to root. Selected child entries stay inside their selected parent folders during bulk moves.
FileSmith checks for missing entries, incompatible directory types, circular moves, and Foundry's nesting limit before applying a move.
Clipboard & Organization
Keep the useful parts of a file manager in your right-click menu.
Copy or cut a folder, document, or selected group, then paste into another folder of the same document type. Duplicate Folder copies a complete folder tree, including its contents and explicit appearance settings.
You can also Merge Contents Into Parent, which moves a folder's direct contents up one level and removes the emptied folder, while keeping its child folders intact. Move Folder To Root brings a nested folder back to the top.
With dnd5e 5.3.3, copying an Item container also copies its nested contents and preserves their relationships in the new copy.
Move Undo
Recover from the last misplaced drag or folder move.
Choose FileSmith: Undo Last Move, or press Ctrl+Z / Cmd+Z while the matching directory is focused. FileSmith checks that the entries are still where that move left them before restoring their earlier locations.
Undo remembers one successful FileSmith move across the client. A newer move replaces it, and reloading clears it. Copies and permanent deletion cannot be undone.
Folder appearance — full detail
- Document shading: Off, Soft Wash, Mist from Bottom, Mist from Top, Mist from Left, Mist from Right, or Center Mist.
- Apply appearance to: This folder only, Entire nested tree, or Exclude inherited tree.
- Nested folder colors: Same color, Fade lighter by depth, Fade darker by depth, or Blend toward another color.
- Folder shading: Solid Color or one of the wash/mist patterns, independently of document shading.
- Branch control: an explicit folder appearance or exclusion stops the inherited theme for that branch; a deeper tree theme can start a new one.
- Shared appearance: only GMs configure it; users see the result on folders already visible to them.
- Automatic inheritance: colors are calculated when the directory renders, without overwriting descendants' saved folder colors.
Selection & shortcuts
| Gesture | What it does |
|---|---|
| Click | Select one row in a directory with double-click mode enabled. |
| Double-click | Open a document or expand/collapse a folder in double-click mode. |
| Ctrl-click / Cmd-click | Toggle individual rows in the selection. |
| Shift-click | Select a visible range. |
| Escape | Clear the selection. |
| Drag a selected row | Move the selected set together. |
| Drag an unselected row | Use the normal single-row behavior. |
| Ctrl+Z / Cmd+Z | Undo the latest FileSmith move while its matching directory is focused. |
| Delete / Backspace | Open the selected-delete confirmation, when enabled in settings. |
Ctrl/Cmd-click and Shift-click selection also work when a directory's double-click setting is off. Search fields, buttons, and other native controls retain their own interaction behavior.
Clipboard & context menus — full detail
All added actions use the FileSmith: prefix. Available actions depend on the row, selection, clipboard, and undo state.
- Folders: Duplicate Folder, Copy Folder, Cut Folder, Merge Contents Into Parent, and Move Folder To Root.
- Documents: Copy Document and Cut Document.
- Selected sets: Copy Selected, Cut Selected, Move Selected To Root, and Delete Selected.
- Destinations: Paste Here and Paste To Root. On a document row, Paste Here uses that document's current folder.
- History: Undo Last Move when a matching FileSmith move is available.
Clipboard operations use the context menu. The clipboard belongs to the current client session, clears on reload, and pastes only within the same document type. For example, Actors can be pasted into Actor folders, and Items into Item folders.
Settings
Open Configure Settings → FileSmith. Settings are grouped into Opening Behavior, Selection & Shortcuts (including Selection Feedback), and Troubleshooting. All preferences are saved for the current browser or client.
Opening Behavior has one checkbox per available directory and a shared explanation. Checked means single-click selects and double-click opens or expands; unchecked restores Foundry's normal single-click behavior. Ctrl/Cmd-click and Shift-click selection work either way. Organization settings appear only for GMs, and unavailable directory choices are hidden.
| Setting | Default |
|---|---|
| Double-click to open, independently for each supported directory | On |
| Clear selection when clicking away | On |
| Select entries on right-click | Off |
| Show selection count notifications | Off |
| Enable Delete / Backspace shortcut | Off |
| Enable debug logging | Off |
Right-click selection replaces the current selection when you right-click an unselected entry, and preserves the group when you right-click an already selected entry. The Delete / Backspace shortcut opens a confirmation; it never deletes immediately.
Folder appearance is saved with the folder and shared with users who can see it; it is separate from these client preferences. Debug logging remains available to all users under Troubleshooting.
Deletion, recovery & limits
Delete Selected always asks for confirmation, defaults to No, and shows the recursive folder/document count. Deleting a selected folder also deletes its contents. With supported dnd5e containers, the count includes nested Items.
Confirmed deletion is permanent and cannot be undone.
FileSmith verifies operation results and reports blocked or incomplete changes. If part of a bulk operation fails, it attempts to recover changes where safe and reports anything that needs inspection. Recovery is best-effort; undo is a single move, not a full history or backup.
FileSmith organizes world folders and documents. Compendia, imports from other sources, and physical files in the FilePicker continue to use Foundry's core behavior.
Troubleshooting
Confirm that libWrapper and FileSmith are enabled, then reload the client. If drag-and-drop enhancements are unavailable, check that libWrapper loaded successfully.
For more detail, enable FileSmith → Enable debug logging and inspect the browser console for messages prefixed with [FileSmith]. Warnings and errors are logged even with debug logging off.
If another module replaces directory rendering, drag-and-drop, or context menus, reproduce the issue with only FileSmith and libWrapper enabled in a test world.
Changes in 14.3.3
- Module settings are grouped with shared opening guidance, clearer selection and shortcut labels, and controls filtered to the current user and available directories. Existing preferences are preserved.
- Sidebar search fields and other controls keep their focus and selection behavior.
- Failed moves recover changes saved before an error where safe, and identify entries requiring inspection.
- Failed move undo preserves folders that acquired contents and identifies folders whose cleanup was blocked.
Installation
- FileSmith uses Foundry's premium content system through my Patreon: Bazaar Patron. I'm still finalizing the access setup and will add the exact activation and installation steps here once it's ready.
- Install libWrapper through Foundry's Add-on Modules → Install Module screen if it is not already installed.
- Once FileSmith is installed, open your world, enable both modules in Manage Modules, and reload connected clients.
For a manual installation, extract the package so its manifest is at Data/modules/filesmith/module.json, then restart Foundry before enabling the module.
| Requirement | Version |
|---|---|
| Foundry VTT | v14 required; verified on 14.367 |
| libWrapper | Required; tested with 1.13.5.1 |
Compatibility
Foundry VTT: v14 required; verified on 14.367.
Recorded testing: FileSmith 14.3.3 was tested with libWrapper 1.13.5.1 and dnd5e 5.3.3.
Game systems: normal world-folder and document organization is system-agnostic. Content-aware Item-container copy and deletion are verified with dnd5e 5.3.3; that does not establish container support for every system.
Directories: Actors, Items, Journal Entries, Scenes, Roll Tables, and Playlists. Cards and Macros are included when their world collections exist and support folders.
Permissions: selection, organization actions, and appearance configuration are GM-only. Players retain Foundry's normal interactions and see static appearance on folders they already have permission to view.
Playlists, compendia & other sidebar modules
- Playlists: FileSmith organizes playlist folders and Playlist entries. Nested PlaylistSound rows keep their native clicks, context menus, playback controls, and drag-and-drop behavior.
- Compendia: FileSmith does not apply its world-directory tools to compendium contents or replace Foundry's import behavior.
- Physical assets: image, audio, and other files in the FilePicker are outside FileSmith's scope.
- Other sidebar modules: modules that replace directory rendering, drag-and-drop, or context menus may bypass FileSmith. Compatibility with every such combination is not established.
Roadmap
Future priorities will be shaped by real campaign workflows and reported issues along with any that I feel would be appropriate but Share a feature request on the Discord! with an example of what you are organizing and where the current tools get in your way.
Community
- Report bugs — Report on Discord in filesmith, under behind the counter - patron only. Include your Foundry version, FileSmith version, game system and version, steps to reproduce, console logs, and screenshots or short clips when useful.
- Request features — tell me what you were trying to organize and what you wish the module could do.
- Follow updates — watch the repo for changes and compatibility notes.
AI-Assisted Development
This module is developed and maintained with the help of AI-assisted tools for coding, debugging, and testing.
I care about the quality, behavior, performance, security, and long-term maintainability of this module, and I take full responsibility for what ships. AI assistance does not replace review, testing, debugging, or security and design judgment.
AI is used here as a tool under my direction to make Foundry better and allow for long term mod support while still having a life outside of building and maintaining my free and premium modules.
If you are uncomfortable using software developed with AI-assisted tools, this module is not for you.
⚖️ License & Permissions
Premium License
FileSmith is a paid, premium module. Refer to the license terms supplied with your purchase for usage and redistribution permissions.
Commercial Licensing
For bundling, commercial integrations, or custom feature development, contact GnollStack to discuss licensing and permission.
Contact
For licensing inquiries or permission slips:
- Discord:
GnollStack(Preferred) - Email:
gnollstack@gmail.com - Please use Discord or email for commercial licensing discussions rather than GitHub Issues.
Author: GnollStack · Compatibility: Foundry VTT v14