[Script] Director — A Roll20 Mod to Handle Theater of the Mind Play

Director 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 Demo ]  Available in One-Click install on your mod page. Interface Overview The interface appears in a Roll20 handout. It consists of four main sections: Acts & Scenes  — scene navigation and management Images  — backdrops, highlights, and associated tracks Items  — characters, variants, macros, and other token types Utility Controls  — edit mode, help toggle, settings, backup Acts & Scenes Act Controls Acts group together related scenes. Use the  + Add Act  button to create an act. In  Edit Mode , act-level options include: Rename or delete the act Move the act 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 appears in the Images and Items sections. In  Edit Mode , scene controls include: Rename / Delete Move Up / Down — if moved past the end of an act, the scene moves to the top of the next expanded act Images Backdrop vs. Highlight Backdrop  is the main background image for the scene, displayed on the map layer to set the overall environment. Highlights  are supplementary images layered above the backdrop on the object layer, used to draw attention to specific elements or areas. When a scene is set, the backdrop is placed on the map layer, while all highlights appear on the object layer, aligned left beyond the page boundary for easy visibility and interaction. To use a highlight, the gm can drag it onto the page, or select it and use the shift-Z keyboard command to preview it to the players. Highlights and Bacdrops can be switched on the fly by using the buttons found on each image in the handout (see below) Adding Images To add an image: Drag a graphic to the tabletop. Hold  Alt / Option  while dragging to preserve aspect ratio. Select the graphic and click  + Add Image  at the top of the Images section. Image Controls Title Overlay : click to rename the image Bottom-right icons : `  Set as backdrop |  Set as highlight m  Assign track (uses currently playing audio). When an image that has a track is made into the Backdrop image, and track assigned to it immediately starts playing. In  Edit Mode : move, recapture, and delete options appear in the top-right corner Items (Characters, Variants, Tracks, Macros, Tables) Items define what is placed or triggered when a scene is set. Items are scoped per scene. Adding Items Click a badge to add a new item: H   C   V   T   M   R Item Behavior H Handouts : Opens the handout C Characters : Opens the sheet if assigned; otherwise, prompts assignment V Variants : Does not open — appears on scene set T Tracks : Toggles playback if assigned; otherwise assigns currently playing track M Macros : Runs the macro if assigned; otherwise prompts to assign an existing macro R Rollable Tables : Rolls the assigned table; otherwise prompts to assign one. Results are whispered to the GM Variants are token snapshots that share a sheet. Use these when default tokens cannot be reliably spawned, or to represent unique versions of a shared character sheet. Edit Controls In Edit Mode, each item shows: p   — Reassign #   — Delete Filter:  Click the magnifying glass button to filter items by type. Header Buttons Set Scene Set the Scene  populates the tabletop with: Backdrop image (Map Layer) Highlight images (Object Layer, left-aligned off page edge) Character and variant tokens (Object Layer, right-aligned off page edge) Starts assigned track (if set) Only works if the current page name contains:  scene, stage, theater, theatre Wipe Scene Wipe the Scene  removes all placed images and stops all audio. Only functions on valid stage pages. Edit Mode The lock button toggles editing. When enabled: Rename, delete, and move controls appear for acts, scenes, and images Items are grouped by type and display reassign/delete controls JB+ If Jukebox plus is installed in your system, Director can detect this and provide a button to open that interface. Help Displays on-screen help. Click "Exit Help" to return to the control panel. Helpful Macros The interface is primary, but the following macros can be used in chat or action buttons: !director --set-scene !director --wipe-scene !director --new-act|Act I !director --new-scene|Act I|Opening Scene !director --capture-image

Changelog 1.0.1  (July 28, 2025) Numerous touchups and bug fixes Can recognize characters with Quotes in the name (a bad practice, but it is accounted for). If storing a Variant or Character with a marketplace image in the token art, it will warn you that when it is placed during a set scene, it will use a fallback image. the fallback image is the Jumpgate default undefined character image. The setting behavior is implemented at set scene time. When starting a new campaign, the script will warn you that you need create at least one scene and one act in order to create an asset. When starting a new campaign, if the game has only one page, it will tell you that you need to create at leaste one other pages and change pages at least once as the GM . New Feature Set scene is now split into  Set as Scene  and  Set as Grid . Set as Scene  works as currently defined. Set as Grid Set as Grid is for GMs who like to have multiple scenes defined at once, allowing them to drag player tokens between them. It's especially useful when the party is temporarily split—for example, while exploring a new city.  This places up to six images on the map layer into a 2x2, 2x3, or 3x2 grid, with a strip across the top for PC tokens. It then places DL lines, turns on DL, daylight mode, with fog opacity 0. This gets cleared (along with DL lines) when setting as scene, or wiping a scene. It also disables highlight/backdrop swapping while in grid mode, and highlight images are not placed to the left. The interface was tweaked slightly after creation, but  here is a very quick video of the feature . And a screenshot from the DL layer. v1.0.2 (Aug.20, 2025) New feature: Assigning Stars to a scene's image Whenever an image is set as the backdrop to a scene, you can specify any number of characters or variants to be stars for that image. Starred characters will have a star next to them in the item list and their tokens off to the right will be outlined in gold. I instituted this since you might have a large number of characters assigned to a scene, but some of them are associated with particular images. It can take a second to find the exact ones you need. Example 1: Suppose you have a market area of the campaign city, and each store locale has a specific shopkeeper, staff or customers. Any of them might be found in the marketplace area, but when you are in the bookstore, you want to be able to find the bookseller or his assistant. There might also be a street urchin or city guard NPC who could be found in any of these places. Example 2:   A coven of helpful witches have cottages or homes in and around the city. Although they might gather at the house of any member of the coven, each is most likely to be found in their own house (image) and they are starred for that image. Example 3:   You have a scene for the boroughs or wards of a city the players are exploring. Each ward has its own image, and a  guiding handout. Whenever that ward becomes the backdrop image, the appropriate handout is starred. You can also filter the list to show only starred items. In Example 3, you could easily limit the visible handouts to just the ones specific to that ward. You can star any asset: Character/variant, handout, track, rollable tables, or macros. Here is a video  demonstrating the system. This is now active in One Click. v1.0.3  Numerous touchups and bug fixes Can recognize characters with Quotes in the name (a bad practice, but it is accounted for). If storing a Variant or Character with a marketplace image in the token art, it will warn you that when it is placed during a set scene, it will use a fallback image. the fallback image is the Jumpgate default undefined character image. The setting behavior is implemented at set scene time. When starting a new campaign, the script will warn you that you need create at least one scene and one act in order to create an asset. When starting a new campaign, if the game has only one page, it will tell you that you need to create at leaste one other pages and change pages at least once as the GM . New Feature Set scene is now split into  Set as Scene  and  Set as Grid . Set as Scene  works as currently defined. Set as Grid Set as Grid is for GMs who like to have multiple scenes defined at once, allowing them to drag player tokens between them. It's especially useful when the party is temporarily split—for example, while exploring a new city.  This places up to six images on the map layer into a 2x2, 2x3, or 3x2 grid, with a strip across the top for PC tokens. It then places DL lines, turns on DL, daylight mode, with fog opacity 0. This gets cleared (along with DL lines) when setting as scene, or wiping a scene. It also disables highlight/backdrop swapping while in grid mode, and highlight images are not placed to the left. The interface was tweaked slightly after creation, but  here is a very quick video of the feature . And a screenshot from the DL layer. 1.0.4 New feature: Assigning Stars to a scene's image Whenever an image is set as the backdrop to a scene, you can specify any number of characters or variants to be stars for that image. Starred characters will have a star next to them in the item list and their tokens off to the right will be outlined in gold. I instituted this since you might have a large number of characters assigned to a scene, but some of them are associated with particular images. It can take a second to find the exact ones you need. Example 1:  Suppose you have a market area of the campaign city, and each store locale has a specific shopkeeper, staff or customers. Any of them might be found in the marketplace area, but when you are in the bookstore, you want to be able to find the bookseller or his assistant. There might also be a street urchin or city guard NPC who could be found in any of these places. Example 2:   A coven of helpful witches have cottages or homes in and around the city. Although they might gather at the house of any member of the coven, each is most likely to be found in their own house (image) and they are starred for that image. Example 3:   You have a scene for the boroughs or wards of a city the players are exploring. Each ward has its own image, and a  guiding handout. Whenever that ward becomes the backdrop image, the appropriate handout is starred. You can also filter the list to show only starred items. In Example 3, you could easily limit the visible handouts to just the ones specific to that ward. You can star any asset: Character/variant, handout, track, rollable tables, or macros. Here is a video  demonstrating the system. This is now active in One Click. v1.0.5 Search new feature in 1.0.5 I have found through play testing that as my Acts, Scenes and Images proliferate, it becomes harder to quickly find what I am looking for. The Acts column and the Image column each now contain a search icon. Click on that and enter a search string. The script will look through the database and find every Scene and every Image containing that string and return a menu to chat. Acts, being top level and always exposed, are not searched. This is now live in the One Click repo. [ Video ]      v1.0.5 Improved Backdrop user interface, Report Function, Improvements to Help Mode, fixed set bug on search and repor t, uncluttered interface Changes are documented below. There are no breaking changes. Improved Backdrop user interface The backdrop/highlight buttons on each image are fiddle to press, and realistically superfluous. The top image is always the backdrop image. Now to set the backdrop, just click anywhere in the image, and it will become the backdrop. Report Function There is a "Report" button under settings that sends a list of all Acts, scenes and images. Scene names are appended by the count of Items attached to that scene. Might be useful for recording a list. Notably, each name line is a link that sets either the scene or highlights the image. Advanced use: Note that this link is actually a chain of commands that can be copied and pasted into a handout link (with some editing.) If you press the button in the report, then press the up arrow in chat, you will get the commands given: !director --expand-act-only|Meta !director --set-active-scene|Meta|Homes !director --set-backdrop|1757836173258_6858 Roll20 need those commands to all be one single line and have html line feeds (
) inserted between each command. Also for a journal button, the whole thing needs to be preceded by a back tick, for reasons. So editing those three commands into: !director --expand-act-only|Meta
!director --set-active-scene|Meta|Homes
!director --set-backdrop|1757836173258_6858 and pasting them into the url link of a selected word in a handout will cause those commands to issue. In this way, a chain of acts and scenes can be embedded into a handout of game notes, for example, so that the scene can be quickly accessed in the course of play. If you actually wish to fully set the scene, you will still need to either press the button in the interface (again, for reasons), or issue the command: !director --set-scene in a macro, or typed into chat. Improvements to Help Mode Cleanup and addition of some undocumented interface controls Fixed set bug on search and report, uncluttered interface When using search, a spurious image with zero height was sometimes created. This no longer happens. I also uncluttered the interface a bit by moving the superfluous search buttons from the column heads into a single search button in the main header. Easier to find.

Keith, you have outdone yourself!  I've grown my own Theater of the Mind workflow, where i need to jog between pages while the players are looking at a different Theater of the Mind scene... and it is very cumbersome.  Using a handout as a dynamic interface to build a complete roll20 extension is smart. The handout provides an extra window (like the pages select/edit bar on top) and as GM you can both see what players see and select at the same time. This looks so good. 

Wow great stuff Keith! I highly recommend people watch the video.

Due to my age I will say "Far Out!"  This promises to change my game.  Thank You

Gotta say I love the focus on UX and making this a console of its own within the system. It'd be great if we had some tools to make it even easier, I love your approach to this. I may have to ask some tips and see if there's a way to follow your lead. 

The basic structure is an updateHandout function that builds the interface, and is called whenever a change is made. case 'command': { identify any arguments or targets found by the chat handler ...do some stuff...   updateHandout();   break; } The buttons are just styled html <a> tags with an href of "!director --someCommand". Sometimes including a query. Jukebox Plus works the same way. Basically, any script that posts an interface to chat can be rewritten to use that code to update a handout instead. It even works (so far as I've tested) while popped out. You now have a floating palette! The only downside to this last bit is that you have to focus on the window before you can interact with the interface, because browsers. When I created Align . I elected to keep it in the chat, because the interaction with tokens was so important, and the interface rarely needed updating.

I've had a couple of positive comments from folks who have used this in an actual game, with no big bug blunders. So this is now in a PR to be included in One Click.

Director is now available in one click. I have done some testing and although everything seems to be working fine, there are some things to pay attention to only if loading this into an absolutely brand new game. In an absolutely brand new game: The script looks for the page the GM is on. If this is a brand new game and you have never as a gm navigated from one page to another, even once, the script doesn't know what page the GM is on. Create a second page and navigate to and from your Scene page. General Install Advice First time install, even in an established  game: Make sure you are on a page with "stage", "scene", "theater", or "theatre" in the title. The script tells you this in the chat, but there are a few edge cases where it doesn't give you full info. I have fixed this for the next update. Remember to create at least one act with one scene in it. Otherwise the script doesn't know where to store the assets. Again, the script tells you this if you try to do it, but remembering this can save you a mis-step. Beware of double quotes in a character name. This is a bad practice in general, since it can cause even generic macros to fail, so I didn't think to put in a catch for it. Thank you to the Roll20 dev team for pointing out a quick fix. This will also be fixed in the next update.

Congrats on the One-Click release It looks like a great API Mod and I'll probably try it on a new game in the near future

I havent used this, but I'm excited about it because this is the way I play. In an absolutely brand new game: The script looks for the page the GM is on. If this is a brand new game and you have never as a gm navigated from one page to another, even once, the script doesn't know what page the GM is on. Create a second page and navigate to and from your Scene page. If no page is found,could you just create a new page and navigate the GM to that? And don't do this if any pages exist.

GiGs said: I havent used this, but I'm excited about it because this is the way I play. In an absolutely brand new game: The script looks for the page the GM is on. If this is a brand new game and you have never as a gm navigated from one page to another, even once, the script doesn't know what page the GM is on. Create a second page and navigate to and from your Scene page. If no page is found,could you just create a new page and navigate the GM to that? And don't do this if any pages exist. That's one possibility. I had also considered on startup, if the script detects only one page and no characters, that it would assume a brand new game. But that wouldn't account for modules. I think another approach would be to just issue startup instructions if the state object is in it's initial state. I'll have to give it some thought.

I would generally have a default operation, and have the startup instructions for those who that doesn't work for. Thank you for the video - I just watched it and am having more ideas on how I'll use the script. I already used your script for setting images, and this looks like a massive expansion of that (and much easier to use).

I'm having a little issue with adding Variants to my game. When I try and add an NPC "Rishaal the Page-Turner" nothing happens in the game. In the MODs sandbox I get this error message: "[Director] Invalid tokenProps for variant \"Rishaal the Page-Turner\". Skipping." I am using Jumpgate and the 2014 Character sheet. The Rishall NPC is one that is supplied with Waterdeep[: Dragon Heist. I have successfully been able to add monsters such as Commoner from the Monster Manual and Player Characters. Am I doing something wrong?

Hi Hultz! I can't duplicate this. Here are the steps I followed: 1. Created a new Jumpgate game using Waterdeep: Dragon Heist. 2. Created 1 new act and 1 new scene in it. 3. Went to the token page. Selected a random character and pressed the Variant V button. Variant Item created 4. Selected Rishall token  and pressed the Variant V button. Variant Item created for Rishall 5. Created a scene page and set the scene. Tokens were created for the Variants Rishall and my test token. Can you give me more detailed repro steps or point out where my test steps may have differed from yours? Did you alter Rishall's character or token in any way?

1. Older game that has been converted to Jumpgate 2. New Act, (second act first is unpopulated) five scenes. 3. Drag and drop Rishall onto the scene and while the Rishall token was selected pressed the Variant V button. Variant Item created. 4. Added the Rishall Token image. Appears to be set as a highlight but does not show up on left side of scene. Added Grindaloth. Grinda works fine. It appears to me that there is something wrong with the token itself. I will try and recreate the token and try again.  Thank you for the attention. 

Step 4: How are you adding the Rishall Token Image? Rishall is by default e text token. Are you adding new art to the token, or adding a portrait to the scene's image assets? If you'd like to PM me an invite to the game, I'd be happy to come take a look.

I am trying this script. I have converted a legacy game to Jumpgate. I created an act and scene with only the background image and then added three handouts and about 7 charactersn (4 PC and 3 NPC) No variants. When I set the scene it places the background but only three characters appear to the right of the scene (2 PCs and 1 NPC). When I wipe the scene the background image disappears but the three characters persist to the right. If I then set the scene it will place those same three characters to the right even if they are already there. 

Jim C. said: I am trying this script. I have converted a legacy game to Jumpgate. I created an act and scene with only the background image and then added three handouts and about 7 charactersn (4 PC and 3 NPC) No variants. When I set the scene it places the background but only three characters appear to the right of the scene (2 PCs and 1 NPC). When I wipe the scene the background image disappears but the three characters persist to the right. If I then set the scene it will place those same three characters to the right even if they are already there.  If you manually delete those characters, does it function correctly afterward? The script places a marker on the images and tokens it creates so that it know what to wipe. If you brought out something manually and then defined it, the script doesn't know to wipe those things on a scene wipe. If a character token is defined by choosing from the drop down, it will sometimes fail to be placed, due to some difficulty in parsing some of the default token JSON. That's one of the reasons I created the variant option. If that's the case, then use a variant for such characters instead of defining a character asset and depending on the default token.

That worked better for the NPCs. However I get the following message in the API concerning the two PCs when added as a variant "[Director] Invalid tokenProps for variant \"Tordek Ungardt\". Skipping." "[Director] Invalid tokenProps for variant \"Michi Cutter\". Skipping." I am using the 2014 character sheet.

I'll extend the same invitation I extended to Hultz. If you want to PM me an invite to the game, I'd be happy to investigate.

There's probably no need for an invitation. Thanks to examining Hultz' game, I know what the problem likely is, and it's a hard Roll20 limitation. The API cannot create marketplace images on the VTT. It can use images that are created by creating a module, it can use images you've created yourself. It can use images from items dropped from the compendium. It can place those or marketplace images in a handout or in chat. But it is specifically forbidden from placing Marketplace images directly on the VTT. I and others have lobbied in the past to have this restriction removed, and instead institute the same safeguards that control whether you as a user have access to the image in the first place as a gate to control placing it on the VTT, but haven't gotten a lot of traction. In short it's not something I can do anything about. :/ However, it is possible to put in a user facing warning whenever you add something with a Marketplace image to the Director handout. It will tell you that this item uses a marketplace image and that it will not be able to place this item on the page. There is still value in having the Variant or Character in the items list (you can still open the character), so I won't have the script forbid it, just warn you. Alternatively, in the case of a character/variant, I could have it use a fallback image. If the token uses a marketplace image, it will fall back to a generic silhouette. What do folks think has more value? A fallback silhouette, or a warning? I'm thinking a silhouette, since this would still give you the token so you have access to HP, token actions, etc. In any case, I think I will go with the warning for the Image assets. A fallback image makes no sense here, but it would be future proofing for when and if Roll20 ever lifts the marketplace restriction.

Until I institute that, you can: A) Use non-marketplace images for Director art or B) Continue to use marketplace images for their other functionality, and wait for the potential silhouette solution.

I'm thinking a little of both, A) warning so that I know why and B) silhouette so that I can continue with what I am doing. -Thank you.

Yeah, that's probably the best way to go. It'll be in the next update, along with a cool new feature.

Thank you That helps a lot. Great Script

I have submitted a new PR. Since I might not be available when it is merged, due to Gen Con, I am going to give a preview of what it will contain: Numerous touchups and bug fixes Can recognize characters with Quotes in the name (a bad practice, but it is accounted for). If storing a Variant or Character with a marketplace image in the token art, it will warn you that when it is placed during a set scene, it will use a fallback image. the fallback image is the Jumpgate default undefined character image. The setting behavior is implemented at set scene time. When starting a new campaign, the script will warn you that you need create at least one scene and one act in order to create an asset. When starting a new campaign, if the game has only one page, it will tell you that you need to create at leaste one other pages and change pages at least once as the GM . New Feature Set scene is now split into Set as Scene and Set as Grid . Set as Scene works as currently defined. Set as Grid Set as Grid is for GMs who like to have multiple scenes defined at once, allowing them to drag player tokens between them. It's especially useful when the party is temporarily split—for example, while exploring a new city.  This places up to six images on the map layer into a 2x2, 2x3, or 3x2 grid, with a strip across the top for PC tokens. It then places DL lines, turns on DL, daylight mode, with fog opacity 0. This gets cleared (along with DL lines) when setting as scene, or wiping a scene. It also disables highlight/backdrop swapping while in grid mode, and highlight images are not placed to the left. The interface was tweaked slightly after creation, but  here is a very quick video of the feature . And a screenshot from the DL layer.

Hey, @keithcurtis,  regarding marketplace images - knowing it's a limitation, i think it's available in the sandbox experimental version as an option (different syntax for it) - I put in the Teleport script and it works when it's Jumpgate and Sandbox is set to Experimental - I do a check for whether or not it's available in a try-catch and message if it's not (first failing back to the older method just in case it's a user-uploaded image).  

Cool! Can you point me toward documentation?

Hi, I JUST started learning how to use Director, and I have a likely very silly question: When you set the scene, it adds the scene images on the left and tokens on the right of the stage... in the visible token layer. But I can't guarantee that my players are set (or will stay set) at 100% zoom. All they have to do it zoom out one and can see all the upcoming assets. Obvs I can get around this by as soon as I set the scene, grab all on the token layer and send to DM layer before hopefully anyone really sees them. But, is there a better solution? Thanks!!

Hi Deirdre! No worries. Players cannot see the backdrop area outside the page margins. Only GMs can see that. It's one of the coolest new features of Jumpgate, and why the script requires Jumpgate. You can use it in confidence that the highlights and tokens are beyond the player's sight until you decide to move them. And of course, you can still preview them to the players by selecting one and pressing Shift-Z. If you want to test this yourself, just to be confident, create a  Dummy Account , and use it to view the game as a player.

keithcurtis said: Cool! Can you point me toward documentation? I got mine straight from @TheAaron  token.createCopy(props) ...you substitute props for ones you want to override (like top, left, etc.) - but this may require a token already being on the desktop, instead of creating one from the graphic library. 

Ah yes. I remember when he introduced that, but couldn't find documentation later. It also requires the Experimental API server, like you said. Yeah, I'll have to revisit that.

keithcurtis said: [...] If you want to test this yourself, just to be confident, create a  Dummy Account , and use it to view the game as a player. (facepalm) omg I should have thought of that myself. duh! Thank you! Yes, works perfectly!!!! Additional question: This is a HUGE longshot, but don't hoit to ask! Is there a way to be able to use Dungeon Scrawl on a scene? Obviously the best way is just to move over to a DungeonScrawl page when that's necessary, then back to the Theater page. But, wow would it be cool to be able to have a Dungeon Scrawl realtime appear in a Director scene! (wishes and fishes) Anyway, THANK YOU for creating and supporting this mod!!! As a GM who FAR prefers to GM with TotM but loves using handouts and images and atmosphere still, this mod is the BEST!! oh, sorry, one more Q: Is there a way to re-order the Items? Like you can with the Acts/Scenes and Images? Thanks!!!

Oh one more question: Is there a way to support your work? Like, a ko-fi or something even? Of any mod I have ever used, this one is an absolute must-have from now on and is SO worth paying something for!! 

Deirdre D. said: keithcurtis said: [...] If you want to test this yourself, just to be confident, create a  Dummy Account , and use it to view the game as a player. (facepalm) omg I should have thought of that myself. duh! Thank you! Yes, works perfectly!!!! Additional question: This is a HUGE longshot, but don't hoit to ask! Is there a way to be able to use Dungeon Scrawl on a scene? Obviously the best way is just to move over to a DungeonScrawl page when that's necessary, then back to the Theater page. But, wow would it be cool to be able to have a Dungeon Scrawl realtime appear in a Director scene! (wishes and fishes) Anyway, THANK YOU for creating and supporting this mod!!! As a GM who FAR prefers to GM with TotM but loves using handouts and images and atmosphere still, this mod is the BEST!! oh, sorry, one more Q: Is there a way to re-order the Items? Like you can with the Acts/Scenes and Images? Thanks!!! The order of items in the items column is creation order, grouped by type. I could likely come up with a ordering routine, but unless you have an awful lot, the easiest thing to do is just set the scene, remove the items, and re-ad them in the order you want. This is pretty easy with variants, but less so with other types. I'll add that to the consideration of future things to enhance.

Deirdre D. said: Oh one more question: Is there a way to support your work? Like, a ko-fi or something even? Of any mod I have ever used, this one is an absolute must-have from now on and is SO worth paying something for!!  Enough people have asked me this that I finally put a ko-fi link in my profile. If you've got money to burn, feel free, but it is never expected or required.

New feature: Assigning Stars to a scene's image Whenever an image is set as the backdrop to a scene, you can specify any number of characters or variants to be stars for that image. Starred characters will have a star next to them in the item list and their tokens off to the right will be outlined in gold. I instituted this since you might have a large number of characters assigned to a scene, but some of them are associated with particular images. It can take a second to find the exact ones you need. Example 1:  Suppose you have a market area of the campaign city, and each store locale has a specific shopkeeper, staff or customers. Any of them might be found in the marketplace area, but when you are in the bookstore, you want to be able to find the bookseller or his assistant. There might also be a street urchin or city guard NPC who could be found in any of these places. Example 2:   A coven of helpful witches have cottages or homes in and around the city. Although they might gather at the house of any member of the coven, each is most likely to be found in their own house (image) and they are starred for that image. Example 3:   You have a scene for the boroughs or wards of a city the players are exploring. Each ward has its own image, and a  guiding handout. Whenever that ward becomes the backdrop image, the appropriate handout is starred. You can also filter the list to show only starred items. In Example 3, you could easily limit the visible handouts to just the ones specific to that ward. You can star any asset: Character/variant, handout, track, rollable tables, or macros. Here is a video  demonstrating the system. This is now active in One Click.

I really want to try this but it keeps breaking my sandbox TypeError: Cannot read properties of undefined (reading 'filter') TypeError: Cannot read properties of undefined (reading 'filter') at renderFilterBarInline (apiscript.js:26453:34) at updateHandout (apiscript.js:27158:23) at apiscript.js:28741:3 at file:///home/node/d20-api-server/src/pubsub2.js:42:46 at Map.forEach (<anonymous>) at PubSub.publish (file:///home/node/d20-api-server/src/pubsub2.js:42:35) at file:///home/node/d20-api-server/api.js:1070:14 at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

Hey Master Azroth! At what point does that error occur? When the sandbox spins up?, When you open the handout? Or when you click any particular button in the handout? EDIT: NVM, I found the issue. It's something that wouldn't pop up during my regular testing, since I don't always test a fresh install before deploying (because I'm an amateur). The crash happened because the old code accessed the items part of the internal database directly, which throws an error if nothing is defined yet (a fresh install has nothing to work from—nothing to filter). I’ve fixed it to use the already-safe activeFilter variable (with a default value), so the code no longer risks trying to filter something undefined. I've fixed the bug you found (Thank You!), and it will be in the next update, but if you want to get this up and running today to test it out: Delete your existing one-click copy Install again, but this time use the "import" button instead of the "Install" button. This will put the editable code in your Mod page. Find this line (should be line 1578): const filterByType = (st.items.filter === "all" ? '': '<span style = "' + css.forceTextColor + 'opacity: 0.5; font-family: Arial; font-style: italic;">= ' + st.items.filter + 's</span>'); Change it to this: const filterByType = (activeFilter === "all"  ? ''  : `<span style="${css.forceTextColor}opacity: 0.5; font-family: Arial; font-style: italic;">= ${activeFilter}s</span>`); And thanks again!

No thank you Keith, you do so much for all of us and you are always willing to help. You have saved my games, api's and macros on more than one occasion and this is no exception. It worked perfectly first time, thank you again.

Excellent! I'll send the pull request.

I probably should have said something a week ago, but this was merged.

Search new feature in 1.0.5 I have found through play testing that as my Acts, Scenes and Images proliferate, it becomes harder to quickly find what I am looking for. The Acts column and the Image column each now contain a search icon. Click on that and enter a search string. The script will look through the database and find every Scene and every Image containing that string and return a menu to chat. Acts, being top level and always exposed, are not searched. This is now live in the One Click repo. [ Video ]     

Next feature will be improved setting of the backdrop image. In the next version, you wil be able to just click on the image to set it as the backdrop, eliminating the need for the little backdrop/highlight buttons:  In the new behavior, the top image is the backdrop image (like currently), but is marked with the active-green border.

Can I copy an Act from one game to another?  

Yes! Use the export command in the settings menu on the  lower left. That will create a handout that has all the data in Director (Director Backup 001, 002...). Transmog that to another campaign, and import. If you have any assets like characters, tracks and such, they might not transfer, but all images should be fine. The graphics don't need to be in your game, just hosted on Roll20. You might be able to rebuild some of the other references with the "Repair" button, but it's not a guarantee. I got limits. :D

:-) Thank you.

I was a bit skeptical at first, I'm so used to running TotM games with no tools just Zoom but I'm really enjoying setting this up and rethinking how I can structure my games and add depth. For my first game I'm setting it up as a sandbox style game with Acts representing city districts and Scenes being individual locations therein. Love that I can assign music, handouts, NPCs, etc to each individual scene. Going to save me so much time and help with player immersion! Thank you so much for making this!

That just made my day! Thanks, Robin!