Sequencer

The Sequencer is a multi-object cinematic timeline. A Sequence asset stores what moves, when, and through which camera. A plSequencePlayerComponent plays it back in game. This page explains how to use it.

Getting started

Install and enable the plasma.sequencer package in your project. It supplies the Sequence asset editor and the runtime Sequence Player component.

1. Create a Sequence asset (Animation category) and open it.
2. Pick a context scene from the toolbar. The scene is cloned into the Sequencer as temporary objects, so editing here never touches the scene file. Saving the scene re-clones it.
3. Select an object in the scenegraph and press + Binding. A binding is a named reference to that object, resolved by name path at runtime.
4. With the binding selected, press + Track and choose what to animate.
5. Arm ● AUTO-KEY, scrub to a time, and move the object with the gizmo. Keys are recorded at the playhead.
6. Drop a plSequencePlayerComponent in your level, point it at the Sequence, and call Play(), or tick PlayOnStart.

warning

Auto-key is a safety catch, not a convenience. With it off, the context scene cannot be edited from the Sequencer at all, because an edit would otherwise be silently discarded when the scene is re-cloned. If a gizmo drag reports “Auto-Key is off”, that is the toggle, not a bug.

Rows

The outliner on the left and the lanes on the right share one row space: row N on the left is always lane N on the right.

Camera Cuts: sequence-level. Which camera the shot is seen through.

Events: sequence-level. Named messages fired at the game.

Sequence Audio / Animation / Sub-Sequence: clips attached to nothing in the scene: music, voice-over and stingers.

Bindings: one per bound object. Shows a grey summary of every key beneath it.

Position / Rotation / Scale: one row per vector, expand for X/Y/Z.

Component properties: anything reachable by reflection.

Colour: a gradient ramp rather than a curve.

Adding tracks

+ Track offers Position, Rotation and Scale directly. Property… opens a searchable list of every animatable property on the bound object, its components, and its descendants. A binding onto a group is normal, and its components usually sit on the children. With no binding selected, + Track offers sequence-level clip lanes instead.

Editing

Gesture	Does
Click a key	Select it. Its curve appears in the Curve Editor dock.
Ctrl+click	Add / remove from the selection.
Drag empty lane space	Box-select every key inside.
Ctrl+A	Select all keys.
Drag a key	Move the whole selection. Only the grabbed key lands on the snap, and the rest keep their spacing.
← / →	Nudge the selection one frame.
Ctrl+C / Ctrl+V	Copy, then paste as a group at the playhead.
Del	Delete the selection.
Double-click a lane	Insert a key at that time, valued at whatever the track already holds, so keying never moves anything.
Right-click	Menu for whatever is under the cursor: key, clip, cut, marker or empty space.
Wheel	Scroll the lanes.

Retiming

Select two or more keys and a band appears under the ruler with a handle at each end. Drag one and every selected key scales its distance from the other end, so a beat stretches or compresses without changing its internal shape. The factor is shown live.

Ease

Right-click a key selection → Ease: Auto, Linear, Ease In, Ease Out, Ease In/Out. Applied to both tangents of every selected curve key. Colour stops and events have no tangents and are skipped.

Markers

Double-click the ruler to name a moment. Markers draw as teal flags with a dotted line down every lane, and everything snaps to them (keys, clips, cuts and the playhead) in preference to the frame grid. Drag to move, right-click to delete.

Colour tracks

Colour is driven by a gradient, not a curve, so a colour lane paints the evaluated ramp over an alpha checkerboard. Its keys are swatch diamonds on the ramp. Clicking one opens the colour picker, with alpha and HDR. The lane and the viewport follow the dialog live, and Cancel leaves the undo stack untouched.

note

A colour key is one RGBA+intensity sample, not three independent stops. The gradient's colour, alpha and intensity channels are always written together, because otherwise dragging a key would tear it into separate stops that drift apart. An HDR pick is split on the way in: the brightest channel becomes the intensity multiplier.

Cameras

Right-click the Camera Cuts lane to cut to a camera at the playhead. A cut holds the camera until the next cut starts. Drag a cut to move it, or drag its right edge to extend its tail.

Overlap two cuts to blend them. Drag one cut's tail past the next cut's start and the overlap becomes a crossfade, drawn as a diagonal wedge. There is no blend-length field: the overlap is the blend.

Timing diagram: the overlap from 2 to 3 seconds sets the blend duration.

Pilot in the transport views through the active cut's camera while scrubbing, blend included. Each cut renders a thumbnail of what its camera sees at that moment. A cut whose camera cannot be found paints red and says camera not found rather than silently doing nothing.

Clips

Clips are bars rather than keys, one lane per kind. Add a lane from + Track ▸ Clip Lane, then right-click the lane or double-click it to add a clip. Drag to move, drag an edge to trim.

Kind	Payload	Runtime
Audio	PlayTrigger / StopTrigger, chosen from the project's audio triggers	Drives a plAudioTriggerComponent, created on demand
Animation	Clip: an animation clip asset	Drives a plSimpleAnimationComponent, created on demand
Sub-Sequence	Sequence: another Sequence asset	Drives a nested plSequencePlayerComponent

Audio clips draw the real waveform of the sample behind their trigger, and take its length the first time a trigger is set. A hand-tuned length is never overwritten by a later trigger change. Use right-click ▸ Fit to Trigger Length to re-fit deliberately. Pressing Play in the transport sounds the audio, while scrubbing stays silent because dragging the playhead would otherwise fire a burst of overlapping one-shots.

Bindings that break

Bindings resolve by name path. Rename or move the object and the binding turns red with a missing: <path> subtitle. Right-click it → Rebind to Selected Object: pick the object in the scenegraph and the binding re-points, keeping all its tracks and clips.

note

An object with no name cannot be bound, because the sequence has nothing to search for at runtime. Name it in the scene, save, then bind.

Playback in game

plSequencePlayerComponent properties: Sequence, PlayOnStart (default false), Loop (default false), Speed (default 1). Scriptable: Play(), Pause(), Stop(). It sends plMsgSequenceFinished when non-looping playback reaches the end, and fires the event track as plMsgGenericEvent.

Bindings resolve below the component's own object by default, with a fallback to the world's top-level objects for scene-root paths. Call the C++ method SetBindingRoot() to resolve them below an explicit object, such as a spawned prefab. This lets one cutscene asset drive different instances.

warning

Stopping restores what it changed. Cameras go back to their original usage hints and poses, running clips are stopped. A sequence interrupted mid-blend does not leave a level camera displaced.

Snapping

The snap mode in the transport applies to every drag: keys, clips, cuts and the playhead.

Mode	Quantises to
Frame	1 / FPS. The default.
Half Frame	Half a frame, for offsetting against the beat.
Free	No snapping, full tick resolution (4800 ticks per second).

Markers override all three: anything dragged within a few pixels of a marker lands exactly on it.

Render to disk

Open Render to Disk from the Sequencer to capture the sequence as frames or an encoded movie.

Add camera cuts covering the entire sequence first. Capture stops with a warning if no camera cut is active at a frame.

1. Choose an Output folder dedicated to this render.
2. Choose Resolution (720p, 1080p, 1440p or 2160p) and Frame rate (24, 30 or 60 fps). Defaults are 1080p and 60 fps.
3. Choose PNG sequence only, or an available video encoder. Media Foundation offers H.264 MP4 on supported Windows machines. ffmpeg appears only when an available installation is found. The dialog does not install it.
4. For video, choose an available Codec and Quality: Draft, Review, Delivery or Master. The default quality is Delivery. Codec choices depend on the encoder installed on the machine.
5. Leave Also keep the PNG frames enabled to retain the frames as well as the movie. Press Render and monitor progress. The same button cancels the render.

note

Rendering advances the world one fixed simulation step per frame, capturing particles, physics and animation. Start at the beginning of the sequence so simulation history is available. The render dialog currently warns that Animation and Sub-Sequence clips are not dispatched in this capture path, so test those shots in runtime playback separately.

To play a rendered movie inside a game, import it as a Video asset.

Troubleshooting

Symptom	Check
Sequence asset type is missing	Enable the plasma.sequencer package and its editor plugin.
Gizmo edits are blocked	Arm Auto-Key before editing the cloned context scene.
A binding is red	Name the target, save the scene, then use Rebind to Selected Object.
A camera cut is red	Check that the camera still exists at the bound name path.
Audio is silent when scrubbing	Use Play to preview audio. Scrubbing intentionally stays silent.
A movie encoder is missing	The dialog lists only backends and codecs available on this machine. PNG output is available independently.