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. One of music, ambient, oneShot, or custom. Drives the host game’s audio mix:

music: looping background tracks. The host loops these and applies music-layer policy (ducking, crossfade).
ambient: looping environmental sounds. The host loops these and applies ambient-layer policy.
oneShot: single-play sound effects. The host plays them once and does not loop.
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.

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 looping mode, 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, with the host applying the segment’s strategy at runtime:

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

The segment’s scope determines when playback ends. Options include playing until the audio naturally finishes, until a player makes a choice, or until a runtime condition becomes true.

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.