The scene-node id or ids performing this action, reusing ids from staging.
A list applies the same verb to several actors in unison (a chorus line, a
crowd, synchronised dancers) instead of repeating the action per actor.
Every id must be a staged scene node, and a list must be non-empty with no
duplicates. Only a frame action names a camera, and it names exactly one
as a string.
Length in seconds, finite and > 0 with start + duration inside the
shot, or "auto" to let the engine pick a natural duration (a stride
cadence, a punch's snap, a projectile's flight time). The reference
synthesizer sizes an "auto" clip itself, while performShot's overlap
check and an attachTo treat the span as running to the shot end, and a
frame as running until the next camera move. An "auto" action may not
start exactly at the shot end, which leaves it no span.
OptionalfocalLens intent in millimetres, full-frame equivalent (24 wide, 50 normal, 85
portrait), finite and > 0. Structural intent only: it is copied into
shot.cameraIntent, while the scene camera's fovY stays the geometric
truth and the solve never reads it. Omit when the lens is not a
directorial choice.
OptionalfocusThe lens subject, which may differ from the framed subject on.
performShot records the world point in shot.cameraIntent at the shot
opening, or at the pull's first mark when focusPull is present.
OptionalfocusTimed focus pull from the explicit focus subject to another lens subject.
The frame action's interval contains both marks. A downstream host can
read these lens marks independently of the camera path.
Finite seconds from the first mark to the second, strictly positive.
Finite seconds from the frame action's start, at least zero.
Positional lens subject at the second mark.
How tight the framing is.
OptionallookaheadFinite nonnegative seconds of aim lookahead for a "follow" move.
At a camera key, translation follows the subject's current position and
rotation aims at the subject this far ahead, capped at the shot end.
Omission or zero aims at the current position. The frame action gate
rejects this field on other moves.
How the camera behaves over this span.
What it frames and tracks.
OptionalphysicsFree-text acknowledgment of a deliberate physical implausibility, such as
"defies-gravity" or "intentional-clip", meant to stop the engine's
warning-severity plausibility feedback (see
IAutoMovieConstraintViolation.severity) from re-firing on this
action. No engine or production path reads this field: the plausibility
detectors take their own physicsIntent argument, and no shot pipeline
calls them, so setting it changes nothing today.
OptionalregionThe body region this action drives (AutoMovieBodyRegion). Actions
whose masked content is disjoint compose concurrently (walk while waving
while looking), and actions sharing content take turns. Omitted, the
engine's actionRegion infers it from the verb and, for gestures, the
kind: locomote is fullBody, because the shipped gaits drive hips,
knees, and contralateral arms; gesture and reach are upperBody;
lookAt and the nod and shake gestures are head; emote is face;
the bow, crouch, kick, stagger, jump, and draw gestures and
every other verb are fullBody. Overlap is judged on the content
surviving those masks (root, bones, expression), so a fullBody gait
still layers with a disjoint head-only lookAt. The engine masks the
synthesized clip to the chosen region and performShot reports content
the mask drops, so override only when the natural region is wrong for the
staging. Camera (frame) and attachTo actions ignore it.
OptionalrepeatPlay the synthesized motion this many times back to back, a positive
integer defaulting to 1: a step repeated on the count, an idle sway.
compilePerformance concatenates the synthesized clip that many times, so
the motion runs repeat clip lengths, while performShot's span and
overlap checks read only start + duration.
Seconds into the shot when it begins, within [0, shot duration].
Selects camera framing as the action family.
The camera is an actor; this is how it moves. A list of camera actions composes a move that changes mid-shot ("follow the charge, then hold static on the fall"), which the engine realizes against the target as the shot's camera-node clip (
cameraMotion).performShotrequires theactorto be exactly one staged camera and allows one live camera per shot. Its moves may not share a start or overlap; an"auto"duration runs until the next move starts, or to the shot end. Theontarget and anyfocusmust resolve to a point (node, live bone, point, or group), with formation groups allowed for lens targets.compileCameraMoveowns the path eachmovetakes.