Media

Media is a video, audio, image, or engine-specific asset with rich author-authored timing data: captions, linked media, background-clip markers, and story-beat annotations. You create media entries in the editor’s Media panel, then reference them by id on Play Sequence events that fire the asset during a run.

For conventions shared by all entity types, see Entities.

Fields

ID

The media entity’s expression-namespace identifier. You’ll use this name in Play sequence events that fire the media and in expressions that reference the asset. Renaming ID updates events that mention the old name; it does not break the media entry’s binding to events.

Convention: media ids are prefixed media_.

Title

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

Description

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

Type

The kind of asset this entry represents. One of video, audio, image, or unity. Drives how the host game loads and plays the asset:

• video: a video file (mp4 or platform-derived webm). The host renders it through a video player surface, optionally with caption overlays.
• audio: an audio file (mp3, ogg, wav). The host plays it through the audio subsystem, typically in the music or one-shot bus.
• image: a static image (png, jpg). The host displays it as a full-screen still, portrait, or overlay depending on the host’s rendering strategy.
• unity: a Unity-specific asset such as a prefab or addressable. The host resolves this through its own Unity integration pipeline rather than loading a file from disk. Use this for projects that ship the runtime inside Unity and use engine-native assets.

Default is video.

File

The filename of the source asset on disk. The file lives under the project’s media/<subfolder>/ directory, where the subfolder is determined by Type (media/video/, media/audio/, media/images/, or media/video_webm/ for platform-derived WebM files). The host reads this path relative to the project root to locate the asset at runtime.

Extension

Optional override of the file extension if File doesn’t already carry one. Use this when the host needs to know the correct MIME type or codec but the filename itself is extensionless. If omitted, the host derives the extension from File directly.

Duration (seconds)

Optional length of the media in seconds. A hint to the host for scrubbing UI controls, timeline placement, and recap summaries. The runtime does not enforce or validate this value; it’s purely metadata. If omitted, the host may probe the asset file to determine the length itself.

Use as background

Audio-only. When ticked, the game can pull this clip as a candidate for menu music or other looping background beds, outside any run. Unchecked clips are still playable through Play Sequence; the flag only marks the entry as background-eligible.

Only visible when Type is Audio. Defaults to off.

Players

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

Captions

A list of timed caption entries overlaid on video or image media during playback. Each caption carries an in-point time (At), an optional out-point (End), the speaker’s character id, the displayed text, and translator hints (Text localization note and Text max length on the caption). The runtime surfaces captions through the dialogue UI alongside the sequence.

When omitted or empty, the media plays with no overlay. Caption in-points are measured in seconds from the start of the media; if End is omitted, the caption remains visible until the next caption’s in-point.

Linked

A list of additional media entries that should fire alongside this one at a specified time offset. Each linked entry carries a Media id (the id of the asset to fire) and an At offset in seconds from the parent media’s start. Used for overlays, picture-in-picture, multi-track audio, or synchronized media chains where a secondary asset needs to play at a precise moment relative to the primary.

Authored via JSON today. The inspector doesn’t surface this field yet; expected to land alongside the multi-track playback UI.

When omitted or empty, only this media entry fires.

Background clips

A list of timed background-clip markers used by recap UIs to identify which sections of the media are filler or b-roll versus main content. Each marker carries an in-point (At), an out-point (End), and a free-form Description that explains what the clip shows. Recap systems use these markers to skip filler sections or flag them in the replay summary.

When omitted or empty, the entire media is treated as story content with no dedicated filler sections.

Story beats

A list of timed story-beat markers used by recap UIs to surface narrative highlights. Each beat carries a unique id, a time range (At to End), content text, and an Importance score on a five-step scale (Trivial, Minor, Moderate, Major, Critical). A decay rate (Importance decay) reduces the beat’s importance over time. Beats with higher importance scores are prominently surfaced in recaps; decay lets older beats fade from view as the run progresses.

Story beats also carry an optional Conditions expression that gates whether the beat should appear in the current run. Authored via JSON today; the inspector doesn’t surface this field yet.

When omitted or empty, the media carries no narrative annotations for recap.

Translator notes

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

When to reach for media

Media is the right shape when the host should play a typed asset (a video, an audio file, an image, or a Unity-native prefab) and the runtime should know about it without owning the file. The editor stores a typed reference (id, filename, duration, captions, story beats); the actual asset lives on the host’s disk under the project’s media/<type>/ folder, or for Unity media as a prefab or addressable the host resolves through its own pipeline. Reach for media whenever a beat should hand a clip, an image, or a track to the host’s player surface rather than the dialogue log.

A media entry’s content sections do double duty: Captions drive the dialogue overlay during playback (per character, per time window), Linked schedules secondary assets to fire alongside (overlays, picture-in-picture, multi-track audio), and Story beats mark narrative highlights that recap UIs can surface in importance order. Trigger a media entry with a play sequence event; the host honors the captions and beats from there.

See also

• Media: the authoring walkthrough for adding assets and captions.
• Play sequence event: the event that fires this media.
• Character: captions reference characters by id.
• Audio cue: for layered audio that ISN’T a single linear media file.
• Expressions: id conventions.