Chapters & sequences
A chapter is the whole experience; sequences are its scenes. Understanding this two-level structure is the key to organizing anything longer than a single moment.
The document model at a glance
Every Maestro project follows the same four-level hierarchy:
| Level | What it is | Film analogy |
|---|---|---|
| Chapter | The whole document: one .chapterscript bundle, one experience | The film |
| Sequence | A timed scene inside the chapter | A scene |
| Step | A timed beat inside a sequence | A shot |
| Action | Something that happens during a step | What's in the shot |
This page covers the top two levels. Steps and actions have their own page.
The chapter: one bundle, one experience
The chapter is your project: the entire .chapterscript bundle, saved as
chapter.json plus an assets/ folder. It carries the experience's name,
all of its sequences, the shared asset catalog, the environment settings, and any particle
presets you've defined. When the player opens a chapter, it plays the chapter's
default sequence first, so a chapter always knows where to begin.
Sequences: the scenes of your chapter
A sequence is a self-contained scene with its own clock. Each sequence carries:
- A name ("Arrival", "The Reveal", "Finale") shown on its timeline tab.
- Steps, the ordered, timed beats that make up the scene, each holding the actions that fire during it.
- Animation tracks: keyframe animation for the sequence's entities lives on the sequence itself, not inside individual steps, so a move can arc smoothly across many beats. See the animation overview.
- A presentation mode: Immersive, Mixed, or Windowed. Each sequence chooses how it meets the viewer. See Presentation modes.
- An optional immersive backdrop, a 360°/180° video skybox or a USDZ environment that wraps the scene.
Because presentation is per-sequence, one chapter can open in a window, move to mixed immersion as the story builds, and go fully immersive for the finale — the player handles each transition automatically.
Working with sequences on the timeline
In Maestro Studio, sequences appear as a row of tabs across the top of the timeline. Click a tab and the timeline, viewport, and inspector all switch to that sequence. The + button at the end of the tab strip adds a new sequence.
Select a sequence and the inspector shows its settings: name, presentation mode, backdrop picker, its list of steps, and the Animation card for its keyframe tracks. This per-sequence inspector is also where you'll find the gate editor for the selected step. Maestro Vision mirrors all of this: the same sequence tabs sit on its floating timeline, and its inspector edits the same settings.
Note. The default sequence is where playback starts when the player opens the chapter. You can change which sequence is the default in the sequence settings, which is handy when you want to test a later scene repeatedly without sitting through the opening.
How sequences relate to steps and actions
A sequence's duration is simply the sum of its steps. Each step has a duration, and its actions fire as the playhead passes through, whether that's revealing an entity, playing video and audio, or triggering an effect. The clips you see on a sequence's timeline are derived from those actions: a reveal opens a clip, a hide closes it. Steps can also carry gates that hold the scene until the audience is ready, which is how a fixed timeline becomes a live, responsive performance. The full timing model is on Steps & actions.
Tip. Sequence at scene granularity. If you're tempted to build one enormous sequence with dozens of steps, split it wherever the story naturally turns. Sequences are cheap, and smaller ones are far easier to time, test, and rearrange.