Audio cues

An audio cue is a sequence of one or more segments. Each segment is a short asset chain with its own selection rule, loop setting, and end condition. The runtime plays through them in order and stops at the boundary you pick. Cues let audio follow story beats automatically, so transitions don’t have to be scripted per scene.

What’s not here: field-by-field reference for the cue and segment types (Audio cue reference); firing a cue from an event (Audio cue event reference); host-side wiring for layers, scopes, and file loading, which lives with the integration docs the studio’s engineers use.

Anatomy of a cue

Audio cue inspector for Anne's Theme showing Identity plus three segments (intro, randomized loop, outro) and the Preview row.

Identity: Title, ID, and Layer live here. Description is a writer memo; it isn’t rendered in a run.
Segments: one or more, drag-to-reorder, each with its own Loop and Scope. This is where the shape of the cue lives.
First segment (intro, non-looping): plays once, then the cue advances.
Second segment (the loop): three interchangeable refs, chosen at random on each pass. Ends the moment the player commits to a choice.
Third segment (outro, non-looping): plays once after the loop ends.
Preview: Play cue, Stop, Advance segment, and a scrubber under the status line. Audition the cue without leaving the inspector.

Build a cue end to end

Use cue_anne_theme in the encounters sample as the worked example. It’s a three-part shape: an intro that plays once, a looping middle that holds under a choice, then an outro that plays out after.

Open the Audio cues tab in the Data View and click New Cue (or click cue_anne_theme to follow along). In the inspector, set Title (“Anne’s Theme”), optionally tweak ID (defaults to cue_<slug>), and pick a Layer. Use music for looping background tracks, ambient for room tone, oneShot for stingers, or custom plus a free-form Custom layer string when your project’s mix needs a non-standard bus.
The new cue starts with one empty segment. In the Audio refs picker, pick the intro clip. Leave Selection as Ordered and leave Loop unchecked. With Loop off, Scope is locked to Until audio ends: the segment plays once, then the cue advances.
Click Add Segment for the looping section. Add its audio ref or refs. Tick Loop. Pick a Selection: Random each loop for variety on each pass, Ordered for a predictable cycle, Pick one for a single random choice that holds for the whole segment, Shuffle once for a single shuffled pass.
Pick a Scope. The question is “what should end this loop?”. See the next section for the choices and what they mean to the player.
Add a final non-looping segment for the outro if you want a distinct tail: the same shape as step 2 with a different clip. Save. The cue is now ready to fire from an event (covered below).

Segments reorder by dragging the ⋮⋮ handle on the header. The inspector flags conflicts inline with red outlines: Random each loop requires Loop on; Loop on requires a Scope other than Until audio ends; Until (custom) requires a custom key.

Pick the right Scope

Segment 2 of Anne's Theme, cropped to the Loop, Selection, and Scope knobs.

Loop (checkbox, ticked): tells the segment to loop rather than play once and advance.
Selection (Random each loop shown): picks which ref plays on each pass through the loop.
Scope (Until choice selected shown): the condition that ends the loop and moves the cue on.

Four of the seven scopes cover most of what writers reach for:

Until next cue: the loop holds until another cue fires on the same layer. Right for background music and ambience.
Until choice selected: ends the moment the player commits to a choice. Right for tension music under a decision.
Until choices presented: ends as soon as the choice list appears. Right for transitional bridges into a beat.
Until stop event: only ends when a Stop audio event fires. Right for cues that should span beyond any cue change or choice.

Until activity started and Until activity ended tie a cue to an Activity event’s lifecycle. Until (custom) takes a free-form key the host handles its own way. See the Audio cue reference for the full list.

Preview before shipping

Audio cue Preview row mid-playback: Stop and Advance segment on the buttons row, the status line, and a pause / scrubber / time readout below.

Stop: ends the preview and resets to segment 1.
Advance segment: skips past the current loop into the next segment without waiting for the segment’s scope to close.
Status line: shows which segment and which ref is currently playing.
Scrubber: pause or resume without losing state, click to seek within the current ref, and read elapsed time on the right.

Two facts the writer needs about the preview:

The preview plays segments back through the browser’s audio element. Useful for hearing the Selection mode, ref order, and pacing, but it can’t close a segment’s scope. In a real run, a looped segment ends when a choice resolves, the next cue fires, or a stop event lands, and the editor doesn’t fire those.
For that reason, looped segments expose an Advance segment button. Click it during preview to play out the current clip and step past the loop into the next segment, so the whole cue can be auditioned.

The host is authoritative. What plays in-game depends on the host’s Scope plumbing and layer policy; the preview is an authoring aid, not a runtime test.

Fire a cue

To play the cue in a run, add an Audio cue event on a node or event list, pick the cue from its Cue field, and pick the Layer the event routes through. See the Audio cue event reference for the event’s full field set. To stop the cue when the Scope doesn’t already, add a Stop audio event on the same layer. See the Stop audio event reference.

Ambient-layer cues can also be bundled onto a location as an ambience. See Locations for the workflow.