Director and Jukebox Plus Update

Director/readme.md

@@ -0,0 +1,164 @@
+# Director
+
+**Director** is a script for supporting "theater of the mind"-style play in Roll20. It provides an interface for managing scenes, images, audio, and game assets — all organized within a persistent handout.
+
+[Here is a video](https://youtu.be/TMYzFNTkiNU?si=yexMBPtz0sXNdx_o) that provides a demo of the script.
+
+---
+
+## Interface Overview
+
+The interface appears in a Roll20 handout and consists of four main sections:
+
+- **Acts & Scenes** — scene navigation and management  
+- **Images** — backdrops, highlights, and associated tracks  
+- **Items** — characters, variants, macros, and token-linked objects  
+- **Utility Controls** — edit mode, help toggle, settings, backup tools  
+
+---
+
+## 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 moment or location. Click a scene name to set it active — this controls what images and items are shown.
+
+In **Edit Mode**, you can:
+- Rename or delete scenes
+- Move scenes up or down (scenes moved beyond an act will join the next expanded act)
+
+---
+
+## Images
+
+### Backdrop vs. Highlight
+
+- **Backdrop**: Main background image placed on the Map Layer  
+- **Highlights**: Visuals layered above the backdrop on the Object Layer (for focus or emphasis)  
+
+When a scene is set:
+- The backdrop is placed on the map
+- All highlights appear just off the left edge of the page
+
+Highlights can be dragged manually, or previewed using `Shift+Z`.
+
+### Adding Images
+
+1. Drag a graphic to the tabletop (hold `Alt`/`Option` to preserve aspect ratio)  
+2. Select the graphic and click `+ Add Image` in the interface
+
+### Image Controls
+
+- **Title**: Click to rename  
+- **Bottom-right icons**:
+  - `expanding arrows icon` = Set as Backdrop  
+  - `overlapping rectangles icon` = Set as Highlight  
+  - `music note icon` = Assign currently playing track. This track will auto play whenever the image becomes a backdrop image.
+- In **Edit Mode**:
+  - Move an image up or down. Although the backdrop image always goes to the top
+  - Recapture
+  - Delete
+
+### Mute Button
+
+Toggles automatic track playback. When red, backdrops will no longer auto-start audio.
+
+---
+
+## Items (Characters, Variants, Tracks, Macros, 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:
+- `H` = Handout  
+- `C` = Character  
+- `V` = Variant  
+- `T` = Track  
+- `M` = Macro  
+- `R` = Rollable Table  
+
+### Item Behavior
+
+| Badge | Type       | Behavior                                                                 |
+|-------|------------|--------------------------------------------------------------------------|
+| `H`   | Handout    | Opens the handout                                                        |
+| `C`   | Character  | Opens the sheet if assigned; otherwise prompts for assignment            |
+| `V`   | Variant    | Places token on scene set (does not open a sheet)                        |
+| `T`   | Track      | Toggles playback; assigns current track if none assigned                 |
+| `M`   | Macro      | Runs macro if assigned; otherwise prompts to choose an existing macro    |
+| `R`   | Table      | Rolls the assigned table; result whispered to GM                         |
+
+> _Variants are token snapshots that share a character sheet. Use them to represent alternate versions of a character or avoid issues with default token behavior._
+
+### Edit Mode Controls
+
+While in **Edit Mode**, each item displays:
+- `pencil icon` — Reassign
+- `trash icon` — Delete
+
+You can also click the `magnifying glass icon` icon to filter items by type.
+
+---
+
+## Header Buttons
+
+### Set the Scene
+
+`Set the Scene` places all scene elements on the tabletop:
+
+- Backdrop (Map Layer)
+- Highlights (Object Layer, off-page)
+- Items (Object Layer, off-page right)
+- Starts assigned track (if any)
+
+> _Only works on pages named:_ `scene`, `stage`, `theater`, or `theatre`
+
+### Wipe the Scene
+
+`Wipe the Scene` removes all images and stops all audio.
+
+> _Only works on valid stage pages._
+
+### Edit Mode
+
+Toggles editing. When enabled:
+- Rename, delete, and move controls appear for acts, scenes, and images
+- Items display grouped by type with assign/delete icons
+
+### JB+
+
+If [Jukebox Plus](https://app.roll20.net/forum/post/12417862/script-jukebox-plus-enhanced-audio-control-for-roll20) is installed, this button appears and provides a chat link to launch its controls.
+
+### Help
+
+Displays this help interface. While in help mode, this changes to "Exit Help".
+
+### Make Help Handout
+
+Creates a handout containing the help documentation. Use it to reference instructions while working in the main interface.
+
+---
+
+## Helpful Macros
+
+These commands can be used in the 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`

Director/script.json

@@ -0,0 +1,19 @@
+{
+  "name": "Director",
+  "script": "Director.js",
+  "version": "1.0.0",
+  "description": "# Director\n\n**Director** is a script for supporting \"theater of the mind\"-style play in Roll20. It provides an interface for managing scenes, images, audio, and game assets — all organized within a persistent handout.\n\n---\n\n## Interface Overview\n\nThe interface appears in a Roll20 handout and consists of four main sections:\n\n- **Acts & Scenes** — scene navigation and management  \n- **Images** — backdrops, highlights, and associated tracks  \n- **Items** — characters, variants, macros, and token-linked objects  \n- **Utility Controls** — edit mode, help toggle, settings, backup tools  \n\n---\n\n## Acts & Scenes\n\n### Act Controls\n\nActs group together related scenes. Use the `+ Add Act` button to create one.\n\nIn **Edit Mode**, you can:\n- Rename or delete acts\n- Move acts up or down\n\n### Scene Controls\n\nEach scene represents a distinct moment or location. Click a scene name to set it active — this controls what images and items are shown.\n\nIn **Edit Mode**, you can:\n- Rename or delete scenes\n- Move scenes up or down (scenes moved beyond an act will join the next expanded act)\n\n---\n\n## Images\n\n### Backdrop vs. Highlight\n\n- **Backdrop**: Main background image placed on the Map Layer  \n- **Highlights**: Visuals layered above the backdrop on the Object Layer (for focus or emphasis)  \n\nWhen a scene is set:\n- The backdrop is placed on the map\n- All highlights appear just off the left edge of the page\n\nHighlights can be dragged manually, or previewed using `Shift+Z`.\n\n### Adding Images\n\n1. Drag a graphic to the tabletop (hold `Alt`/`Option` to preserve aspect ratio)  \n2. Select the graphic and click `+ Add Image` in the interface\n\n### Image Controls\n\n- **Title**: Click to rename  \n- **Bottom-right icons**:  \n  - `expanding arrows icon` = Set as Backdrop  \n  - `overlapping rectangles icon` = Set as Highlight  \n  - `music note icon` = Assign currently playing track. This track will auto play whenever the image becomes a backdrop image.\n- In **Edit Mode**:  \n  - Move an image up or down. Although the backdrop image always goes to the top\n  - Recapture\n  - Delete\n\n### Mute Button\n\nToggles automatic track playback. When red, backdrops will no longer auto-start audio.\n\n---\n\n## Items (Characters, Variants, Tracks, Macros, Tables)\n\nItems define what gets placed or triggered when a scene is set. Items are scoped per scene.\n\n### Adding Items\n\nClick a badge to add a new item:\n- `H` = Handout  \n- `C` = Character  \n- `V` = Variant  \n- `T` = Track  \n- `M` = Macro  \n- `R` = Rollable Table  \n\n### Item Behavior\n\n| Badge | Type       | Behavior                                                                 |\n|-------|------------|--------------------------------------------------------------------------|\n| `H`   | Handout    | Opens the handout                                                        |\n| `C`   | Character  | Opens the sheet if assigned; otherwise prompts for assignment            |\n| `V`   | Variant    | Places token on scene set (does not open a sheet)                        |\n| `T`   | Track      | Toggles playback; assigns current track if none assigned                 |\n| `M`   | Macro      | Runs macro if assigned; otherwise prompts to choose an existing macro    |\n| `R`   | Table      | Rolls the assigned table; result whispered to GM                         |\n\n> Variants are token snapshots that share a character sheet. Use them to represent alternate versions of a character or avoid issues with default token behavior.\n\n### Edit Mode Controls\n\nWhile in **Edit Mode**, each item displays:\n- `pencil icon` — Reassign\n- `trash icon` — Delete\n\nYou can also click the `magnifying glass icon` icon to filter items by type.\n\n---\n\n## Header Buttons\n\n### Set the Scene\n\n`Set the Scene` places all scene elements on the tabletop:\n\n- Backdrop (Map Layer)\n- Highlights (Object Layer, off-page)\n- Items (Object Layer, off-page right)\n- Starts assigned track (if any)\n\n> Only works on pages named: `scene`, `stage`, `theater`, or `theatre`\n\n### Wipe the Scene\n\n`Wipe the Scene` removes all images and stops all audio.\n\n> Only works on valid stage pages.\n\n### Edit Mode\n\nToggles editing. When enabled:\n- Rename, delete, and move controls appear for acts, scenes, and images\n- Items display grouped by type with assign/delete icons\n\n### JB+\n\nIf Jukebox Plus is installed, this button appears and provides a chat link to launch its controls.\n\n### Help\n\nDisplays this help interface. While in help mode, this changes to \"Exit Help\".\n\n### Make Help Handout\n\nCreates a handout containing the help documentation. Use it to reference instructions while working in the main interface.\n\n---\n\n## Helpful Macros\n\nThese commands can be used in the chat or bound to macro/action buttons:\n\n`!director --set-scene`\n\n`!director --wipe-scene`\n\n`!director --new-act|Act I`\n\n`!director --new-scene|Act I|Opening Scene`\n\n`!director --capture-image`",
+  "authors": "Keith Curtis",
+  "roll20userid": "162065",
+  "dependencies": [],
+  "modifies": {
+    "graphic": "read, write",
+    "handout": "read, write",
+    "character": "read, write",
+    "jukeboxtrack": "read",
+    "macro": "read",
+    "rollabletable": "read"
+  },
+  "conflicts": [],
+  "previousversions": ["1.0.0"]
+}