Cinematic Scene Data

A cinematic scene is a server-loaded timeline that combines camera motion, actor cues, world events and subtitles. Positions are relative to a supplied pivot, so the same scene can play at different locations without rewriting its coordinates.

Where the files live

Place scene JSON in data/<namespace>/cinematic_scenes/*.json, including subdirectories. By default its resource path becomes the scene ID; an explicit id overrides it. Higher-priority packs replace the same resource ID. Different files can collide on an explicit scene ID: the loader logs the collision but has already replaced the earlier entry, and resource iteration is not sorted.

Camera-only Gecko animations are separate client assets under assets/<namespace>/camera_animations/*.json. A scene’s gecko track references their animation registry ID, not the JSON filename. The native spline track needs no such asset.

Minimal example

This short fixed shot uses the same camera-node fields as the bundled isekaiexpansion:hidden_hud_subtitle_scene. Save it as data/example/cinematic_scenes/fixed_shot.json to define example:fixed_shot; its 40 ticks equal 2 seconds at 20 ticks per second.

{
  "schema": 1,
  "length_ticks": 40,
  "camera": {
    "track": {
      "nodes": [
        { "t": 0, "pos": [0, 1.7, 4], "rot": [0, 180, 0], "fov": 60 }
      ]
    }
  }
}

An empty object also parses, but supplies no camera pose. It still has default playback settings, so a successfully loaded file is not necessarily a useful shot.

Fields

Root and playback

All scene times are ticks. Length is clamped, but cue times are not checked against it: entries after the end never run. Playback fade/blend values have no parser range check; client transport normalises negative values to 0. Omitting playback gives blend values of 8; supplying an empty object gives 10, because absent blend fields inherit the fade values.

Pivot coordinates and actors

The supplied transform uses +X right, +Y up and −Z forward in the scene’s reference pose. Local yaw 180 faces forward. Position offsets rotate by pivot yaw minus 180; local yaw becomes pivot yaw plus local yaw minus 180. All positions use blocks, and rotations use degrees. The pivot metadata does not select or move the actual transform.

For triggering_player, the player wins before UUID and other filters. Otherwise a UUID-resolved living entity wins; if it cannot be found, nearest resolution continues. Both nearest selectors use the same axis-aligned search box and optional type/name filters, then choose the closest living, present candidate to the pivot. The box is not a spherical radius test. An explicit type filter excludes the triggering player from that search.

Actor keys that normalise to the same text overwrite earlier keys. A supplied player definition is retained; only an absent key gets the default triggering-player definition. Unresolved custom actors are omitted at playback start.

Camera tracks and nodes

The first table describes camera and its track; the second describes each track.nodes entry.

Native tracks interpolate position with the selected interpolation, pitch linearly, and yaw/roll by wrapped-angle interpolation. The destination node supplies easing. A destination look target takes precedence over the previous node’s target; the target is not blended between actors.

Scene transport rebuilds the camera JSON. When a node has look_at, it writes that target and omits rot; the client therefore reparses the default rotation. Do not rely on authored roll or an authored fallback rotation surviving a targeted node through normal server playback. Untargeted nodes retain their rotation.

Gecko tracks sample elapsed scene time at 20 ticks per second and clamp to the animation’s length. This path does not apply the camera-only API’s loop/hold selection. Missing animation data produces no pose.

Targets

look_at and face accept an object using the fields below, a 3-number local position array, or the string walk_target. Other strings produce no target; null also means no target.

Object priority is walk target, then actor, then position. Actor targets use feet, so add an upward offset to frame the face. walk_target is meaningful for an actor cue; a camera node has no movement cue to supply that destination and cannot resolve it. Target actor strings are not normalised by the direct data parser, while the editor and client transport normalise them; use the same already-normalised key everywhere.

Camera effects

Shake instances combine up to their strength cap; a new distortion replaces the current distortion. These are client screen effects, not changes to actor position. A late viewer starts only the remaining portion of an already-started effect, rather than replaying its full duration.

Actor tracks

Walk/sprint needs a path with non-zero length. A single point, or pos alone, does not form a walk from the actor’s current position. Movement does not snap an off-path actor to its first point; use an explicit pose when that cut is intended.

Path length divided by duration determines the requested speed; outside that band it is clamped and the loader reports a timing warning. The correction does not extend the cue window or scene length. A blocked actor, off-path start or too-short duration can still leave the actor short of its destination.

Movement cues run from their start through start plus duration, inclusive, when duration is positive. Overlapping cues are not rejected or merged; avoid giving the same actor competing movement instructions. Missing actors and missing animation IDs skip their action rather than rejecting the scene.

World events

Events are server-side and fire once when due. Sounds and particles use world broadcasting, and weather/time alter the world rather than just viewers’ presentation. Particle events support simple registered particle types without extra payload data; block/item-style particle parameters are not part of this format.

Subtitles and easing

Only one subtitle is active at a time; a new cue replaces it. Text and speaker strings are resolved as translation keys, with literal strings remaining usable. The subtitle overlay can render while the ordinary HUD is hidden. A late viewer resumes an unexpired cue partway through its reveal.

Easing names are linear, step, ease_in_quad, ease_out_quad, ease_in_out_quad, ease_in_sine, ease_out_sine, ease_in_out_sine, ease_in_cubic, ease_out_cubic, ease_in_out_cubic, ease_in_back and ease_out_back. Input is case-insensitive, trims whitespace and accepts hyphens/spaces as underscores; compact names such as easeInOutQuad are also recognised. Unknown names fall back to linear.

Validation

The parser does not impose finite-number checks, maximum timeline length, maximum keyframe count or existence checks for every referenced asset. Use finite values and valid IDs; successful parsing does not establish that an actor, animation, sound or particle is available.

Normal scene-start transport sends a compressed authoring draft, limited to 262144 compressed bytes on receipt, and at most 64 actor bindings with keys up to 64 characters. This is a compressed-size bound, not a decompressed-memory limit. Client reconstruction rounds many vector, rotation and effect values to 3 decimal places, normalises target keys and discards unknown fields. Keep timelines within that transport budget and avoid depending on finer precision.

Reloading

/reload rebuilds the server scene catalogue and increments its revision, including reloads with errors. Starting a scene sends its current definition and resolved actor bindings; clients do not need the server data pack locally for native tracks. Gecko camera animations and other visual assets still belong in client resource packs.

Active server playbacks retain the scene object they started with. Reloading a definition changes later starts, not the existing timeline. Restart the scene to inspect changes, and reload client resources separately after editing camera animation assets.

Related

• Cinematic scene runtime — triggers, viewers, actor authority and saved history.
• Camera animation assets — the resource format used by Gecko camera tracks.

Emoji data defines stickers used by emoji cues. NPC assets covers NPC animation resources, and Developer editor preferences explains the shared editor theme controls.