Audio cue

An audio cue is an author-defined audio bundle composed of one or more segments, each describing a sub-clip with its own asset chain, selection strategy, looping mode, and scope. Fire a cue with an Audio Cue event and stop it with a Stop Audio event.

For conventions shared by all entity types, see Entities.

Audio cue inspector for Anne's Theme on the Music layer, with one play-once intro segment and one looping segment scoped to the next cue. — The Audio cue inspector, opened from the Audio Cues tab of the Data View.

Fields

ID

The audio cue’s expression-namespace identifier. You’ll use this name in audio cue events that fire the cue. Pick from the editor’s audio cue picker. Renaming the ID updates events that mention the old name.

Convention: audio cue ids are prefixed cue_ (e.g. cue_ambient_loop, cue_one_shot).

Title

The human-readable label shown in the editor’s audio cue picker and the audio cue inspector. Free-form string, author-typed. This is the visible name (not the expression-namespace ID), and it’s what the author sees when selecting a cue to fire on a node or event.

Description

Optional author-facing prose explaining the purpose or context of this cue. Surfaces in the editor’s audio cue inspector as a detail row. Has no runtime effect.

Layer

The audio bus or channel this cue routes to. Pick from the editor’s dropdown. Drives the host game’s audio mix:

Music (music): looping background tracks. The host loops these and applies music-layer policy (ducking, crossfade).
Ambient (ambient): looping environmental sounds. The host loops these and applies ambient-layer policy.
One shot (oneShot): single-play sound effects. The host plays them once and does not loop.
Custom (custom): a project-specific layer keyed by Custom layer. The host reads the Custom layer string to map to its own mix channel.

Default is Music. The parenthesised code values are what the disk schema stores; the writer-facing labels are what the editor dropdown shows.

Custom layer

A free-form string used when Layer is set to Custom. The host game reads this value to map the cue to its own custom mix channel or bus. Ignored (empty) when Layer is any of the standard layers.

Segments

A list of segment definitions that make up the cue. Each segment is an authored sub-clip containing one or more audio asset references, a Selection strategy, an optional Loop flag, and a Scope that determines when the segment ends. Segments are the building blocks of layered audio: a cue with multiple segments plays each segment in sequence.

Selection picks which audio ref plays each time the segment starts (and, for looping segments, each pass through the loop):

Ordered (ordered): play each asset in the order authored.
Pick one (pickOne): randomly select one asset from the list each time the segment starts.
Shuffle once (shuffleOnce): shuffle all assets and play them once each in the shuffled order.
Random each loop (randomEachLoop): randomly pick one asset each time the segment loops.

Scope determines when playback ends. Non-looping segments always use Until audio ends (the scope selector is hidden when Loop is off). Looping segments pick from:

Until choice selected (untilChoiceSelected): ends when the player selects a choice on the current node.
Until choices presented (untilChoicesPresented): ends when the next choice set is shown to the player.
Until activity started (untilActivityStarted): ends when the next activity fires.
Until activity ended (untilActivityEnded): ends when the current activity completes.
Until next cue (untilNextCue): ends when another cue starts on the same layer.
Until stop event (untilStopEvent): ends only when a matching Stop Audio event fires.
Until (custom) (untilCustom): ends when the host raises the custom signal named in the Custom field. Use this when the project needs a project-specific pause point the built-in scopes don’t cover.

The parenthesised code values are what the disk schema stores; the writer-facing labels are what the editor dropdowns show.

Players

Multiplayer scope override. If set, the cue only plays for the listed player slots. Empty (default) = all players. For single-player projects, leave empty.

Translator notes

Title can carry a translator note: see Entities for more information.

When to reach for audio cues

An audio cue is the right shape when sound needs to follow story beats automatically: looping background score that swaps between scenes, ambient room tone that ends when a choice resolves, a stinger that punctuates a reveal. Each cue bundles one or more segments; each segment is a chain of audio assets with its own selection strategy (ordered, pick-one, shuffle), an optional loop, and a scope that decides when playback ends. The runtime advances segments when the scope closes (a choice resolves, the next cue fires, a custom signal arrives), so the host doesn’t script transitions by hand.

Reach for a cue any time you would otherwise wire up bespoke audio logic per scene. Fire a cue from a node or event with an audio cue event and halt it with a stop audio event. The host-side scope contract (which event ends which segment, layer/policy details, file loading) is covered in the Unity audio integration guide.