Cinematic Sequencer
A sequence is a timeline that animates anything in a scene: objects, bones, lights, any component field, animation clips, cameras, sounds and physics. It is a JSON file in the project's Sequences folder (Sequences/<name>.sequence.json, format ttr.sequence), so an agent can write it key by key and a person can edit it in the Timeline. A sequence { file "bottle_fight.sequence.json" autoplay true } component plays it when the game starts; game.playSequence("name") plays it from a script.
Times are story seconds. The sequence's time_scale curve says how fast story time runs: 1 is real time, 0.15 is slow motion. While it plays, physics, animation, particles and script clocks all slow together, and every key stays in story time.
The tools
| Tool | What it does |
|---|---|
create_sequence | Make (or resize) a sequence, or write a whole one from JSON. |
add_track | A track with options: after (hold / release), group, layer (override / additive), new (another layer on the same object). |
set_key | A key on a track: position, rotation, scale, value, weight; channel: "position.y" sets one number. falloff reshapes the keys around it. |
edit_key | The curve editor: tangents (auto, flat, linear, step, free with in/out), an ease preset, move_to (retime), sample (read the curve). |
add_clip | An animation clip on a character, cross-faded in. |
add_event | A timed event: launch, release, ragdoll, particles, shatter, sound, send, say and every cutscene event. |
add_camera_cut | A cut: eye/look or a camera object, fov or lens (mm), to (a move: dolly, truck, crane, orbit, pan, tilt, focus pull), shake (hand-held), focus, aperture. |
set_time_scale_key | A key on the slow-motion curve; ease: "smooth" ramps in and out of it. |
add_shot | Another sequence inside this one from t (nested up to 8 deep). |
record_physics | Simulate one object (a throw, a fall, a ragdoll) and bake it into keys you can then edit. |
get_sequence, scrub_sequence, play_sequence, render_sequence | Read it, see any moment, play it, render frames (and video: true for an mp4). |
Slow motion and a thrown bottle
The Bottle Fight scene (Projects/Sandbox/Scenes/Bottle_Fight.ttrscene) is built entirely with these tools by Lab/sequencer/make_proof.sh:
- Ava's and Ben's clips and expressions (
add_clip,set_keyonanimator.expression). - The bottle keyed in her hand, then
launchat 2.0 s with a velocity and spin. set_time_scale_key1 → 0.15 → 1 around the flight.- Camera cuts: a two-shot, a close-up on Ava, a camera that follows the bottle, the impact, the aftermath.
record_physicsbakes the flight into keys;set_keywithfalloffmoves where the bottle goes, keeping the arc smooth.shatterwhen the keys end: the bottle breaks into shards that fly on under live physics, with asoundcue.render_sequencerenders it through the cameras.
Physics: record, edit, blend
record_physics plays the scene up to from, lets physics take the object and records every tick until to (slow motion is recorded slowed, so it keeps more samples). It keeps only the keys a straight line between neighbours doesn't already give. Playback is then the keys, the same on every run; a launch or ragdoll inside the recorded stretch is not run again.
To change the result without touching the recording:
set_keywithfalloffmoves one key and the ones around it smoothly.- An additive layer (
add_track {new: true, layer: "additive"}) adds offsets on top of the baked arc. - An override layer with
weightkeys cross-fades from the baked take into hand keys and back. after: "release"hands an object back to physics where its keys end, moving as the curve was.
Cameras
Each cut holds until the next. blend eases from the previous cut. to moves the camera over the cut: absolute (eye, look, fov, lens, roll) or rig moves relative to where the cut starts (dolly, truck, crane, orbit, pan, tilt), and focus pulls (focus, focus_distance, aperture). shake makes a hand-held camera that wobbles the same way on every run. The renderer does not yet draw depth of field: focus and aperture are computed and reported, ready for when it does.
The Timeline
With the Arcwright preview on (the default), the editor's bottom dock has a Timeline tab. Pick a sequence, drag in the ruler to scrub (the viewport shows that moment; Camera looks through the sequence's camera), press play to watch it at clock speed with its slow motion. Click a track to see its curves; drag a key along its row to retime it, or up and down in the curve view to change its value. Edits are saved to the file at once and checked the way the tools check them.