Skip to main content

Scenes

Overview​

Scenes allow you to chain multiple scripts and dialogues together into organized, sequential playlists. Create complex narrative flows by linking related content without cramming logic into single nodes. Scenes maintain game state throughout playback, making them perfect for multi-part sequences that involve Variables, Scenarios, and dialogue choices.

Features​

  • Sequential Chaining: Link multiple scripts and dialogues in order
  • Flexible References: Reference any Script or Dialogue document
  • Drag-and-Drop Reordering: Organize items by dragging them into the desired sequence
  • State Persistence: Variables and game state persist across scene items
  • Export Support: Scenes can be included in game content exports via API or manual export

Scene Item Structure​

Each item in a scene playlist contains:

{
  "docId": "uuid-of-script-or-dialogue",
  "docType": "Script" | "Dialogue",
  "startLine": 0,          // For Scripts: line number to begin playback (default: 0) -- For future use
  "startNode": null        // For Dialogues: node ID to start from (null = auto-detect start) -- For future use
}

Usage Guide​

Creating a Scene​

  1. Create a new Scene document
  2. Click Add Item to open the document picker
  3. Select a Script or Dialogue to add to the playlist
  4. Repeat to add more items
  5. Drag items up or down to reorder the sequence

Drag-and-Drop Reordering​

Click and hold the grabber icon (⋮⋮) next to any item, then drag it to a new position in the list. The scene playlist updates immediately.

Scene Playback​

Open a scene and click the Play Scene button to launch the scene player. The player shows:

  • Progress strip: Visual indicator of your position in the scene
  • Navigation controls:
    • Previous Item (⏮): Jump to the previous script/dialogue
    • Next Item (⏭): Advance to the next item
    • Jump to Item: Click any item in the progress strip to jump directly to it
  • Item counter: "Item 3 / 7" shows your current position

Playback Behavior:

  • Scripts play line-by-line; navigate forward past the last line to advance to the next item
  • Dialogues play node-by-node; reaching an End node does not advance automatically. Use the Next button to proceed to the next item after dialogue completion.
  • Variables modified during playback persist across all scene items if "Write to Live Scenario" is enabled in project settings (default: true)

Exporting Scenes​

Scenes can be included in game content exports:

  1. Go to Project Settings → Export Options
  2. Check the Scenes checkbox
  3. Click Export Game Content or use the API endpoint

Exported scenes contain the full item structure, allowing your game engine to reconstruct and play scenes programmatically.

API Export Example:

GET /game-export?collections=Scripts,Dialogues,Variables,Scenarios,Scenes

See API Documentation for more details.

Use Cases​

  • Complex narrative sequences spanning multiple dialogues
  • Tutorial sequences combining scripts and dialogue
  • Story chapters or acts with multiple components
  • Cinematic sequences with branching dialogue and variable changes
  • Multi-stage encounters where Variables track progression across scenes

Integration with Variables and Scenarios​

Scenes work seamlessly with Variables and Scenarios:

  • Variables: Modified during scene playback, changes persist across items
  • Scenarios: Load a scenario before playing a scene to set up initial state
  • Scripting: Use @set and @if commands in scripts and dialogue port scripts to control flow

Example workflow:

  1. Load a Scenario to set initial variable values (e.g., player.location = "forest")
  2. Play a Scene with multiple dialogue branches that modify variables
  3. Variables persist across all scene items, allowing later items to reference earlier choices
  4. After scene completion, save a new Scenario snapshot for testing