The Director script supports "theater of the mind" style play in Roll20. It provides an interface for managing scenes, associated images, audio, and relevant game assets — all organized within a persistent interactive control panel handout. Video Tutorials: Director intro | Set as Grid feature | Search feature | Star Item feature Available in One-Click install on your mod page. (Roll20 closes threads after a few months of inactivity, so this is a fresh thread replacing the original .) New features with this version are: Actor-- a new, preferred way of designating a character/token for a scene Crossfade Transitions One-Macro setups Fill Margin setting changes to increase working area Many other items are also new to this thread, but were present in earlier releases Each detailed below. To make them easier to find, I have marked them with a star emoji: ⭐ Interface Overview The interface appears in a Roll20 handout and consists of five main sections: Header — search, edit mode, help toggle, and scene controls (Set as Grid/Scene, Wipe the Scene, Stop Audio) Acts & Scenes — scene navigation and management Images — backdrops, highlights, and associated tracks Items — Actors, characters, variants, macros, and other token-linked objects Settings — light/dark mode, captions, margins, backup/restore, report generation, and repair Acts & Scenes Act Controls Acts group together related scenes. Use the + Add Act button to create one. In Edit Mode , you can: Rename or delete acts Move acts up or down Scene Controls Each scene represents a distinct time and place. Click a scene name to set it active — the active scene determines what shows up in the Images and Items sections. In Edit Mode , you can: Rename or delete scenes Move scenes up or down (a scene moved past the end of an act joins the top of the next expanded act) Search As my own Acts, Scenes, and Images have piled up over a long campaign, it got harder to find what I was looking for quickly. Click the magnifying-glass icon in the column header to search scenes and images by name (Acts themselves aren't searched — they're the top level, and always visible). Enter a partial or similar term and Director returns every match to chat. Click a scene's name and it expands to that act and highlights the scene without touching the tabletop; there's a set button right next to it if you actually want to make it live. Image results show a thumbnail plus set (cuts straight to that scene with this backdrop) and Reveal (crossfades it in without wiping or pushing anything else live — handy for staging a backdrop ahead of time, or swapping one in mid-scene). Images Backdrop vs. Highlight Backdrop : the main background image for the scene, placed on the Map Layer Highlights : every other image in the scene, layered on the Object Layer for focus or emphasis When a scene is set, the backdrop goes on the map, and highlights appear just off the left edge of the page — drag one onto the map as needed, or preview it with Shift+Z . ⭐ Clicking an image to make it the backdrop on a scene that's already live now crossfades smoothly instead of snapping instantly. Clicking an image while browsing a different scene doesn't touch the tabletop at all — it just lines up what that scene will use next time, without disturbing what's currently on screen. Adding Images Drag a graphic to the tabletop (hold Alt / Option to preserve aspect ratio) Select the graphic and click + Add Image in the interface Image Controls Title overlay : click to rename Click the thumbnail : sets this image as the scene's backdrop Bottom-right icon : assign the currently playing track — it auto-plays whenever this image becomes the backdrop In Edit Mode : move, recapture, and delete controls appear in the top-right corner Mute Button Toggles automatic track playback. When red, backdrops no longer auto-start audio. Items (Actors, Characters, Variants, Handouts, Tracks, Macros, Rollable Tables) Items define what gets placed or triggered when a scene is set. Items are scoped per scene. Adding Items Click a badge to add a new item: A (Actor) , C (Character), V (Variant), H (Handout), T (Track), M (Macro), R (Rollable Table). Item Behavior Badge Type Behavior A Actor ⭐New! Appears on scene set, copied live from a reference token; opens that token's character sheet if it's linked to one C Character Opens the sheet if assigned; otherwise prompts for assignment V Variant Places token on scene set (does not open a sheet) H Handout Opens the handout T Track Toggles playback if assigned; otherwise assigns the currently playing track M Macro Runs the macro if assigned; otherwise prompts to choose an existing one R Table Rolls the assigned table; result whispered to the GM ⭐Actor — New! This is a lighter-weight alternative to Variant: instead of storing its own snapshot, an Actor points at a reference token you keep on a permanent Token Page, and copies it live every time it's placed. Edits to the reference token (image, bars, auras, etc.) are picked up automatically, and it takes far less storage than a Variant. You can convert an existing Character or Variant to an Actor with one click in Edit Mode — Director will also find and convert matching duplicates of the same character elsewhere in the campaign at the same time. Variants are still there and still useful (particularly when a default token can't be reliably spawned), but Actor is absolutely the preferred method going forward. Star System Star an Actor, Character, or Variant to link it to a specific backdrop image. Useful when a scene has a lot of items attached, but some of them really only belong with a particular image: Marketplace example: each shop has its own shopkeeper or staff, but a street urchin or city guard might show up in any stall — star the shopkeepers to their own shop's image, and leave the wandering NPCs unstarred. Coven example: a group of witches might gather at any of their homes, but each is most often found at her own cottage — star her there. City ward example: each ward of a city has its own image and its own guiding handout; star the handout to the ward's image, and the item list stays uncluttered as you flip between wards. Starred items get a gold outline on their tokens whenever their image is the live backdrop. The Star Filter button shows only starred items; use the item filter to temporarily see everything again. Disabled in Grid Mode. Supernotes Integration If you've got the Supernotes script installed, an info button appears next to each Actor, Character, or Variant in the Items list — click it to whisper that item's token notes to chat in Supernotes' card layout. It only shows up when there's a live token for it to point at. ⭐Improved behavior Edit Mode Controls While in Edit Mode , each item shows: Move up / move down Rename (display name only) Redefine — reassign what the item points to Convert to Actor (Character and Variant items only) (⭐New!) Delete Settings ( New Settings)! A collapsible menu for utility functions and global behavior. Mode — switches the interface (and its chat output) between Light and Dark. Independent of the game's own dark/light setting. ⭐ Captions New! — optional text overlays on theater pages (Scene Mode only), toggled On/Off and configured with Set. Style and position a text object on the page as a template; Director reuses it every time a scene is set, and can substitute [Act] , [Scene] , and [Image] into the text (e.g. "Scene: [Scene], Location: [Image]" → "Scene: Castle Ward, Location: Yawning Portal" ). Off and campaign-wide by default. Not supported in Grid Mode. ⭐ Margins New! — turn Margins Off if you run the Director interface docked in the VTT, and On if you run it popped out into its own window. Off is the default. (The handout's margins render slightly differently depending on which way you use it — this setting corrects for that.) Backup — make creates a sequentially numbered "Director Backup ###" handout, useful for restoring a corrupted database, or for moving act/scene/image definitions to a new campaign (handy alongside Transmogrifier if you're copying a whole game over). restore replaces the current database with a selected backup (can't be undone). Make Report — sends a clickable list of every Act, Scene, and Image to chat. Each line is a link that jumps to that scene or highlights that image — and, if you press the button and then the up-arrow in chat, you get the raw chained commands, which can be pasted into a handout link to build your own jump-points into the game. Repair — checks the database for problems (orphaned tracks, orphaned images, and other general cleanup) and tries to fix them, and refreshes the handout if images were added or removed outside the normal flow. Header Buttons ⭐ Search New! — opens a prompt to search scenes and images by name (see Search, above). Set Scene as: Scene places the following on the tabletop: Backdrop image (Map Layer) Highlight images (Object Layer, left-aligned off page edge) Actor, Character, and Variant tokens (Object Layer, right-aligned off page edge) Starts the assigned track, if any Set Scene as: Grid places up to nine images (expanded from the original six) in a grid on the Map Layer, with a strip across the top reserved for player tokens. It surrounds each image with dynamic-lighting barriers and turns on dynamic lighting with Daylight Mode — handy for a temporarily split party, or for letting players drag their tokens between locations at will. The Star system is disabled in Grid Mode, since there's no single backdrop. Set as Scene and Set as Grid both only work if the current page name contains scene , stage , theater , or theatre . Wipe the Scene — removes all placed images and stops all audio. Only works on valid stage pages. Stop Audio — stops whatever's playing without otherwise touching the scene. Edit Mode — toggles editing. When on, rename/delete/move controls appear for acts, scenes, and images, and items show their full set of edit controls. JB+ — if you have Jukebox Plus installed, this button appears and links to its controls. Help — displays the in-program help. ⭐ New! It's been rewritten to match how the script actually works today, with a new interface diagram, working jump-links to each section, and a collapsible "advanced details" area so new users aren't overwhelmed up front. Make Help Handout — appears in Help mode; creates a standalone handout with the help documentation, so you can reference it while working in the main interface. Helpful Macros The interface is primary, but these can be used in chat or bound to macro/action buttons: !director --set-scene
!director --wipe-scene
!director --new-act|Act I
!director --new-scene|Act I|Opening Scene
!director --capture-image
⭐New ! An entire scene setup can also be triggered from a single macro handy if you want a preset list of scenes keyed to macro buttons for quick access during a session. Both commands take the Act, Scene, and Backdrop/Image name directly, spelled however you like (matching is case-insensitive): !director --set|Act I|Opening Scene|Tavern Interior
!director --reveal|Act I|Opening Scene|Tavern Interior
--set — cuts straight to a brand-new scene: wipes whatever's up, then sets and pushes the given act/scene/backdrop live. --reveal — just navigates and sets the backdrop, with no wipe and nothing pushed live. This is the same thing the Reveal button on a search result does: crossfade to a new backdrop within a scene that's already live, or pre-stage what a scene not yet live will show next. If a name can't be found, neither command changes anything — chat tells you which name(s) didn't match so you can check your spelling. Bug Fixes In this release: Character names containing quotes are now handled correctly. A Variant or Character using a Marketplace image now warns you up front that it'll fall back to a default silhouette image when placed — the API can't put Marketplace art directly on the VTT. The best way to avoid this is to use Actor over Variant New campaigns get a clear warning if you haven't yet created at least one Act and Scene, or if the game still has only one page. Fixed a fresh-install crash caused by an undefined filter variable. Fixed search occasionally creating a stray zero-height image. Fixed a bug that could corrupt or fail to restore certain backups; backup and restore are more reliable overall. Fixed Capture Image, which was documented but could sometimes trigger a crash. Fixed Repair unexpectedly stopping any music that was playing. Fixed act/scene names or image titles containing a | character breaking the rename/delete buttons. Fixed the Supernotes button sometimes pointing at a token that no longer existed.