Cinematic Shot Flows

A shot flow is authored coverage that is subject-agnostic: it names roles rather than actors, so one flow performs for any cast, anywhere. Everything that plays authored camera work — a runtime call, a Sequencer section, the editor Stage — reads the same asset and drives the same flow cursor, so what you approve in rehearsal is what plays in the game.

There is no DataTable and no JSON import for flows. Discovery is tag → asset: FlowTag is registry-searchable, so the camera registry finds the asset from the Asset Registry with nothing to configure.

Two flows ship with the plugin, under /AgenticGameplayCamera/Cinematic/Flows/:

The Asset

The asset's own Validate is structural only — a valid tag, at least one segment, every subject role declared, no duplicate role names — and that is what the editor's data validation reports. Whether the film grammar is any good is a separate judgement, made by the evaluator against a rehearsal.

Roles

Register subjects once and let the flows bind themselves:

Subsystem->RegisterSubject(SpeakerTag, SpeakingActor);
Subsystem->RegisterSubject(ListenerTag, ListeningActor);
Subsystem->PlayShotFlowByTag(DialogueFlowTag, FAgenticFlowBindings());

Segments

A segment says when a shot starts, how it arrives, when it ends, and which of its values animate.

A new segment starts out physical and composed: a 35 mm focal length, dolly-only group adjustment, head-room on, and a little lead room. So a flow shot moves the camera to its framing rather than zooming to it.

Ending a Segment

For Signal and External, Duration is only the estimate used for seeking, duration reporting and the Sequencer projection. It is never a timeout — a held segment holds.

A Duration segment's overshoot carries into the next segment, so boundaries never round up to a frame.

Transitions

Cut or Blend, with a time and a curve (the same curve vocabulary as the gameplay side: linear, ease in/out, overshoot, bounce, snap, anticipation, smoothstep, elastic, expo-out…). A cut has zero duration by definition.

Pins

A pin replaces the framing solve for its segment: placement, movement model, smoothing and the collision probe all stand down and the authored poses are honored exactly. Corrections still run. Key times are segment-local seconds, not normalized — a signal-held segment has no known length, so clamping at the last key is the honest answer.

A pin is world-space and therefore level-bound. Curves port to any cast in any set; a pin does not.

Shot Size

Two fields can name a shot's size, and they are not the same thing:

• Framing.Size is the control the distance solve reads: aim at this band.
• Intent.SizeStart is the assertion the contract checks: this shot is a close-up.

Explicit control always wins; an undeclared control falls back to the intent, so a shot that only asserts its size is still aimed at that band. A genuine disagreement — both declared and different — is reported as a warning rather than silently resolved.

Bands are frame height in centimetres at the subject's depth. They are contiguous and total, and a boundary belongs to the tighter size.

The solve aims at a band's geometric centre so the result classifies back to the same size. When a pose is unachievable, a fixed degrade ladder runs — loosen the size one band, swap the orbit side, raise the height — and every step it took is recorded rather than hidden.

Curves

The curve vocabulary is fixed and closed; an unknown name is rejected, not ignored. Every curve is relative to the pair frame — origin at the weighted group centre, x along the line of action, z up — so the same move plays for any two actors anywhere. A present curve overrides the shot's static value for that segment; an absent one leaves it alone. Curves run first, so a movement model composes on top of them.

Movement Models

A shot holds one primary model and any number of layers. A model is a pure function of segment-local time and never touches the world: where a move needs level content it publishes a request naming roles, and the world-aware caller fulfils it.

A layer placed in the primary slot is rejected by the validator, not quietly ignored. The primary runs first, then each layer in author order.

There is deliberately no Crane model — a crane is the Height, Distance and Orbit curves on a segment.

Policy

Interruption

The policy is read from the flow currently playing, so an insert can declare its own answer.

Interrupting never releases a segment's signal hold, so raising a signal keeps its one meaning.

Corrections

Four correction classes ship, each declaring its own tag:

Each has bEnabled and a Priority (lower runs earlier; 100 by default). A correction reports true only when it actually moved the camera, which is what makes the trace a record of what fired rather than a list of what was configured. This is the same source-agnostic pipeline the gameplay corrections use.

Occlusion is not a correction: a blocked pose goes through the degrade ladder and is reported as occluded frames on the trace.

Playback

Reach the subsystem with Get Cinematic Subsystem (from a player controller) or its world-context variant, then:

All of these are Blueprint-callable.

The three doors — a direct call, a Sequencer flow section, and the editor Stage — drive one player, so behavior does not fork by entry point. When an external driver such as Sequencer owns the clock, it takes time control and advances the flow with its own frames.

Playback is deterministic: the same flow, the same tick deltas and the same signals produce the same events.

What the Trace Reports

One trace entry is opened per segment entry, so a looping flow records each pass. Every field is measured, never requested: the transition kind and time, when the segment was entered, how long it held, which side of the line the camera was on, the requested and solved size, how many degrade steps ran, whether the pose was still unachievable, the occluded / clipped / out-of-reach / solved frame counts, and which corrections fired.

A flow ends as Completed, Stopped, Replaced, Skipped or Interrupted, and the most recent completed trace stays readable afterwards.

Authoring and Rehearsal (Editor Only)

The Stage is a rehearsal room shipped as /AgenticGameplayCamera/Stage/L_Stage: it spawns stand-ins for a flow's roles, plays the authored sequence for real, and can capture a PNG sequence and a WAV of the session with measured frame intervals. Its settings live under Project Settings → Plugins → Agentic Camera Stage.

The Stage, the flow catalog and the authoring tools live in the Editor modules (AgenticCameraEditor and AgenticCameraToolsets), so they are absent from a packaged game entirely. Rehearsal is a development activity; only the runtime flow playback, which lives in the Runtime module, ships in your game.

With Epic's Experimental ToolsetRegistry plugin enabled, the same surfaces are exposed to an agent as toolsets: list the flows, describe one (its roles, per-segment shape, exposed curves, staging hint, and the schema the authoring calls accept), and export the whole catalog as JSON. The catalog is generated from the flow assets on every call and never stored, so it cannot drift from what would actually play. Export is one-way — nothing reads a flow back from JSON.

Without ToolsetRegistry, IsAvailable reports false and the toolsets are simply absent. The camera and the flows behave identically.