Chapters & segments
A chapter is the whole experience; segments 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 Chapter Vision project follows the same four-level hierarchy:
| Level | What it is | Film analogy |
|---|---|---|
| Chapter | The whole document: one .chapterscript bundle, one experience | The film |
| Segment | A timed scene inside the chapter | A scene |
| Step | A timed beat inside a segment | 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 segments, 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 segment first, so a chapter always knows where to begin.
Segments: the scenes of your chapter
A segment is a self-contained scene with its own clock. Each segment 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 segment's entities lives on the segment 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 segment 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-segment, 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 segments on the timeline
In Chapter Studio, segments 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 segment. The + button at the end of the tab strip adds a new segment.
Select a segment 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-segment inspector is also where you'll find the gate editor for the selected step. Chapter Vision mirrors all of this: the same segment tabs sit on its floating timeline, and its inspector edits the same settings.
Note. The default segment is where playback starts when the player opens the chapter. You can change which segment is the default in the segment settings, which is handy when you want to test a later scene repeatedly without sitting through the opening.
How segments relate to steps and actions
A segment'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 segment'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. Segment at scene granularity. If you're tempted to build one enormous segment with dozens of steps, split it wherever the story naturally turns. Segments are cheap, and smaller ones are far easier to time, test, and rearrange.