Update to Picsart
Snapshot Nov 11, 2026 · 00:08 UTC · version 2.5.0
Collection source: downloaded plugin package.
Instructions updated for scene-animation-reference
Skill instructions — Now says: 55.128.2 second. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` / `scale([t])` is that same instant (see "Bind a supported...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Skill instructions
Nov 7, 2026 · 00:09 UTC
55.104.0 second. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` is that same instant (see "Bind a supported property instead of copying its track"). fits; build by hand only when it does not.
Nov 11, 2026 · 00:08 UTC
55.128.2 second. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` / `scale([t])` is that same instant (see "Bind a supported property instead of copying its track"). `getSocket` and `getSocketDirection` on a ...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -4,7 +4,7 @@ metadata: category: authoring version: '1.19' - ported-from: motion-mechanics 1.19 at 55.104.0 + ported-from: motion-mechanics 1.19 at 55.128.2 --- # Saying motion in a scene @@ -300,11 +300,11 @@ **Reading another value at a time.** `ctx.composition:getParameters():<name>([t])` is a parameter at `t`, seconds on the reader's clock (default now): `p:headTurn(time - 0.25)` trails a quarter -second. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` is that +second. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` / `scale([t])` is that layer's placement at `t`, seconds on the reader's clock with the layer's own clock applied: `position(time - 0.2)` trails it by 0.2 s. The layer is one of the same composition; a timed read of a layer that plays on another composition's clock fails the frame. Without `t` it reads this -same instant (see "Bind a supported property instead of copying its track"). +same instant (see "Bind a supported property instead of copying its track"). `getSocket` and `getSocketDirection` on a layer read a placed character's published sockets (`character-rigging` "Standard sockets"). **In a DEFINITION** (a look, a transition, a decoration) `{param}` splices the definition's own scope into the expression text, so the shape stays parametric: @@ -375,7 +375,7 @@ A character that walks, waves or jumps from a few looped keys, a shape's outline that morphs, bends or is swapped (`vertices` tracks, `deformers`, outline expressions), bent limbs and two-bone `ik` foot targets are all in `character-rigging` as well. Pose the catalog rig (`rig-humanoid`, `rig-face`) when it -fits; build by hand only when it does not. Within a shape's `items`, and a group's `contents`, the +fits; build by hand only when it does not. A humanoid rig holds a prop itself through its `held` parameter, and a `reach` constraint on its instance layer (`{"type": "reach", "socket": "rightHand", "target": {"layer": "ball"}, "mix": 1}`) puts a hand, foot or the `seat` on a stage point: both in `character-rigging`. Within a shape's `items`, and a group's `contents`, the first item paints on top, as After Effects stacks layers: list a face's mouth and eyes before the head they sit on.
Full technical diff · 1 changed fields
changed /skill_md_contents
"---\nname: scene-animation-reference\ndescription: How a scene expresses motion — preset catalogs, layer animations and transform stacks, easing and spatial tangents, Lua expressions, shared path phase, text on a curved or closed path, named actions mixed on a placed scene, depth and the composition camera (2.5D, cards that flip or fan out in depth under an orbit, a 2D film camera's pan, push-in and parallax), motion blur, held drawings (animation on twos), transition firing, and parameter drivers that keep a character alive on their own (eyes looking around, blinks, breathing, hair and ears that follow through, a tail that settles, whiskers that wiggle), with a pointer to the walk, wave and jump cycles of a cartoon rig. Use when motion needs authoring or validation, a character or object should glance, blink, breathe or sway by itself, objects need editable path offsets, text must follow a baseline, a scene validates but renders wrong, or a preset is rejected for the content kind.\nmetadata:\n category: authoring\n version: '1.19'\n ported-from: motion-mechanics 1.19 at 55.104.0\n---\n\n# Saying motion in a scene\n\nThe decision — what a beat is for, how long, which register — is `picsart_scene_recipe motion-intent`.\nThis is the other half: how the format says it, and the places where the obvious spelling is the\nwrong one. For the relationship across beats or the choice of seam mechanism, decide first with\n`picsart_scene_recipe motion-scene-continuity`, then return here for syntax. For semantic grouping, container\ngrowth and sibling reflow, first use `picsart_scene_recipe linked-element-motion`. A common placement owner\ndoes not imply automatic layout. The constructions below need verification in the actual scene.\n\n## Named actions on a placed scene\n\nWhen a placed scene declares fixed motions in its root `actions` map (imported bone timelines,\nparameter motions, authored cut-out poses), its `scene_ref` layer plays and mixes them through\n`content.animation`: a list of entries with `action`, `trim`, `speed`, `loop`, `weight`, `start`,\n`duration`, `fade`, `mode` (`replace` or `aggregate`) and `tier`. A catalog rig's motion presets\nwrite `scene_ref.parameters` bindings instead; those are live controls, not actions. Layer\n`animations` move the whole rig. Mixing, tiers, crossfades without a rest dip, step channels,\n`blending: \"pass_through\"`, a complete walk→idle scene and every refusal are in\n[named-actions.md](references/named-actions.md); the schema is `picsart_scene_capabilities` with\n`sections: [\"schema:ActionAnimation\"]`.\n\n## Two catalogs, two ways in\n\nThey look alike and are applied differently. Getting this wrong is the commonest first failure.\n\n| | Motion looks | Motion presets | Text animations |\n|---|---|---|---|\n| What | entrance/exit (`role: in`/`out`) `fade`, `slide`, `zoom`, `spin`, `wipe`, `blur`, `flip`; entrance `pop`, `flash`; loops `float`, `sway`, `shake`, `pulse`, `glow_pulse`, `blink`, `rotate`, `clockwork`, `ken_burns` | entrances `fade_in`, `slide_in`, `zoom_in`, `scale_pop`, `spring`, `rotate_in`, `blur_in`, `flip_in`, `reveal_in`; exits `fade_out`, `slide_out`, `zoom_out`, `rotate_out`, `blur_out`, `reveal_out`; emphasis `tap_pulse`, `glow_pulse`, `shake`; atmosphere `ken_burns`, `breathe`, `float`, `sway`; paging `step_slide`; secondary motion `settle`, `wiggle` (also on a shape group with `item`); parameter drivers `follow_through`, `random_pulse`, `random_hold`, `cycle` (write a parameter, below) | `typewriter`, `fade_in_chars` (`grow` makes each letter grow in too), `slide_up_lines`, `flicker_chars` (+ ambient ones, below) |\n| Applied with | `picsart_scene_apply_preset` with `look:<id>` (iOS `applyLook`) and `params` (`role`, `length`, …); a window `start`/`duration` is set on the `looks[]` entry with `picsart_scene_patch` | `picsart_scene_apply_preset` with `motionPreset:<id>` (iOS `applyMotionPreset`) | name it in `content.animations[]`, or bake an entrance with `picsart_scene_apply_preset` and `textAnimation:<name>` |\n| Lands in | the layer's `looks[]` | the layer's `animations` / `transforms[]` / `effects`, or `constraints` for layer follow-through | the text content's `content.animations[]` |\n| Named in the document? | yes — `{ \"look\": \"fade\", \"params\": { \"role\": \"in\" } }`, so an editor shows and swaps it | no — the tool expands it into ordinary tracks or layer constraints | yes — `{ \"preset\": \"typewriter\", \"params\": {} }` |\n\n**A preset or a look.** A motion preset is a starting point: it writes ordinary keyframes (and\neffects) that the agent or the editor user then owns and edits keyframe by keyframe. A look stays a\nnamed entry an editor shows and swaps as a whole. Use a preset when the keyframes will be edited\nafterwards; use a look when the motion should stay a named, swappable entry. A one-shot beat at a\nchosen moment (`tap_pulse`, `spring`, `scale_pop`) is a preset.\n\nA look applies to the kinds its `appliesTo` lists. Most motion looks take `color` and `shape` layers\ntoo (`blur` and `flip` take `color` but not `shape`; `wipe`, `flash`, `blink`, `rotate` and\n`clockwork` take neither). For a look that does not list the kind, wrap\nthe layer in a scene asset and apply the look to the `scene_ref`.\n\n`content.animations[]` is a mixed source list: each row is either a named `{preset, params?}` reference\nor a concrete per-glyph `{transform, selector}` entry. Resolution expands every named row before the\nrenderer sees it. Naming keeps the choice editable and can reach a `type: \"text_animation\"` definition\ndeclared in the document's own assets; baking with the tool writes the concrete entries instead.\n\n**Content-kind traps.** `ken_burns`, look or preset, takes `media` / `scene_ref` only, and a look\nor preset on a kind outside its `appliesTo` is `preset_kind_mismatch`. A plain text layer may name either an entrance preset or an **ambient** one\n(`drift`, `flicker`, `hop`, `shake`, `sway`, `throb`, `transform`, `wiggle`). Ambient motion uses\nthe layer's duration as its resolution window; its mode decides whether it is static, plays once,\nloops, or ping-pongs. It selects every glyph. A caption can use the same ambient definition through\na decoration row's `place: \"text\"` field when it needs line/emphasis/highlight selectors instead.\n\n`applied` in the result names the preset once; `entryCount` says how many animator entries it\nappended (a multi-decorator preset like `slide_up_lines` appends two).\n\n### What `picsart_scene_apply_preset` writes\n\n- **Camera presets** (`appliesTo: [\"camera\"]`, e.g. `motionPreset:push_in`, `dolly`, `orbit`) move the\n root composition's camera when `layerId` is omitted, or the camera of the `composition` or\n `scene_ref` layer it names.\n- **Effects** can be confined to a detected region with `mask`: the effect's `supports.effects` row\n says whether it takes one, and the detectors are listed under `supports.maskProviders`.\n- **Text animations** start at the text layer's local time 0: set the layer's `start` to reveal it\n later. An ambient text animation is not baked; it is attached by name in `content.animations[]`.\n- **Looks** wrap the layer's content in an isolated nested composition, so the look treats the\n composited result as one image. By reference (the default) nothing is baked: preview, translate\n and query expand it when needed, and `picsart_scene_resolve_looks` bakes a self-contained scene.\n `mode: \"expand\"` bakes it now: `transform`, `animations`, `blendMode`, `mask` and `motionBlur`\n move onto the wrapper, the layer's own effects apply once before the look, and a track clip bakes\n its whole `looks[]` chain and keeps its slot. A layer with `adjustmentLayer: true` takes no look.\n\n## Where a motion lives\n\nTwo places, and the choice is not stylistic.\n\n**`animations`** — the layer's own Placement tracks (`position`, `scale`, `rotation`, `z`,\n`rotationX`, `rotationY`, `opacity`, `anchor`). Pivots about the layer's own anchor. Always available.\n\n**`transforms[]`** — an ordered stack of motion components applied *outside* Placement, each with its\nown `id` and `animations` (`translation` / `scale` / `rotation` / `z` / `rotationX` / `rotationY` /\n`anchor`), evaluated in array order:\n\n```json\n\"transforms\": [\n { \"id\": \"entrance\", \"animations\": { \"translation\": { \"keyframes\": [ ... ] } } },\n { \"id\": \"breathe\", \"animations\": { \"scale\": { \"expression\": \"return value * (1 + 0.02 * math.sin(2*math.pi*time/3))\" } } }\n]\n```\n\nThe stack exists so **layout stays editable**: `transforms` carries motion (animations, presets) and\n`transform` is the placement a user or host edits. They compose, so editing placement never rewrites\nthe motion, and the motion follows the edit. That is why a `motionPreset:` preset applied with `picsart_scene_apply_preset` routes geometry here. One\ncomponent per motion layer also keeps each independently re-timeable, instead of one `scale` track\ncarrying an entrance and a breathe that can no longer be told apart.\n\nPositions follow After Effects: `transform.position` places the layer's `transform.anchor` in its\nparent's space (the parent layer's own pixels with `parentId`, otherwise composition pixels from the\ntop-left). An omitted `transform.position` is the composition's centre, for a child too: a child\nwith no `transform` sits half a composition into its parent's pixels, so give every child one\n(`[0, 0]` is the parent's origin, the pivot of an `empty` or a shape drawn about `[0, 0]`). An\nomitted component `anchor` is that anchor **where it currently sits**, following a `position`\nanimation and parenting, so a component scale or rotation turns the layer in place even while it\nmoves:\n\n```json\n\"transform\": { \"position\": [300, 300] },\n\"animations\": { \"position\": { \"keyframes\": [ {\"time\": 0, \"value\": [300, 300]}, {\"time\": 2, \"value\": [700, 300]} ] } },\n\"transforms\": [\n { \"id\": \"spin\", \"animations\": { \"rotation\": { \"keyframes\": [ {\"time\": 0, \"value\": 0}, {\"time\": 2, \"value\": 360} ] } } }\n]\n```\n\nMental model: a component is a parent null (After Effects) or a wrapper element (CSS) sitting on the\nlayer's anchor. With no `anchor` it rotates and scales about the layer's anchor wherever the layer\ncurrently is, and `translation` moves in parent pixels.\n\n- **Turn about a fixed point** — give the component an `anchor`: a fixed point in the layer's\n parent space, not the layer's own pixels. It replaces the pivot and does not follow placement edits.\n `anchor: [0,0]` pivots on the parent's top-left.\n- A component's `animations.anchor` is its pivot track, in the same parent space; a layer's own\n `animations.anchor` is layer-local, like `transform.anchor`.\n\n## Easing\n\n`linear`, `ease_in`, `ease_out`, `ease_in_out`, `step` — **plus** a parametric curve:\n\n```json\n\"easing\": { \"kind\": \"cubic_bezier\", \"control\": [0.175, 0.885, 0.32, 1.275] }\n```\n\nCSS convention: `x` stays in [0,1], while `y` may extend beyond it. A control ordinate is not the\nrendered overshoot percentage: the curve, endpoints and timing determine the actual peak. Query or\nrender the peak in the scene before deciding whether it suits the intended motion.\n\n**A keyframe with no `easing` is `linear`.** Use it deliberately for constant-rate travel or progress;\nuse an eased curve when acceleration or settling serves the beat. Easing belongs on the segment's\nstarting keyframe; the terminal keyframe has no following segment to ease.\n\n**Each component on its own.** On a vec2, vec3 or rect value, `easing` may be a list with one easing\nper component, in the value's order: a scale whose width snaps out while its height lags is one\ntrack, not two nested layers.\n\n```json\n\"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0, 0], \"easing\": [\"ease_out\", \"ease_in\"] },\n { \"time\": 0.6, \"value\": [1, 1] } ] }\n```\n\nThe list has exactly one entry per component, and `step` is never an entry (a hold keeps the whole\nvalue). A number or a colour takes one easing.\n\n## Path, separately from timing\n\n`inTangent` / `outTangent` on a `position` or `anchor` keyframe are `[x, y]` velocity handles\nrelative to that keyframe's value — AE motion-path handles. `easing` shapes the timing *along* the\npath; the tangents shape the path itself. Omitted means a straight line, which is why every\nunattended long move is one.\n\n```json\n\"position\": { \"keyframes\": [\n { \"time\": 0, \"value\": [200, 540], \"easing\": \"ease_in_out\", \"outTangent\": [120, -160] },\n { \"time\": 1.6, \"value\": [880, 540], \"inTangent\": [-120, -160] }\n] }\n```\n\nA handle on any other property is dropped.\n\nFor **a path driven by a separate phase**, use tangent keyframes plus\n`ctx:sampleBase(seconds)` on that same property. Read [Shared path phase](references/path-phase.md)\nfor a runnable scene, offset/clamp/wrap choices, clock and sampling limits, and executable checks.\nThis keeps position geometry editable without retiming the card's video. Ordinary timed movement\nstill needs only keyframes; this extra sampling is for independently controlled progress.\n\nFor **text on a curved or closed baseline**, use `content.textPath` rather than\none animated layer per letter. Read [Text on a path](references/text-on-path.md)\nfor geometry, animated offsets, combined character animators and validation. This is distinct from\nmoving an entire object along its position track.\n\n## Expressions\n\nFor an object that turns along its path, keep one authoritative position track and bind\n`animations.rotation.expression` to `positionDirection()`. Do not introduce an auto-orientation\nflag or copy the path into a separate heading track. The artwork's forward-axis correction belongs\nin `transform.rotation`; the expression adds it through `value`. This applies to arrows, vehicles\nand other path followers, not only cursors. Ordinary value reads do not request motion samples;\ndirection/velocity work is on demand when the expression calls it.\n\nRead Cursor-led action (fetch with `picsart_scene_recipe`, name `app-ui-animation`) and its direction reference\nbefore authoring the binding. Through MCP, fetch `picsart_scene_recipe` with `name: \"app-ui-animation\"`,\nthen its listed **Cursor actions and menus** reference. It contains the executable expression, coordinate\nand clock limits, hold/zero-direction behavior and validation. Check heading against independent\ntravel samples, including a changed path and a delayed instance; a valid expression and correct\npositions alone do not prove correct orientation. Use an explicit heading track only when the\nart direction deliberately differs from travel (banking, gaze, a stationary expression's held pose).\n\nA track can carry a Lua `expression` instead of, or on top of, keyframes. It must `return`, sees\n`value` (the keyframed base) and `time` in **layer-local seconds**, zero at that layer's start,\nand returns `Vec.v2(x, y)` for vec2 properties. Moving the layer's start moves the expression's\nonset too; do not subtract that start again. For a nested scene, map root time into the containing\ncomposition first, including reference trim/speed, then subtract the child's start. Keyframe\n`timeMode` does not turn an expression's clock into root time. Check delayed/nested instances with\n`picsart_scene_query_layout` at their mapped start and later moments.\n\n### Bind a supported property instead of copying its track\n\nPrefer a common composition owner for a rigid widget. For a genuine one-way dependency between\nseparate layers, Lua can read a sibling's evaluated Placement, for example on the follower's\nposition track:\n\n```json\n{ \"expression\": \"return ctx.composition:getLayer('driver'):getPlacement():position() + Vec.v2(0, 24)\" }\n```\n\nThis reads an authored sibling id in the same composition; it is not a flattened query id. The\nresult is Placement in that layer's parent space, not its root-space painted center or the result\nof every `transforms[]` entry. Use this offset formula only with compatible parent spaces, anchors\nand intended Placement motion. For shared transform-stack motion, use an owner instead. Self-reads\nof the property being defined and cyclic dependencies are refused. Consult the current expression\nschema for available getters; there is no arbitrary live shape-size or text-metrics getter.\nUnlike `$eval`, this is a per-frame dependency. Validate and query the actual delayed/nested instance;\nlocal `time` formulas on separately started layers need clock mapping even when their text matches.\n\nA value that follows a parameter through drawn poses is a `by` track (see `character-rigging`, \"Poses keyed to a dial\"),\nnot an expression that reads the parameter and interpolates by hand.\n\nTwo compact time-expression uses:\n\n**Ambient motion that continues looping** for the beat's duration:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.15 * math.sin(2*math.pi*time/2))\" }\n```\n\nThe coefficient varies the base scale by ±15%. Its literal two-second period does not change when\nthe beat duration changes; adjust it explicitly to preserve a chosen cycle count. Inspect the\nresulting bounds, final phase and reading comfort.\n\n**A real spring** — a damped oscillation, which one `cubic_bezier` cannot express:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.35 * math.exp(-6*time) * math.cos(18*time))\" }\n```\n\nThe expression alternates around the base value with diminishing amplitude. Raise the\n`exp` coefficient to settle sooner, the `cos` coefficient for more bounces.\n\n### The `picsart.*` stdlib — the recurring shapes, already written\n\nThese are built in. Reach for them before\nhand-rolling the trigonometry. Call them directly as `picsart.<name>(...)`; an alias such as `local p = picsart` is not supported.\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, 0.3, 1, 0.7)\" }\n\"position\": { \"expression\": \"return picsart.jitter(value, time, 16, 11, 0.3)\" }\n\"rotation\": { \"expression\": \"return picsart.wiggle(value, time, 2, 4)\" }\n\"scale\": { \"expression\": \"return Vec.v2(picsart.oscillate(time, 1, 1.05, 2), picsart.oscillate(time, 1, 1.05, 2))\" }\n```\n\n- `picsart.oscillate(time, low, high, halfPeriod)` — smooth low↔high, starting at `low`, one half cycle\n every `halfPeriod` seconds. A vec2 property takes one call per component inside `Vec.v2`.\n- `picsart.jitter(value, time, ampX, ampY, step)` — deterministic shimmer around the layer's own base\n `value`, resampled every `step` seconds. Not random: same inputs, same frame.\n- `picsart.wiggle(value, time, freq, amp [, octaves=1, ampMult=0.5, seed=0])` — AE's `wiggle`, fractal\n noise at `freq` wiggles/sec, per component on a `Vec`.\n- `ctx:loopOut(mode)` — repeats the track's keyed range past its last key. Key ONE cycle, loop it:\n `\"cycle\"` restarts every range (a breath, a foot's roll), `\"pingpong\"` plays every other range\n backwards (a wave), `\"offset\"` restarts each range shifted by its last-minus-first value (anything\n that travels: a stride, a walking body), `\"continue\"` extends along the slope at the end it leaves.\n `{\"keyframes\": [...], \"expression\": \"return ctx:loopOut('cycle')\"}`. Before the first key the\n track holds that key.\n- `picsart.cycle(time, waveform, from, to, period, phase [, variation, seed])` — a `\"sine\"`,\n `\"triangle\"`, `\"saw\"` or `\"square\"` wave: `picsart.cycle(time, \"sine\", 0, 1, 3.5, 0)`.\n- `picsart.randomPulse(time, from, to, minInterval, maxInterval, attack, hold, release, burstChance, seed)`\n — seeded random events, each eased `from` -> `to` and back: a blink.\n- `picsart.randomHold(time, from, to, minInterval, maxInterval, transition, seed, channel [, centerBias, half])`\n — a seeded random value held, then eased to the next on `picsart.randomPulse`'s timing; `half`\n `\"both\"`, `\"positive\"` or `\"negative\"`: a glance.\n- `picsart.follow(time, read, frequency, damping, amount, segment)` — a damped spring trailing `read(t)`:\n lag, overshoot, settle (hair, tails, a dangling arm). It follows PARAMETERS; see\n [Secondary motion](#secondary-motion-and-characters) for `segments`, one value per piece\n of a chain of any length.\n- `picsart.clamp(v, low, high)`, `picsart.linear|ease|easeIn|easeOut(t, tMin, tMax, v1, v2)` — AE's\n interpolation set, held outside `[tMin, tMax]`; `v1`/`v2` a number or same-arity `Vec`:\n `picsart.ease(time, 0, 0.4, 0, 1)`.\n- The four `picsart.cycle` / `picsart.randomPulse` / `picsart.randomHold` / `picsart.follow` calls are what the\n `cycle`, `random_pulse`, `random_hold` and `follow_through` presets write\n ([Parameter drivers](#parameter-drivers)). Apply the preset rather than writing the call.\n\n**Reading another value at a time.** `ctx.composition:getParameters():<name>([t])` is a parameter\nat `t`, seconds on the reader's clock (default now): `p:headTurn(time - 0.25)` trails a quarter\nsecond. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` is that\nlayer's placement at `t`, seconds on the reader's clock with the layer's own clock applied:\n`position(time - 0.2)` trails it by 0.2 s. The layer is one of the same composition; a timed read\nof a layer that plays on another composition's clock fails the frame. Without `t` it reads this\nsame instant (see \"Bind a supported property instead of copying its track\").\n\n**In a DEFINITION** (a look, a transition, a decoration) `{param}` splices the definition's own\nscope into the expression text, so the shape stays parametric:\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, {glow} * 0.3, {glow}, 0.18 / {speed})\" }\n```\n\n`{name}` there is a raw TEXT splice, not a typed lookup — it drops the param's number into the Lua\nsource, so surrounding arithmetic is Lua's. (Everywhere OUTSIDE an `expression`, `{name}` is the\ntyped scope lookup instead.) `picsart_scene_capabilities` lists the full stdlib.\n\n## Parameter drivers\n\nFour presets write a number parameter's `default`, applied with `picsart_scene_apply_preset`\n(`motionPreset:<id>` and `\"parameter\": \"<name>\"`); the layers read the parameter, so one value drives\nevery part that shares it.\n\nOn a cartoon rig (a `scene_ref` layer drawing `scene://rig-humanoid` or `rig-face`), pass the rig\nlayer as `layerId` and its control as `parameter` (`random_pulse` on `blink`, `cycle` on `breath`):\nthe track is bound on that layer, so each instance moves on its own. The rigs and `walk_cycle` are in\n`character-rigging`.\n\n| Preset | The value | Typical uses |\n|---|---|---|\n| `follow_through` | the swing of a damped spring trailing other parameters | hair, ears, tails, antennae, a dangling sign |\n| `random_pulse` | brief eased events at seeded random intervals (`minInterval`, `intervalSpread`, `attack`/`hold`/`release`, `burstChance`) | blinks (`eyeOpen` from 1 to 0), lamp flicker, twinkling stars, glitch hits |\n| `random_hold` | a seeded random value held, then a quick eased jump (`transition`) to the next, `minInterval` + `intervalSpread` apart; one `seed` shares the jump times, `channel` picks the value stream, `half` keeps its `positive` or `negative` side, `centerBias` gathers values mid-range | eyes looking around (`lookLeft`/`lookRight`/`lookUp`/`lookDown`), random pose or colour picks, a jittering needle |\n| `cycle` | a repeating `sine`/`triangle`/`saw`/`square` wave every `period` seconds | breathing (`breath`, sine ~3.5 s), bobbing, a pulsing glow, UI pulses, beacons |\n\nDrive eyelids or the eyes' y-scale from `eyeOpen`; drive chest or shoulder scale and a small head\nbob from `breath`. A different `seed` per character keeps two characters from blinking together.\n\nEyes that look around: give each eye a `composition` layer holding its white and its pupil. Mask the\npupil with a clip that repeats the white's own `transform` and shape: a clip keeps its own transform,\nso inside the eye it lands exactly on the white and the pupil never leaves it. A clip on the eye layer\nitself does not sit on the white, and the eye draws nothing. The gaze is four one-sided 0..1 parameters,\nthe standard expression names `lookLeft`, `lookRight`, `lookUp`, `lookDown`. The pupil's position reads\nthem, `value + Vec.v2((p:lookRight() - p:lookLeft()) * r, (p:lookDown() - p:lookUp()) * r)` with\n`p = ctx.composition:getParameters()` and `r` the room the white leaves. Apply `random_hold` to all four\nwith one `seed` and `centerBias` about 0.5: `lookRight` channel 0 `half: \"positive\"`, `lookLeft`\nchannel 0 `half: \"negative\"`, `lookUp` channel 1 `positive`, `lookDown` channel 1 `negative`. The eye\nnever looks left and right at once, and both axes jump at the same moments, as a glance does.\n\n## Secondary motion and characters\n\nPick by what moves the part: a rig control (a head turn drives the hair) is parameter-mode\n`follow_through`; a parent layer's world motion, under gravity or wind too, is layer-mode\n`follow_through` (`layerId`, a layer constraint); a keyed part that should carry on past its own stop\nis `settle`; a part that never holds still is `wiggle`; a slow regular loop is `sway`; an impact is\n`shake`. Layer-mode springs, their ranges and starting values per part, a worked five-link hair chain,\nnested clocks, seeking cost and pitfalls are in [secondary-motion.md](references/secondary-motion.md).\n`settle` and `wiggle` on a layer or, with `item`, on one named group of a `shape` layer (a drawn tail,\nantennae, whiskers) are in [settle-and-wiggle.md](references/settle-and-wiggle.md).\n\nHair, ears, a tail or an antenna that lag a turning head are one parameter following others through a\ndamped spring: apply `follow_through` to the PARAMETER (`\"follow\"` lists the driving parameters with\ntheir weights; `frequency` and `damping` set the lag), never write the spring yourself. Its value is\nthe swing, 0 while the drivers hold still. A chain of any length takes one value per piece through\n`segments`. The full recipe, with the parameter wiring and the units, is in `character-rigging`\n(fetch with `picsart_scene_recipe`, name `character-rigging`).\n\nA sketchy, hand-inked look comes from the `line_boil` preset on a shape's `path` items: each outline\npoint sits up to `amplitude` px off its place and takes a new one `rate` times a second, where `shake`\nmoves the layer and a group `wiggle` moves a part rigidly. Worked calls, `item` for one outline and the\nrefusals: [references/line-boil.md](references/line-boil.md).\n\nA character that walks, waves or jumps from a few looped keys, a shape's outline that morphs, bends or\nis swapped (`vertices` tracks, `deformers`, outline expressions), bent limbs and two-bone `ik` foot\ntargets are all in `character-rigging` as well. Pose the catalog rig (`rig-humanoid`, `rig-face`) when it\nfits; build by hand only when it does not. Within a shape's `items`, and a group's `contents`, the\nfirst item paints on top, as After Effects stacks layers: list a face's mouth and eyes before the head\nthey sit on.\n\n## Held drawings: animating on twos\n\nA nested composition (an inline `composition` or a `scene_ref` body) whose `composition.fps` is\nLOWER than its host's rate draws on its own frame grid: every host frame shows the start of the\nnested frame it falls in. `\"fps\": 12` inside a 24 fps scene is animation on twos, the stepped look of\nhand-drawn animation, without duplicating a keyframe. The hold covers the whole composition:\nkeyframes, expressions (their `time` is the held one, so a wobble boils on twos), media, Lottie and\nnested playback, which of its layers are live and reads between its own layers. A held frame keeps the\nmotion blur of its own instant. An effect's rolling seed follows the host clock (the grain is the\nfilm, not the drawing), and sound is not held: audio inside plays on the host clock.\n\n```json\n{\"id\": \"character\", \"content\": {\"kind\": \"composition\",\n \"composition\": {\"width\": 1080, \"height\": 1080, \"fps\": 12},\n \"layers\": [{\"id\": \"ball\", \"content\": {\"kind\": \"shape\", \"items\": [\"...\"]},\n \"animations\": {\"position\": {\"keyframes\": [{\"time\": 0, \"value\": [100, 500]}, {\"time\": 1, \"value\": [900, 500]}]}}}]}}\n```\n\nAn equal or higher rate, or none, holds nothing. A rate that does not divide the host's holds\nunevenly (24 in 30 is a pulldown), so pick a divisor of the output rate. Put whatever must stay\nsmooth, such as a camera move, outside the held composition. Measure the result per frame: the ink\ncentroid moves only on the nested frames.\n\n## Depth and the camera\n\nEvery composition is seen through one perspective camera, `composition.camera`. Omitted, it is the\ndefault: pivot at the composition centre, `distance` `width * 50 / 36` (a 50 mm lens), no orbit. On\nthe `z = 0` plane that draws exactly the flat composition, so depth costs nothing until a layer asks.\n\n| Field | Meaning |\n|---|---|\n| layer `transform.z` | depth in composition px, **positive toward the viewer** |\n| layer `transform.rotationX` / `rotationY` | tilt in degrees, the `perspective_3d` effect's signs: +X tips the top edge away, +Y turns the right edge away; `rotation` stays the clockwise roll |\n| `camera.position` | the pivot that zoom, roll and orbit turn about. The camera does **not pan**: moving only the pivot leaves every `z = 0` layer where it is, so pan with a parent layer ([film-camera.md](references/film-camera.md)) |\n| `camera.zoom` | image scale about the pivot — perspective unchanged |\n| `camera.distance` | eye-to-pivot px, > 0; the `z = 0` plane keeps its size at any distance, so animating it is a **dolly zoom** (nearer layers grow, farther ones shrink) — a push-in is `zoom` |\n| `camera.rotationX` / `rotationY` | orbit of the eye: the view is the inverse of a layer rotation of the same values (eye right = world turned left) — +X raises the eye, +Y moves it right |\n\nThe layer matrix is `T(x, y, z) · Rx · Ry · Rz · S · T(-anchor)` (intrinsic XYZ, as `perspective_3d`); `anchor`, `scale` and `position`\nstay `[x, y]`. All six layer/camera depth fields animate like any track; a layer's `animations.z`,\n`rotationX` and `rotationY` are replace-only, and motion components carry them too, so a preset can\nflip a card in depth.\n\nLayers in one run of camera-participating, non-adjustment layers draw **far to near**, re-sorted\nevery frame; equal depth keeps document order. `cameraExempt: true` on a root keeps its subtree flat\nand in place (a HUD). A mask follows its host's plane and carries no depth of its own. A nested\ncomposition, `scene_ref` or track has its own camera and is drawn as ONE flat card at its layer's\n`z` and tilt — put layers that must interleave in depth in the same composition. A look (such as\n`rounded_corners`) keeps its layer's depth, tilt and draw order. A look that turns its layer\n(`flip`, `tilt_3d`, `tilt_reflection`, tagged `2.5d`) adds that turn to the layer itself as a\n`look:<id>` motion component, so the composition camera draws it and it moves with an orbit.\n\nCamera moves ship as motion presets: `orbit`, `dolly` and `push_in`, each `appliesTo: [\"camera\"]`.\n`picsart_scene_apply_preset` with `motionPreset:<id>` and no `layerId` keys them onto the root composition's camera as editable\ntracks; their parameters are listed under `supports.motionPresets` in `picsart_scene_capabilities`.\n\nDepth is verified by measurement. `picsart_scene_query_layout` reports each projected layer's `quad`, `depth`\n(eye distance, larger is farther) and `zIndex` (this frame's paint order). In `picsart_scene_lint_layout`, a\nrelationship `{ \"kind\": \"order\", \"axis\": \"depth\", \"members\": [...] }` (members front to back) checks the\nstack over a window, and `covered` names each layer left under half visible by the layers drawn after it.\nAn overlap between two planes stays a collision finding, annotated `depthStacked` (`near`, `far`): judge\nwhether the stack is intended, with `covered` as the check for text it hides.\n\nThree laws for a scene in depth:\n\n1. **A label rides its plane.** Make it a child of the plane (`parentId`) with no `z` of its own: it\n takes the plane's depth and tilt and draws in front of it. A label given its own `z` floats free\n of the plane and sorts on its own.\n2. **Titles and HUD stay flat.** Make them `cameraExempt: true` roots.\n3. **Read the orbit's sign, don't guess it.** `camera.rotationX > 0` raises the eye, so nearer planes\n project LOWER on screen; the classic exploded diagram, front plane highest, is `rotationX < 0`\n (measured: a four-plane stack at `distance` 2400 under ±42°). Render one frame at the held orbit\n before building on it.\n\nA 2D film camera (a pan on an empty `world` parent, a push-in on `camera.zoom`, parallax by depth,\na sky kept still with `cameraExempt`) is in [film-camera.md](references/film-camera.md).\n\n## Motion blur\n\n`\"motionBlur\": true` on the layer smears it along its own motion, keyframed or expression-driven.\nIt is what makes a fast move read as speed rather than a teleport. `composition.motionBlurSampleCount`\nsets the shutter samples per frame (clamped 1..64); omit it for the default (16). It is refused in a\ncomposition whose camera orbits or whose layers author depth (`motion_blur_3d_unsupported`).\n\n## Transitions\n\nA `transitions[]` entry needs `between` — which seam of the track it sits in — as well as `id` and\n`duration`. Omitting it fails `transition_between_out_of_range`, which names the legal range.\n\nEvery shipped transition fills the `duration` it is given: its keyframes are written against the\nwindow, so a longer window is a slower move — `card_flip` goes edge-on exactly at the seam, as\nauthored. None plays a video or lottie matte (those families were removed: their `.webm` mattes do\nnot decode on iOS).\n\n## Validate the mechanism and its result\n\nFor reversals, jumps, overshoot, acceleration peaks or settling, inspect the actual output-frame times. Read [Frame-complete motion validation](references/frame-motion-validation.md) for independent thresholds and coverage limits. Run `picsart_scene_check_motion` with an explicit root-time window and the actual export FPS; explicit queries cover only the times actually requested. Do not claim frame-complete evidence unless every relevant frame and channel was compared. Construct rigid relationships with a shared owner or supported binding first; numerical checks do not replace ownership or visual inspection.\n\nRead `picsart_scene_recipe motion-pattern-library` and fetch its **Validation by pattern** reference\nbefore accepting a motion. Use its **mechanics**\nrows for pivots/transform order, easing, local clocks, expressions, text selectors, and motion blur;\nuse its pattern rows for the intended beat. `picsart_scene_validate` accepts structure, not choreography.\nQuery evaluated geometry at the decisive events and extrema; run supported relationship contracts;\ninspect rendered frames and playback for paint-only effects and perceived timing. Never substitute\nauthored keyframe values or a successful export for evidence that the evaluated result is correct.\n\n## When it renders wrong\n\n| Symptom | Look at |\n|---|---|\n| `preset_kind_mismatch` | a look or preset on a content kind outside its `appliesTo` (`ken_burns` on a non-media layer) |\n| `unknown_text_animation_preset` | the name is absent from both the document and shipped text-animation catalogs |\n| `invalid_text_animation_params` | a named text animation has a missing, unknown, or out-of-range parameter |\n| the layer slides while it scales | a component `anchor` explicitly set to `[0,0]` |\n| a transition fires but feels wrong | a mask-driven one whose `duration` is not its `sweep` |\n| motion reads mechanical | `easing` omitted somewhere — that is `linear` |\n| a layer moved in `z` does not reorder against a sibling | the sibling sits in another composition (a nested card), or a `cameraExempt`/adjustment layer splits the run |\n""---\nname: scene-animation-reference\ndescription: How a scene expresses motion — preset catalogs, layer animations and transform stacks, easing and spatial tangents, Lua expressions, shared path phase, text on a curved or closed path, named actions mixed on a placed scene, depth and the composition camera (2.5D, cards that flip or fan out in depth under an orbit, a 2D film camera's pan, push-in and parallax), motion blur, held drawings (animation on twos), transition firing, and parameter drivers that keep a character alive on their own (eyes looking around, blinks, breathing, hair and ears that follow through, a tail that settles, whiskers that wiggle), with a pointer to the walk, wave and jump cycles of a cartoon rig. Use when motion needs authoring or validation, a character or object should glance, blink, breathe or sway by itself, objects need editable path offsets, text must follow a baseline, a scene validates but renders wrong, or a preset is rejected for the content kind.\nmetadata:\n category: authoring\n version: '1.19'\n ported-from: motion-mechanics 1.19 at 55.128.2\n---\n\n# Saying motion in a scene\n\nThe decision — what a beat is for, how long, which register — is `picsart_scene_recipe motion-intent`.\nThis is the other half: how the format says it, and the places where the obvious spelling is the\nwrong one. For the relationship across beats or the choice of seam mechanism, decide first with\n`picsart_scene_recipe motion-scene-continuity`, then return here for syntax. For semantic grouping, container\ngrowth and sibling reflow, first use `picsart_scene_recipe linked-element-motion`. A common placement owner\ndoes not imply automatic layout. The constructions below need verification in the actual scene.\n\n## Named actions on a placed scene\n\nWhen a placed scene declares fixed motions in its root `actions` map (imported bone timelines,\nparameter motions, authored cut-out poses), its `scene_ref` layer plays and mixes them through\n`content.animation`: a list of entries with `action`, `trim`, `speed`, `loop`, `weight`, `start`,\n`duration`, `fade`, `mode` (`replace` or `aggregate`) and `tier`. A catalog rig's motion presets\nwrite `scene_ref.parameters` bindings instead; those are live controls, not actions. Layer\n`animations` move the whole rig. Mixing, tiers, crossfades without a rest dip, step channels,\n`blending: \"pass_through\"`, a complete walk→idle scene and every refusal are in\n[named-actions.md](references/named-actions.md); the schema is `picsart_scene_capabilities` with\n`sections: [\"schema:ActionAnimation\"]`.\n\n## Two catalogs, two ways in\n\nThey look alike and are applied differently. Getting this wrong is the commonest first failure.\n\n| | Motion looks | Motion presets | Text animations |\n|---|---|---|---|\n| What | entrance/exit (`role: in`/`out`) `fade`, `slide`, `zoom`, `spin`, `wipe`, `blur`, `flip`; entrance `pop`, `flash`; loops `float`, `sway`, `shake`, `pulse`, `glow_pulse`, `blink`, `rotate`, `clockwork`, `ken_burns` | entrances `fade_in`, `slide_in`, `zoom_in`, `scale_pop`, `spring`, `rotate_in`, `blur_in`, `flip_in`, `reveal_in`; exits `fade_out`, `slide_out`, `zoom_out`, `rotate_out`, `blur_out`, `reveal_out`; emphasis `tap_pulse`, `glow_pulse`, `shake`; atmosphere `ken_burns`, `breathe`, `float`, `sway`; paging `step_slide`; secondary motion `settle`, `wiggle` (also on a shape group with `item`); parameter drivers `follow_through`, `random_pulse`, `random_hold`, `cycle` (write a parameter, below) | `typewriter`, `fade_in_chars` (`grow` makes each letter grow in too), `slide_up_lines`, `flicker_chars` (+ ambient ones, below) |\n| Applied with | `picsart_scene_apply_preset` with `look:<id>` (iOS `applyLook`) and `params` (`role`, `length`, …); a window `start`/`duration` is set on the `looks[]` entry with `picsart_scene_patch` | `picsart_scene_apply_preset` with `motionPreset:<id>` (iOS `applyMotionPreset`) | name it in `content.animations[]`, or bake an entrance with `picsart_scene_apply_preset` and `textAnimation:<name>` |\n| Lands in | the layer's `looks[]` | the layer's `animations` / `transforms[]` / `effects`, or `constraints` for layer follow-through | the text content's `content.animations[]` |\n| Named in the document? | yes — `{ \"look\": \"fade\", \"params\": { \"role\": \"in\" } }`, so an editor shows and swaps it | no — the tool expands it into ordinary tracks or layer constraints | yes — `{ \"preset\": \"typewriter\", \"params\": {} }` |\n\n**A preset or a look.** A motion preset is a starting point: it writes ordinary keyframes (and\neffects) that the agent or the editor user then owns and edits keyframe by keyframe. A look stays a\nnamed entry an editor shows and swaps as a whole. Use a preset when the keyframes will be edited\nafterwards; use a look when the motion should stay a named, swappable entry. A one-shot beat at a\nchosen moment (`tap_pulse`, `spring`, `scale_pop`) is a preset.\n\nA look applies to the kinds its `appliesTo` lists. Most motion looks take `color` and `shape` layers\ntoo (`blur` and `flip` take `color` but not `shape`; `wipe`, `flash`, `blink`, `rotate` and\n`clockwork` take neither). For a look that does not list the kind, wrap\nthe layer in a scene asset and apply the look to the `scene_ref`.\n\n`content.animations[]` is a mixed source list: each row is either a named `{preset, params?}` reference\nor a concrete per-glyph `{transform, selector}` entry. Resolution expands every named row before the\nrenderer sees it. Naming keeps the choice editable and can reach a `type: \"text_animation\"` definition\ndeclared in the document's own assets; baking with the tool writes the concrete entries instead.\n\n**Content-kind traps.** `ken_burns`, look or preset, takes `media` / `scene_ref` only, and a look\nor preset on a kind outside its `appliesTo` is `preset_kind_mismatch`. A plain text layer may name either an entrance preset or an **ambient** one\n(`drift`, `flicker`, `hop`, `shake`, `sway`, `throb`, `transform`, `wiggle`). Ambient motion uses\nthe layer's duration as its resolution window; its mode decides whether it is static, plays once,\nloops, or ping-pongs. It selects every glyph. A caption can use the same ambient definition through\na decoration row's `place: \"text\"` field when it needs line/emphasis/highlight selectors instead.\n\n`applied` in the result names the preset once; `entryCount` says how many animator entries it\nappended (a multi-decorator preset like `slide_up_lines` appends two).\n\n### What `picsart_scene_apply_preset` writes\n\n- **Camera presets** (`appliesTo: [\"camera\"]`, e.g. `motionPreset:push_in`, `dolly`, `orbit`) move the\n root composition's camera when `layerId` is omitted, or the camera of the `composition` or\n `scene_ref` layer it names.\n- **Effects** can be confined to a detected region with `mask`: the effect's `supports.effects` row\n says whether it takes one, and the detectors are listed under `supports.maskProviders`.\n- **Text animations** start at the text layer's local time 0: set the layer's `start` to reveal it\n later. An ambient text animation is not baked; it is attached by name in `content.animations[]`.\n- **Looks** wrap the layer's content in an isolated nested composition, so the look treats the\n composited result as one image. By reference (the default) nothing is baked: preview, translate\n and query expand it when needed, and `picsart_scene_resolve_looks` bakes a self-contained scene.\n `mode: \"expand\"` bakes it now: `transform`, `animations`, `blendMode`, `mask` and `motionBlur`\n move onto the wrapper, the layer's own effects apply once before the look, and a track clip bakes\n its whole `looks[]` chain and keeps its slot. A layer with `adjustmentLayer: true` takes no look.\n\n## Where a motion lives\n\nTwo places, and the choice is not stylistic.\n\n**`animations`** — the layer's own Placement tracks (`position`, `scale`, `rotation`, `z`,\n`rotationX`, `rotationY`, `opacity`, `anchor`). Pivots about the layer's own anchor. Always available.\n\n**`transforms[]`** — an ordered stack of motion components applied *outside* Placement, each with its\nown `id` and `animations` (`translation` / `scale` / `rotation` / `z` / `rotationX` / `rotationY` /\n`anchor`), evaluated in array order:\n\n```json\n\"transforms\": [\n { \"id\": \"entrance\", \"animations\": { \"translation\": { \"keyframes\": [ ... ] } } },\n { \"id\": \"breathe\", \"animations\": { \"scale\": { \"expression\": \"return value * (1 + 0.02 * math.sin(2*math.pi*time/3))\" } } }\n]\n```\n\nThe stack exists so **layout stays editable**: `transforms` carries motion (animations, presets) and\n`transform` is the placement a user or host edits. They compose, so editing placement never rewrites\nthe motion, and the motion follows the edit. That is why a `motionPreset:` preset applied with `picsart_scene_apply_preset` routes geometry here. One\ncomponent per motion layer also keeps each independently re-timeable, instead of one `scale` track\ncarrying an entrance and a breathe that can no longer be told apart.\n\nPositions follow After Effects: `transform.position` places the layer's `transform.anchor` in its\nparent's space (the parent layer's own pixels with `parentId`, otherwise composition pixels from the\ntop-left). An omitted `transform.position` is the composition's centre, for a child too: a child\nwith no `transform` sits half a composition into its parent's pixels, so give every child one\n(`[0, 0]` is the parent's origin, the pivot of an `empty` or a shape drawn about `[0, 0]`). An\nomitted component `anchor` is that anchor **where it currently sits**, following a `position`\nanimation and parenting, so a component scale or rotation turns the layer in place even while it\nmoves:\n\n```json\n\"transform\": { \"position\": [300, 300] },\n\"animations\": { \"position\": { \"keyframes\": [ {\"time\": 0, \"value\": [300, 300]}, {\"time\": 2, \"value\": [700, 300]} ] } },\n\"transforms\": [\n { \"id\": \"spin\", \"animations\": { \"rotation\": { \"keyframes\": [ {\"time\": 0, \"value\": 0}, {\"time\": 2, \"value\": 360} ] } } }\n]\n```\n\nMental model: a component is a parent null (After Effects) or a wrapper element (CSS) sitting on the\nlayer's anchor. With no `anchor` it rotates and scales about the layer's anchor wherever the layer\ncurrently is, and `translation` moves in parent pixels.\n\n- **Turn about a fixed point** — give the component an `anchor`: a fixed point in the layer's\n parent space, not the layer's own pixels. It replaces the pivot and does not follow placement edits.\n `anchor: [0,0]` pivots on the parent's top-left.\n- A component's `animations.anchor` is its pivot track, in the same parent space; a layer's own\n `animations.anchor` is layer-local, like `transform.anchor`.\n\n## Easing\n\n`linear`, `ease_in`, `ease_out`, `ease_in_out`, `step` — **plus** a parametric curve:\n\n```json\n\"easing\": { \"kind\": \"cubic_bezier\", \"control\": [0.175, 0.885, 0.32, 1.275] }\n```\n\nCSS convention: `x` stays in [0,1], while `y` may extend beyond it. A control ordinate is not the\nrendered overshoot percentage: the curve, endpoints and timing determine the actual peak. Query or\nrender the peak in the scene before deciding whether it suits the intended motion.\n\n**A keyframe with no `easing` is `linear`.** Use it deliberately for constant-rate travel or progress;\nuse an eased curve when acceleration or settling serves the beat. Easing belongs on the segment's\nstarting keyframe; the terminal keyframe has no following segment to ease.\n\n**Each component on its own.** On a vec2, vec3 or rect value, `easing` may be a list with one easing\nper component, in the value's order: a scale whose width snaps out while its height lags is one\ntrack, not two nested layers.\n\n```json\n\"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0, 0], \"easing\": [\"ease_out\", \"ease_in\"] },\n { \"time\": 0.6, \"value\": [1, 1] } ] }\n```\n\nThe list has exactly one entry per component, and `step` is never an entry (a hold keeps the whole\nvalue). A number or a colour takes one easing.\n\n## Path, separately from timing\n\n`inTangent` / `outTangent` on a `position` or `anchor` keyframe are `[x, y]` velocity handles\nrelative to that keyframe's value — AE motion-path handles. `easing` shapes the timing *along* the\npath; the tangents shape the path itself. Omitted means a straight line, which is why every\nunattended long move is one.\n\n```json\n\"position\": { \"keyframes\": [\n { \"time\": 0, \"value\": [200, 540], \"easing\": \"ease_in_out\", \"outTangent\": [120, -160] },\n { \"time\": 1.6, \"value\": [880, 540], \"inTangent\": [-120, -160] }\n] }\n```\n\nA handle on any other property is dropped.\n\nFor **a path driven by a separate phase**, use tangent keyframes plus\n`ctx:sampleBase(seconds)` on that same property. Read [Shared path phase](references/path-phase.md)\nfor a runnable scene, offset/clamp/wrap choices, clock and sampling limits, and executable checks.\nThis keeps position geometry editable without retiming the card's video. Ordinary timed movement\nstill needs only keyframes; this extra sampling is for independently controlled progress.\n\nFor **text on a curved or closed baseline**, use `content.textPath` rather than\none animated layer per letter. Read [Text on a path](references/text-on-path.md)\nfor geometry, animated offsets, combined character animators and validation. This is distinct from\nmoving an entire object along its position track.\n\n## Expressions\n\nFor an object that turns along its path, keep one authoritative position track and bind\n`animations.rotation.expression` to `positionDirection()`. Do not introduce an auto-orientation\nflag or copy the path into a separate heading track. The artwork's forward-axis correction belongs\nin `transform.rotation`; the expression adds it through `value`. This applies to arrows, vehicles\nand other path followers, not only cursors. Ordinary value reads do not request motion samples;\ndirection/velocity work is on demand when the expression calls it.\n\nRead Cursor-led action (fetch with `picsart_scene_recipe`, name `app-ui-animation`) and its direction reference\nbefore authoring the binding. Through MCP, fetch `picsart_scene_recipe` with `name: \"app-ui-animation\"`,\nthen its listed **Cursor actions and menus** reference. It contains the executable expression, coordinate\nand clock limits, hold/zero-direction behavior and validation. Check heading against independent\ntravel samples, including a changed path and a delayed instance; a valid expression and correct\npositions alone do not prove correct orientation. Use an explicit heading track only when the\nart direction deliberately differs from travel (banking, gaze, a stationary expression's held pose).\n\nA track can carry a Lua `expression` instead of, or on top of, keyframes. It must `return`, sees\n`value` (the keyframed base) and `time` in **layer-local seconds**, zero at that layer's start,\nand returns `Vec.v2(x, y)` for vec2 properties. Moving the layer's start moves the expression's\nonset too; do not subtract that start again. For a nested scene, map root time into the containing\ncomposition first, including reference trim/speed, then subtract the child's start. Keyframe\n`timeMode` does not turn an expression's clock into root time. Check delayed/nested instances with\n`picsart_scene_query_layout` at their mapped start and later moments.\n\n### Bind a supported property instead of copying its track\n\nPrefer a common composition owner for a rigid widget. For a genuine one-way dependency between\nseparate layers, Lua can read a sibling's evaluated Placement, for example on the follower's\nposition track:\n\n```json\n{ \"expression\": \"return ctx.composition:getLayer('driver'):getPlacement():position() + Vec.v2(0, 24)\" }\n```\n\nThis reads an authored sibling id in the same composition; it is not a flattened query id. The\nresult is Placement in that layer's parent space, not its root-space painted center or the result\nof every `transforms[]` entry. Use this offset formula only with compatible parent spaces, anchors\nand intended Placement motion. For shared transform-stack motion, use an owner instead. Self-reads\nof the property being defined and cyclic dependencies are refused. Consult the current expression\nschema for available getters; there is no arbitrary live shape-size or text-metrics getter.\nUnlike `$eval`, this is a per-frame dependency. Validate and query the actual delayed/nested instance;\nlocal `time` formulas on separately started layers need clock mapping even when their text matches.\n\nA value that follows a parameter through drawn poses is a `by` track (see `character-rigging`, \"Poses keyed to a dial\"),\nnot an expression that reads the parameter and interpolates by hand.\n\nTwo compact time-expression uses:\n\n**Ambient motion that continues looping** for the beat's duration:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.15 * math.sin(2*math.pi*time/2))\" }\n```\n\nThe coefficient varies the base scale by ±15%. Its literal two-second period does not change when\nthe beat duration changes; adjust it explicitly to preserve a chosen cycle count. Inspect the\nresulting bounds, final phase and reading comfort.\n\n**A real spring** — a damped oscillation, which one `cubic_bezier` cannot express:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.35 * math.exp(-6*time) * math.cos(18*time))\" }\n```\n\nThe expression alternates around the base value with diminishing amplitude. Raise the\n`exp` coefficient to settle sooner, the `cos` coefficient for more bounces.\n\n### The `picsart.*` stdlib — the recurring shapes, already written\n\nThese are built in. Reach for them before\nhand-rolling the trigonometry. Call them directly as `picsart.<name>(...)`; an alias such as `local p = picsart` is not supported.\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, 0.3, 1, 0.7)\" }\n\"position\": { \"expression\": \"return picsart.jitter(value, time, 16, 11, 0.3)\" }\n\"rotation\": { \"expression\": \"return picsart.wiggle(value, time, 2, 4)\" }\n\"scale\": { \"expression\": \"return Vec.v2(picsart.oscillate(time, 1, 1.05, 2), picsart.oscillate(time, 1, 1.05, 2))\" }\n```\n\n- `picsart.oscillate(time, low, high, halfPeriod)` — smooth low↔high, starting at `low`, one half cycle\n every `halfPeriod` seconds. A vec2 property takes one call per component inside `Vec.v2`.\n- `picsart.jitter(value, time, ampX, ampY, step)` — deterministic shimmer around the layer's own base\n `value`, resampled every `step` seconds. Not random: same inputs, same frame.\n- `picsart.wiggle(value, time, freq, amp [, octaves=1, ampMult=0.5, seed=0])` — AE's `wiggle`, fractal\n noise at `freq` wiggles/sec, per component on a `Vec`.\n- `ctx:loopOut(mode)` — repeats the track's keyed range past its last key. Key ONE cycle, loop it:\n `\"cycle\"` restarts every range (a breath, a foot's roll), `\"pingpong\"` plays every other range\n backwards (a wave), `\"offset\"` restarts each range shifted by its last-minus-first value (anything\n that travels: a stride, a walking body), `\"continue\"` extends along the slope at the end it leaves.\n `{\"keyframes\": [...], \"expression\": \"return ctx:loopOut('cycle')\"}`. Before the first key the\n track holds that key.\n- `picsart.cycle(time, waveform, from, to, period, phase [, variation, seed])` — a `\"sine\"`,\n `\"triangle\"`, `\"saw\"` or `\"square\"` wave: `picsart.cycle(time, \"sine\", 0, 1, 3.5, 0)`.\n- `picsart.randomPulse(time, from, to, minInterval, maxInterval, attack, hold, release, burstChance, seed)`\n — seeded random events, each eased `from` -> `to` and back: a blink.\n- `picsart.randomHold(time, from, to, minInterval, maxInterval, transition, seed, channel [, centerBias, half])`\n — a seeded random value held, then eased to the next on `picsart.randomPulse`'s timing; `half`\n `\"both\"`, `\"positive\"` or `\"negative\"`: a glance.\n- `picsart.follow(time, read, frequency, damping, amount, segment)` — a damped spring trailing `read(t)`:\n lag, overshoot, settle (hair, tails, a dangling arm). It follows PARAMETERS; see\n [Secondary motion](#secondary-motion-and-characters) for `segments`, one value per piece\n of a chain of any length.\n- `picsart.clamp(v, low, high)`, `picsart.linear|ease|easeIn|easeOut(t, tMin, tMax, v1, v2)` — AE's\n interpolation set, held outside `[tMin, tMax]`; `v1`/`v2` a number or same-arity `Vec`:\n `picsart.ease(time, 0, 0.4, 0, 1)`.\n- The four `picsart.cycle` / `picsart.randomPulse` / `picsart.randomHold` / `picsart.follow` calls are what the\n `cycle`, `random_pulse`, `random_hold` and `follow_through` presets write\n ([Parameter drivers](#parameter-drivers)). Apply the preset rather than writing the call.\n\n**Reading another value at a time.** `ctx.composition:getParameters():<name>([t])` is a parameter\nat `t`, seconds on the reader's clock (default now): `p:headTurn(time - 0.25)` trails a quarter\nsecond. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` / `scale([t])` is that\nlayer's placement at `t`, seconds on the reader's clock with the layer's own clock applied:\n`position(time - 0.2)` trails it by 0.2 s. The layer is one of the same composition; a timed read\nof a layer that plays on another composition's clock fails the frame. Without `t` it reads this\nsame instant (see \"Bind a supported property instead of copying its track\"). `getSocket` and `getSocketDirection` on a layer read a placed character's published sockets (`character-rigging` \"Standard sockets\").\n\n**In a DEFINITION** (a look, a transition, a decoration) `{param}` splices the definition's own\nscope into the expression text, so the shape stays parametric:\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, {glow} * 0.3, {glow}, 0.18 / {speed})\" }\n```\n\n`{name}` there is a raw TEXT splice, not a typed lookup — it drops the param's number into the Lua\nsource, so surrounding arithmetic is Lua's. (Everywhere OUTSIDE an `expression`, `{name}` is the\ntyped scope lookup instead.) `picsart_scene_capabilities` lists the full stdlib.\n\n## Parameter drivers\n\nFour presets write a number parameter's `default`, applied with `picsart_scene_apply_preset`\n(`motionPreset:<id>` and `\"parameter\": \"<name>\"`); the layers read the parameter, so one value drives\nevery part that shares it.\n\nOn a cartoon rig (a `scene_ref` layer drawing `scene://rig-humanoid` or `rig-face`), pass the rig\nlayer as `layerId` and its control as `parameter` (`random_pulse` on `blink`, `cycle` on `breath`):\nthe track is bound on that layer, so each instance moves on its own. The rigs and `walk_cycle` are in\n`character-rigging`.\n\n| Preset | The value | Typical uses |\n|---|---|---|\n| `follow_through` | the swing of a damped spring trailing other parameters | hair, ears, tails, antennae, a dangling sign |\n| `random_pulse` | brief eased events at seeded random intervals (`minInterval`, `intervalSpread`, `attack`/`hold`/`release`, `burstChance`) | blinks (`eyeOpen` from 1 to 0), lamp flicker, twinkling stars, glitch hits |\n| `random_hold` | a seeded random value held, then a quick eased jump (`transition`) to the next, `minInterval` + `intervalSpread` apart; one `seed` shares the jump times, `channel` picks the value stream, `half` keeps its `positive` or `negative` side, `centerBias` gathers values mid-range | eyes looking around (`lookLeft`/`lookRight`/`lookUp`/`lookDown`), random pose or colour picks, a jittering needle |\n| `cycle` | a repeating `sine`/`triangle`/`saw`/`square` wave every `period` seconds | breathing (`breath`, sine ~3.5 s), bobbing, a pulsing glow, UI pulses, beacons |\n\nDrive eyelids or the eyes' y-scale from `eyeOpen`; drive chest or shoulder scale and a small head\nbob from `breath`. A different `seed` per character keeps two characters from blinking together.\n\nEyes that look around: give each eye a `composition` layer holding its white and its pupil. Mask the\npupil with a clip that repeats the white's own `transform` and shape: a clip keeps its own transform,\nso inside the eye it lands exactly on the white and the pupil never leaves it. A clip on the eye layer\nitself does not sit on the white, and the eye draws nothing. The gaze is four one-sided 0..1 parameters,\nthe standard expression names `lookLeft`, `lookRight`, `lookUp`, `lookDown`. The pupil's position reads\nthem, `value + Vec.v2((p:lookRight() - p:lookLeft()) * r, (p:lookDown() - p:lookUp()) * r)` with\n`p = ctx.composition:getParameters()` and `r` the room the white leaves. Apply `random_hold` to all four\nwith one `seed` and `centerBias` about 0.5: `lookRight` channel 0 `half: \"positive\"`, `lookLeft`\nchannel 0 `half: \"negative\"`, `lookUp` channel 1 `positive`, `lookDown` channel 1 `negative`. The eye\nnever looks left and right at once, and both axes jump at the same moments, as a glance does.\n\n## Secondary motion and characters\n\nPick by what moves the part: a rig control (a head turn drives the hair) is parameter-mode\n`follow_through`; a parent layer's world motion, under gravity or wind too, is layer-mode\n`follow_through` (`layerId`, a layer constraint); a keyed part that should carry on past its own stop\nis `settle`; a part that never holds still is `wiggle`; a slow regular loop is `sway`; an impact is\n`shake`. Layer-mode springs, their ranges and starting values per part, a worked five-link hair chain,\nnested clocks, seeking cost and pitfalls are in [secondary-motion.md](references/secondary-motion.md).\n`settle` and `wiggle` on a layer or, with `item`, on one named group of a `shape` layer (a drawn tail,\nantennae, whiskers) are in [settle-and-wiggle.md](references/settle-and-wiggle.md).\n\nHair, ears, a tail or an antenna that lag a turning head are one parameter following others through a\ndamped spring: apply `follow_through` to the PARAMETER (`\"follow\"` lists the driving parameters with\ntheir weights; `frequency` and `damping` set the lag), never write the spring yourself. Its value is\nthe swing, 0 while the drivers hold still. A chain of any length takes one value per piece through\n`segments`. The full recipe, with the parameter wiring and the units, is in `character-rigging`\n(fetch with `picsart_scene_recipe`, name `character-rigging`).\n\nA sketchy, hand-inked look comes from the `line_boil` preset on a shape's `path` items: each outline\npoint sits up to `amplitude` px off its place and takes a new one `rate` times a second, where `shake`\nmoves the layer and a group `wiggle` moves a part rigidly. Worked calls, `item` for one outline and the\nrefusals: [references/line-boil.md](references/line-boil.md).\n\nA character that walks, waves or jumps from a few looped keys, a shape's outline that morphs, bends or\nis swapped (`vertices` tracks, `deformers`, outline expressions), bent limbs and two-bone `ik` foot\ntargets are all in `character-rigging` as well. Pose the catalog rig (`rig-humanoid`, `rig-face`) when it\nfits; build by hand only when it does not. A humanoid rig holds a prop itself through its `held` parameter, and a `reach` constraint on its instance layer (`{\"type\": \"reach\", \"socket\": \"rightHand\", \"target\": {\"layer\": \"ball\"}, \"mix\": 1}`) puts a hand, foot or the `seat` on a stage point: both in `character-rigging`. Within a shape's `items`, and a group's `contents`, the\nfirst item paints on top, as After Effects stacks layers: list a face's mouth and eyes before the head\nthey sit on.\n\n## Held drawings: animating on twos\n\nA nested composition (an inline `composition` or a `scene_ref` body) whose `composition.fps` is\nLOWER than its host's rate draws on its own frame grid: every host frame shows the start of the\nnested frame it falls in. `\"fps\": 12` inside a 24 fps scene is animation on twos, the stepped look of\nhand-drawn animation, without duplicating a keyframe. The hold covers the whole composition:\nkeyframes, expressions (their `time` is the held one, so a wobble boils on twos), media, Lottie and\nnested playback, which of its layers are live and reads between its own layers. A held frame keeps the\nmotion blur of its own instant. An effect's rolling seed follows the host clock (the grain is the\nfilm, not the drawing), and sound is not held: audio inside plays on the host clock.\n\n```json\n{\"id\": \"character\", \"content\": {\"kind\": \"composition\",\n \"composition\": {\"width\": 1080, \"height\": 1080, \"fps\": 12},\n \"layers\": [{\"id\": \"ball\", \"content\": {\"kind\": \"shape\", \"items\": [\"...\"]},\n \"animations\": {\"position\": {\"keyframes\": [{\"time\": 0, \"value\": [100, 500]}, {\"time\": 1, \"value\": [900, 500]}]}}}]}}\n```\n\nAn equal or higher rate, or none, holds nothing. A rate that does not divide the host's holds\nunevenly (24 in 30 is a pulldown), so pick a divisor of the output rate. Put whatever must stay\nsmooth, such as a camera move, outside the held composition. Measure the result per frame: the ink\ncentroid moves only on the nested frames.\n\n## Depth and the camera\n\nEvery composition is seen through one perspective camera, `composition.camera`. Omitted, it is the\ndefault: pivot at the composition centre, `distance` `width * 50 / 36` (a 50 mm lens), no orbit. On\nthe `z = 0` plane that draws exactly the flat composition, so depth costs nothing until a layer asks.\n\n| Field | Meaning |\n|---|---|\n| layer `transform.z` | depth in composition px, **positive toward the viewer** |\n| layer `transform.rotationX` / `rotationY` | tilt in degrees, the `perspective_3d` effect's signs: +X tips the top edge away, +Y turns the right edge away; `rotation` stays the clockwise roll |\n| `camera.position` | the pivot that zoom, roll and orbit turn about. The camera does **not pan**: moving only the pivot leaves every `z = 0` layer where it is, so pan with a parent layer ([film-camera.md](references/film-camera.md)) |\n| `camera.zoom` | image scale about the pivot — perspective unchanged |\n| `camera.distance` | eye-to-pivot px, > 0; the `z = 0` plane keeps its size at any distance, so animating it is a **dolly zoom** (nearer layers grow, farther ones shrink) — a push-in is `zoom` |\n| `camera.rotationX` / `rotationY` | orbit of the eye: the view is the inverse of a layer rotation of the same values (eye right = world turned left) — +X raises the eye, +Y moves it right |\n\nThe layer matrix is `T(x, y, z) · Rx · Ry · Rz · S · T(-anchor)` (intrinsic XYZ, as `perspective_3d`); `anchor`, `scale` and `position`\nstay `[x, y]`. All six layer/camera depth fields animate like any track; a layer's `animations.z`,\n`rotationX` and `rotationY` are replace-only, and motion components carry them too, so a preset can\nflip a card in depth.\n\nLayers in one run of camera-participating, non-adjustment layers draw **far to near**, re-sorted\nevery frame; equal depth keeps document order. `cameraExempt: true` on a root keeps its subtree flat\nand in place (a HUD). A mask follows its host's plane and carries no depth of its own. A nested\ncomposition, `scene_ref` or track has its own camera and is drawn as ONE flat card at its layer's\n`z` and tilt — put layers that must interleave in depth in the same composition. A look (such as\n`rounded_corners`) keeps its layer's depth, tilt and draw order. A look that turns its layer\n(`flip`, `tilt_3d`, `tilt_reflection`, tagged `2.5d`) adds that turn to the layer itself as a\n`look:<id>` motion component, so the composition camera draws it and it moves with an orbit.\n\nCamera moves ship as motion presets: `orbit`, `dolly` and `push_in`, each `appliesTo: [\"camera\"]`.\n`picsart_scene_apply_preset` with `motionPreset:<id>` and no `layerId` keys them onto the root composition's camera as editable\ntracks; their parameters are listed under `supports.motionPresets` in `picsart_scene_capabilities`.\n\nDepth is verified by measurement. `picsart_scene_query_layout` reports each projected layer's `quad`, `depth`\n(eye distance, larger is farther) and `zIndex` (this frame's paint order). In `picsart_scene_lint_layout`, a\nrelationship `{ \"kind\": \"order\", \"axis\": \"depth\", \"members\": [...] }` (members front to back) checks the\nstack over a window, and `covered` names each layer left under half visible by the layers drawn after it.\nAn overlap between two planes stays a collision finding, annotated `depthStacked` (`near`, `far`): judge\nwhether the stack is intended, with `covered` as the check for text it hides.\n\nThree laws for a scene in depth:\n\n1. **A label rides its plane.** Make it a child of the plane (`parentId`) with no `z` of its own: it\n takes the plane's depth and tilt and draws in front of it. A label given its own `z` floats free\n of the plane and sorts on its own.\n2. **Titles and HUD stay flat.** Make them `cameraExempt: true` roots.\n3. **Read the orbit's sign, don't guess it.** `camera.rotationX > 0` raises the eye, so nearer planes\n project LOWER on screen; the classic exploded diagram, front plane highest, is `rotationX < 0`\n (measured: a four-plane stack at `distance` 2400 under ±42°). Render one frame at the held orbit\n before building on it.\n\nA 2D film camera (a pan on an empty `world` parent, a push-in on `camera.zoom`, parallax by depth,\na sky kept still with `cameraExempt`) is in [film-camera.md](references/film-camera.md).\n\n## Motion blur\n\n`\"motionBlur\": true` on the layer smears it along its own motion, keyframed or expression-driven.\nIt is what makes a fast move read as speed rather than a teleport. `composition.motionBlurSampleCount`\nsets the shutter samples per frame (clamped 1..64); omit it for the default (16). It is refused in a\ncomposition whose camera orbits or whose layers author depth (`motion_blur_3d_unsupported`).\n\n## Transitions\n\nA `transitions[]` entry needs `between` — which seam of the track it sits in — as well as `id` and\n`duration`. Omitting it fails `transition_between_out_of_range`, which names the legal range.\n\nEvery shipped transition fills the `duration` it is given: its keyframes are written against the\nwindow, so a longer window is a slower move — `card_flip` goes edge-on exactly at the seam, as\nauthored. None plays a video or lottie matte (those families were removed: their `.webm` mattes do\nnot decode on iOS).\n\n## Validate the mechanism and its result\n\nFor reversals, jumps, overshoot, acceleration peaks or settling, inspect the actual output-frame times. Read [Frame-complete motion validation](references/frame-motion-validation.md) for independent thresholds and coverage limits. Run `picsart_scene_check_motion` with an explicit root-time window and the actual export FPS; explicit queries cover only the times actually requested. Do not claim frame-complete evidence unless every relevant frame and channel was compared. Construct rigid relationships with a shared owner or supported binding first; numerical checks do not replace ownership or visual inspection.\n\nRead `picsart_scene_recipe motion-pattern-library` and fetch its **Validation by pattern** reference\nbefore accepting a motion. Use its **mechanics**\nrows for pivots/transform order, easing, local clocks, expressions, text selectors, and motion blur;\nuse its pattern rows for the intended beat. `picsart_scene_validate` accepts structure, not choreography.\nQuery evaluated geometry at the decisive events and extrema; run supported relationship contracts;\ninspect rendered frames and playback for paint-only effects and perceived timing. Never substitute\nauthored keyframe values or a successful export for evidence that the evaluated result is correct.\n\n## When it renders wrong\n\n| Symptom | Look at |\n|---|---|\n| `preset_kind_mismatch` | a look or preset on a content kind outside its `appliesTo` (`ken_burns` on a non-media layer) |\n| `unknown_text_animation_preset` | the name is absent from both the document and shipped text-animation catalogs |\n| `invalid_text_animation_params` | a named text animation has a missing, unknown, or out-of-range parameter |\n| the layer slides while it scales | a component `anchor` explicitly set to `[0,0]` |\n| a transition fires but feels wrong | a mask-driven one whose `duration` is not its `sweep` |\n| motion reads mechanical | `easing` omitted somewhere — that is `linear` |\n| a layer moved in `z` does not reorder against a sibling | the sibling sits in another composition (a nested card), or a `cameraExempt`/adjustment layer splits the run |\n"Full snapshot data
{
"description": "How a scene expresses motion — preset catalogs, layer animations and transform stacks, easing and spatial tangents, Lua expressions, shared path phase, text on a curved or closed path, named actions mixed on a placed scene, depth and the composition camera (2.5D, cards that flip or fan out in depth under an orbit, a 2D film camera's pan, push-in and parallax), motion blur, held drawings (animation on twos), transition firing, and parameter drivers that keep a character alive on their own (eyes looking around, blinks, breathing, hair and ears that follow through, a tail that settles, whiskers that wiggle), with a pointer to the walk, wave and jump cycles of a cartoon rig. Use when motion needs authoring or validation, a character or object should glance, blink, breathe or sway by itself, objects need editable path offsets, text must follow a baseline, a scene validates but renders wrong, or a preset is rejected for the content kind.",
"included_files": [
{
"relative_path": "references/film-camera.md",
"size_in_bytes": 1690
},
{
"relative_path": "references/frame-motion-validation.md",
"size_in_bytes": 6445
},
{
"relative_path": "references/line-boil.md",
"size_in_bytes": 3248
},
{
"relative_path": "references/named-actions.md",
"size_in_bytes": 7856
},
{
"relative_path": "references/path-phase.md",
"size_in_bytes": 6655
},
{
"relative_path": "references/secondary-motion.md",
"size_in_bytes": 9051
},
{
"relative_path": "references/settle-and-wiggle.md",
"size_in_bytes": 3703
},
{
"relative_path": "references/text-on-path.md",
"size_in_bytes": 5886
}
],
"name": "scene-animation-reference",
"skill_md_contents": "---\nname: scene-animation-reference\ndescription: How a scene expresses motion — preset catalogs, layer animations and transform stacks, easing and spatial tangents, Lua expressions, shared path phase, text on a curved or closed path, named actions mixed on a placed scene, depth and the composition camera (2.5D, cards that flip or fan out in depth under an orbit, a 2D film camera's pan, push-in and parallax), motion blur, held drawings (animation on twos), transition firing, and parameter drivers that keep a character alive on their own (eyes looking around, blinks, breathing, hair and ears that follow through, a tail that settles, whiskers that wiggle), with a pointer to the walk, wave and jump cycles of a cartoon rig. Use when motion needs authoring or validation, a character or object should glance, blink, breathe or sway by itself, objects need editable path offsets, text must follow a baseline, a scene validates but renders wrong, or a preset is rejected for the content kind.\nmetadata:\n category: authoring\n version: '1.19'\n ported-from: motion-mechanics 1.19 at 55.128.2\n---\n\n# Saying motion in a scene\n\nThe decision — what a beat is for, how long, which register — is `picsart_scene_recipe motion-intent`.\nThis is the other half: how the format says it, and the places where the obvious spelling is the\nwrong one. For the relationship across beats or the choice of seam mechanism, decide first with\n`picsart_scene_recipe motion-scene-continuity`, then return here for syntax. For semantic grouping, container\ngrowth and sibling reflow, first use `picsart_scene_recipe linked-element-motion`. A common placement owner\ndoes not imply automatic layout. The constructions below need verification in the actual scene.\n\n## Named actions on a placed scene\n\nWhen a placed scene declares fixed motions in its root `actions` map (imported bone timelines,\nparameter motions, authored cut-out poses), its `scene_ref` layer plays and mixes them through\n`content.animation`: a list of entries with `action`, `trim`, `speed`, `loop`, `weight`, `start`,\n`duration`, `fade`, `mode` (`replace` or `aggregate`) and `tier`. A catalog rig's motion presets\nwrite `scene_ref.parameters` bindings instead; those are live controls, not actions. Layer\n`animations` move the whole rig. Mixing, tiers, crossfades without a rest dip, step channels,\n`blending: \"pass_through\"`, a complete walk→idle scene and every refusal are in\n[named-actions.md](references/named-actions.md); the schema is `picsart_scene_capabilities` with\n`sections: [\"schema:ActionAnimation\"]`.\n\n## Two catalogs, two ways in\n\nThey look alike and are applied differently. Getting this wrong is the commonest first failure.\n\n| | Motion looks | Motion presets | Text animations |\n|---|---|---|---|\n| What | entrance/exit (`role: in`/`out`) `fade`, `slide`, `zoom`, `spin`, `wipe`, `blur`, `flip`; entrance `pop`, `flash`; loops `float`, `sway`, `shake`, `pulse`, `glow_pulse`, `blink`, `rotate`, `clockwork`, `ken_burns` | entrances `fade_in`, `slide_in`, `zoom_in`, `scale_pop`, `spring`, `rotate_in`, `blur_in`, `flip_in`, `reveal_in`; exits `fade_out`, `slide_out`, `zoom_out`, `rotate_out`, `blur_out`, `reveal_out`; emphasis `tap_pulse`, `glow_pulse`, `shake`; atmosphere `ken_burns`, `breathe`, `float`, `sway`; paging `step_slide`; secondary motion `settle`, `wiggle` (also on a shape group with `item`); parameter drivers `follow_through`, `random_pulse`, `random_hold`, `cycle` (write a parameter, below) | `typewriter`, `fade_in_chars` (`grow` makes each letter grow in too), `slide_up_lines`, `flicker_chars` (+ ambient ones, below) |\n| Applied with | `picsart_scene_apply_preset` with `look:<id>` (iOS `applyLook`) and `params` (`role`, `length`, …); a window `start`/`duration` is set on the `looks[]` entry with `picsart_scene_patch` | `picsart_scene_apply_preset` with `motionPreset:<id>` (iOS `applyMotionPreset`) | name it in `content.animations[]`, or bake an entrance with `picsart_scene_apply_preset` and `textAnimation:<name>` |\n| Lands in | the layer's `looks[]` | the layer's `animations` / `transforms[]` / `effects`, or `constraints` for layer follow-through | the text content's `content.animations[]` |\n| Named in the document? | yes — `{ \"look\": \"fade\", \"params\": { \"role\": \"in\" } }`, so an editor shows and swaps it | no — the tool expands it into ordinary tracks or layer constraints | yes — `{ \"preset\": \"typewriter\", \"params\": {} }` |\n\n**A preset or a look.** A motion preset is a starting point: it writes ordinary keyframes (and\neffects) that the agent or the editor user then owns and edits keyframe by keyframe. A look stays a\nnamed entry an editor shows and swaps as a whole. Use a preset when the keyframes will be edited\nafterwards; use a look when the motion should stay a named, swappable entry. A one-shot beat at a\nchosen moment (`tap_pulse`, `spring`, `scale_pop`) is a preset.\n\nA look applies to the kinds its `appliesTo` lists. Most motion looks take `color` and `shape` layers\ntoo (`blur` and `flip` take `color` but not `shape`; `wipe`, `flash`, `blink`, `rotate` and\n`clockwork` take neither). For a look that does not list the kind, wrap\nthe layer in a scene asset and apply the look to the `scene_ref`.\n\n`content.animations[]` is a mixed source list: each row is either a named `{preset, params?}` reference\nor a concrete per-glyph `{transform, selector}` entry. Resolution expands every named row before the\nrenderer sees it. Naming keeps the choice editable and can reach a `type: \"text_animation\"` definition\ndeclared in the document's own assets; baking with the tool writes the concrete entries instead.\n\n**Content-kind traps.** `ken_burns`, look or preset, takes `media` / `scene_ref` only, and a look\nor preset on a kind outside its `appliesTo` is `preset_kind_mismatch`. A plain text layer may name either an entrance preset or an **ambient** one\n(`drift`, `flicker`, `hop`, `shake`, `sway`, `throb`, `transform`, `wiggle`). Ambient motion uses\nthe layer's duration as its resolution window; its mode decides whether it is static, plays once,\nloops, or ping-pongs. It selects every glyph. A caption can use the same ambient definition through\na decoration row's `place: \"text\"` field when it needs line/emphasis/highlight selectors instead.\n\n`applied` in the result names the preset once; `entryCount` says how many animator entries it\nappended (a multi-decorator preset like `slide_up_lines` appends two).\n\n### What `picsart_scene_apply_preset` writes\n\n- **Camera presets** (`appliesTo: [\"camera\"]`, e.g. `motionPreset:push_in`, `dolly`, `orbit`) move the\n root composition's camera when `layerId` is omitted, or the camera of the `composition` or\n `scene_ref` layer it names.\n- **Effects** can be confined to a detected region with `mask`: the effect's `supports.effects` row\n says whether it takes one, and the detectors are listed under `supports.maskProviders`.\n- **Text animations** start at the text layer's local time 0: set the layer's `start` to reveal it\n later. An ambient text animation is not baked; it is attached by name in `content.animations[]`.\n- **Looks** wrap the layer's content in an isolated nested composition, so the look treats the\n composited result as one image. By reference (the default) nothing is baked: preview, translate\n and query expand it when needed, and `picsart_scene_resolve_looks` bakes a self-contained scene.\n `mode: \"expand\"` bakes it now: `transform`, `animations`, `blendMode`, `mask` and `motionBlur`\n move onto the wrapper, the layer's own effects apply once before the look, and a track clip bakes\n its whole `looks[]` chain and keeps its slot. A layer with `adjustmentLayer: true` takes no look.\n\n## Where a motion lives\n\nTwo places, and the choice is not stylistic.\n\n**`animations`** — the layer's own Placement tracks (`position`, `scale`, `rotation`, `z`,\n`rotationX`, `rotationY`, `opacity`, `anchor`). Pivots about the layer's own anchor. Always available.\n\n**`transforms[]`** — an ordered stack of motion components applied *outside* Placement, each with its\nown `id` and `animations` (`translation` / `scale` / `rotation` / `z` / `rotationX` / `rotationY` /\n`anchor`), evaluated in array order:\n\n```json\n\"transforms\": [\n { \"id\": \"entrance\", \"animations\": { \"translation\": { \"keyframes\": [ ... ] } } },\n { \"id\": \"breathe\", \"animations\": { \"scale\": { \"expression\": \"return value * (1 + 0.02 * math.sin(2*math.pi*time/3))\" } } }\n]\n```\n\nThe stack exists so **layout stays editable**: `transforms` carries motion (animations, presets) and\n`transform` is the placement a user or host edits. They compose, so editing placement never rewrites\nthe motion, and the motion follows the edit. That is why a `motionPreset:` preset applied with `picsart_scene_apply_preset` routes geometry here. One\ncomponent per motion layer also keeps each independently re-timeable, instead of one `scale` track\ncarrying an entrance and a breathe that can no longer be told apart.\n\nPositions follow After Effects: `transform.position` places the layer's `transform.anchor` in its\nparent's space (the parent layer's own pixels with `parentId`, otherwise composition pixels from the\ntop-left). An omitted `transform.position` is the composition's centre, for a child too: a child\nwith no `transform` sits half a composition into its parent's pixels, so give every child one\n(`[0, 0]` is the parent's origin, the pivot of an `empty` or a shape drawn about `[0, 0]`). An\nomitted component `anchor` is that anchor **where it currently sits**, following a `position`\nanimation and parenting, so a component scale or rotation turns the layer in place even while it\nmoves:\n\n```json\n\"transform\": { \"position\": [300, 300] },\n\"animations\": { \"position\": { \"keyframes\": [ {\"time\": 0, \"value\": [300, 300]}, {\"time\": 2, \"value\": [700, 300]} ] } },\n\"transforms\": [\n { \"id\": \"spin\", \"animations\": { \"rotation\": { \"keyframes\": [ {\"time\": 0, \"value\": 0}, {\"time\": 2, \"value\": 360} ] } } }\n]\n```\n\nMental model: a component is a parent null (After Effects) or a wrapper element (CSS) sitting on the\nlayer's anchor. With no `anchor` it rotates and scales about the layer's anchor wherever the layer\ncurrently is, and `translation` moves in parent pixels.\n\n- **Turn about a fixed point** — give the component an `anchor`: a fixed point in the layer's\n parent space, not the layer's own pixels. It replaces the pivot and does not follow placement edits.\n `anchor: [0,0]` pivots on the parent's top-left.\n- A component's `animations.anchor` is its pivot track, in the same parent space; a layer's own\n `animations.anchor` is layer-local, like `transform.anchor`.\n\n## Easing\n\n`linear`, `ease_in`, `ease_out`, `ease_in_out`, `step` — **plus** a parametric curve:\n\n```json\n\"easing\": { \"kind\": \"cubic_bezier\", \"control\": [0.175, 0.885, 0.32, 1.275] }\n```\n\nCSS convention: `x` stays in [0,1], while `y` may extend beyond it. A control ordinate is not the\nrendered overshoot percentage: the curve, endpoints and timing determine the actual peak. Query or\nrender the peak in the scene before deciding whether it suits the intended motion.\n\n**A keyframe with no `easing` is `linear`.** Use it deliberately for constant-rate travel or progress;\nuse an eased curve when acceleration or settling serves the beat. Easing belongs on the segment's\nstarting keyframe; the terminal keyframe has no following segment to ease.\n\n**Each component on its own.** On a vec2, vec3 or rect value, `easing` may be a list with one easing\nper component, in the value's order: a scale whose width snaps out while its height lags is one\ntrack, not two nested layers.\n\n```json\n\"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0, 0], \"easing\": [\"ease_out\", \"ease_in\"] },\n { \"time\": 0.6, \"value\": [1, 1] } ] }\n```\n\nThe list has exactly one entry per component, and `step` is never an entry (a hold keeps the whole\nvalue). A number or a colour takes one easing.\n\n## Path, separately from timing\n\n`inTangent` / `outTangent` on a `position` or `anchor` keyframe are `[x, y]` velocity handles\nrelative to that keyframe's value — AE motion-path handles. `easing` shapes the timing *along* the\npath; the tangents shape the path itself. Omitted means a straight line, which is why every\nunattended long move is one.\n\n```json\n\"position\": { \"keyframes\": [\n { \"time\": 0, \"value\": [200, 540], \"easing\": \"ease_in_out\", \"outTangent\": [120, -160] },\n { \"time\": 1.6, \"value\": [880, 540], \"inTangent\": [-120, -160] }\n] }\n```\n\nA handle on any other property is dropped.\n\nFor **a path driven by a separate phase**, use tangent keyframes plus\n`ctx:sampleBase(seconds)` on that same property. Read [Shared path phase](references/path-phase.md)\nfor a runnable scene, offset/clamp/wrap choices, clock and sampling limits, and executable checks.\nThis keeps position geometry editable without retiming the card's video. Ordinary timed movement\nstill needs only keyframes; this extra sampling is for independently controlled progress.\n\nFor **text on a curved or closed baseline**, use `content.textPath` rather than\none animated layer per letter. Read [Text on a path](references/text-on-path.md)\nfor geometry, animated offsets, combined character animators and validation. This is distinct from\nmoving an entire object along its position track.\n\n## Expressions\n\nFor an object that turns along its path, keep one authoritative position track and bind\n`animations.rotation.expression` to `positionDirection()`. Do not introduce an auto-orientation\nflag or copy the path into a separate heading track. The artwork's forward-axis correction belongs\nin `transform.rotation`; the expression adds it through `value`. This applies to arrows, vehicles\nand other path followers, not only cursors. Ordinary value reads do not request motion samples;\ndirection/velocity work is on demand when the expression calls it.\n\nRead Cursor-led action (fetch with `picsart_scene_recipe`, name `app-ui-animation`) and its direction reference\nbefore authoring the binding. Through MCP, fetch `picsart_scene_recipe` with `name: \"app-ui-animation\"`,\nthen its listed **Cursor actions and menus** reference. It contains the executable expression, coordinate\nand clock limits, hold/zero-direction behavior and validation. Check heading against independent\ntravel samples, including a changed path and a delayed instance; a valid expression and correct\npositions alone do not prove correct orientation. Use an explicit heading track only when the\nart direction deliberately differs from travel (banking, gaze, a stationary expression's held pose).\n\nA track can carry a Lua `expression` instead of, or on top of, keyframes. It must `return`, sees\n`value` (the keyframed base) and `time` in **layer-local seconds**, zero at that layer's start,\nand returns `Vec.v2(x, y)` for vec2 properties. Moving the layer's start moves the expression's\nonset too; do not subtract that start again. For a nested scene, map root time into the containing\ncomposition first, including reference trim/speed, then subtract the child's start. Keyframe\n`timeMode` does not turn an expression's clock into root time. Check delayed/nested instances with\n`picsart_scene_query_layout` at their mapped start and later moments.\n\n### Bind a supported property instead of copying its track\n\nPrefer a common composition owner for a rigid widget. For a genuine one-way dependency between\nseparate layers, Lua can read a sibling's evaluated Placement, for example on the follower's\nposition track:\n\n```json\n{ \"expression\": \"return ctx.composition:getLayer('driver'):getPlacement():position() + Vec.v2(0, 24)\" }\n```\n\nThis reads an authored sibling id in the same composition; it is not a flattened query id. The\nresult is Placement in that layer's parent space, not its root-space painted center or the result\nof every `transforms[]` entry. Use this offset formula only with compatible parent spaces, anchors\nand intended Placement motion. For shared transform-stack motion, use an owner instead. Self-reads\nof the property being defined and cyclic dependencies are refused. Consult the current expression\nschema for available getters; there is no arbitrary live shape-size or text-metrics getter.\nUnlike `$eval`, this is a per-frame dependency. Validate and query the actual delayed/nested instance;\nlocal `time` formulas on separately started layers need clock mapping even when their text matches.\n\nA value that follows a parameter through drawn poses is a `by` track (see `character-rigging`, \"Poses keyed to a dial\"),\nnot an expression that reads the parameter and interpolates by hand.\n\nTwo compact time-expression uses:\n\n**Ambient motion that continues looping** for the beat's duration:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.15 * math.sin(2*math.pi*time/2))\" }\n```\n\nThe coefficient varies the base scale by ±15%. Its literal two-second period does not change when\nthe beat duration changes; adjust it explicitly to preserve a chosen cycle count. Inspect the\nresulting bounds, final phase and reading comfort.\n\n**A real spring** — a damped oscillation, which one `cubic_bezier` cannot express:\n\n```\n\"scale\": { \"expression\": \"return value * (1 + 0.35 * math.exp(-6*time) * math.cos(18*time))\" }\n```\n\nThe expression alternates around the base value with diminishing amplitude. Raise the\n`exp` coefficient to settle sooner, the `cos` coefficient for more bounces.\n\n### The `picsart.*` stdlib — the recurring shapes, already written\n\nThese are built in. Reach for them before\nhand-rolling the trigonometry. Call them directly as `picsart.<name>(...)`; an alias such as `local p = picsart` is not supported.\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, 0.3, 1, 0.7)\" }\n\"position\": { \"expression\": \"return picsart.jitter(value, time, 16, 11, 0.3)\" }\n\"rotation\": { \"expression\": \"return picsart.wiggle(value, time, 2, 4)\" }\n\"scale\": { \"expression\": \"return Vec.v2(picsart.oscillate(time, 1, 1.05, 2), picsart.oscillate(time, 1, 1.05, 2))\" }\n```\n\n- `picsart.oscillate(time, low, high, halfPeriod)` — smooth low↔high, starting at `low`, one half cycle\n every `halfPeriod` seconds. A vec2 property takes one call per component inside `Vec.v2`.\n- `picsart.jitter(value, time, ampX, ampY, step)` — deterministic shimmer around the layer's own base\n `value`, resampled every `step` seconds. Not random: same inputs, same frame.\n- `picsart.wiggle(value, time, freq, amp [, octaves=1, ampMult=0.5, seed=0])` — AE's `wiggle`, fractal\n noise at `freq` wiggles/sec, per component on a `Vec`.\n- `ctx:loopOut(mode)` — repeats the track's keyed range past its last key. Key ONE cycle, loop it:\n `\"cycle\"` restarts every range (a breath, a foot's roll), `\"pingpong\"` plays every other range\n backwards (a wave), `\"offset\"` restarts each range shifted by its last-minus-first value (anything\n that travels: a stride, a walking body), `\"continue\"` extends along the slope at the end it leaves.\n `{\"keyframes\": [...], \"expression\": \"return ctx:loopOut('cycle')\"}`. Before the first key the\n track holds that key.\n- `picsart.cycle(time, waveform, from, to, period, phase [, variation, seed])` — a `\"sine\"`,\n `\"triangle\"`, `\"saw\"` or `\"square\"` wave: `picsart.cycle(time, \"sine\", 0, 1, 3.5, 0)`.\n- `picsart.randomPulse(time, from, to, minInterval, maxInterval, attack, hold, release, burstChance, seed)`\n — seeded random events, each eased `from` -> `to` and back: a blink.\n- `picsart.randomHold(time, from, to, minInterval, maxInterval, transition, seed, channel [, centerBias, half])`\n — a seeded random value held, then eased to the next on `picsart.randomPulse`'s timing; `half`\n `\"both\"`, `\"positive\"` or `\"negative\"`: a glance.\n- `picsart.follow(time, read, frequency, damping, amount, segment)` — a damped spring trailing `read(t)`:\n lag, overshoot, settle (hair, tails, a dangling arm). It follows PARAMETERS; see\n [Secondary motion](#secondary-motion-and-characters) for `segments`, one value per piece\n of a chain of any length.\n- `picsart.clamp(v, low, high)`, `picsart.linear|ease|easeIn|easeOut(t, tMin, tMax, v1, v2)` — AE's\n interpolation set, held outside `[tMin, tMax]`; `v1`/`v2` a number or same-arity `Vec`:\n `picsart.ease(time, 0, 0.4, 0, 1)`.\n- The four `picsart.cycle` / `picsart.randomPulse` / `picsart.randomHold` / `picsart.follow` calls are what the\n `cycle`, `random_pulse`, `random_hold` and `follow_through` presets write\n ([Parameter drivers](#parameter-drivers)). Apply the preset rather than writing the call.\n\n**Reading another value at a time.** `ctx.composition:getParameters():<name>([t])` is a parameter\nat `t`, seconds on the reader's clock (default now): `p:headTurn(time - 0.25)` trails a quarter\nsecond. `ctx.composition:getLayer(id):getPlacement():position([t])` / `rotation([t])` / `scale([t])` is that\nlayer's placement at `t`, seconds on the reader's clock with the layer's own clock applied:\n`position(time - 0.2)` trails it by 0.2 s. The layer is one of the same composition; a timed read\nof a layer that plays on another composition's clock fails the frame. Without `t` it reads this\nsame instant (see \"Bind a supported property instead of copying its track\"). `getSocket` and `getSocketDirection` on a layer read a placed character's published sockets (`character-rigging` \"Standard sockets\").\n\n**In a DEFINITION** (a look, a transition, a decoration) `{param}` splices the definition's own\nscope into the expression text, so the shape stays parametric:\n\n```\n\"opacity\": { \"expression\": \"return picsart.oscillate(time, {glow} * 0.3, {glow}, 0.18 / {speed})\" }\n```\n\n`{name}` there is a raw TEXT splice, not a typed lookup — it drops the param's number into the Lua\nsource, so surrounding arithmetic is Lua's. (Everywhere OUTSIDE an `expression`, `{name}` is the\ntyped scope lookup instead.) `picsart_scene_capabilities` lists the full stdlib.\n\n## Parameter drivers\n\nFour presets write a number parameter's `default`, applied with `picsart_scene_apply_preset`\n(`motionPreset:<id>` and `\"parameter\": \"<name>\"`); the layers read the parameter, so one value drives\nevery part that shares it.\n\nOn a cartoon rig (a `scene_ref` layer drawing `scene://rig-humanoid` or `rig-face`), pass the rig\nlayer as `layerId` and its control as `parameter` (`random_pulse` on `blink`, `cycle` on `breath`):\nthe track is bound on that layer, so each instance moves on its own. The rigs and `walk_cycle` are in\n`character-rigging`.\n\n| Preset | The value | Typical uses |\n|---|---|---|\n| `follow_through` | the swing of a damped spring trailing other parameters | hair, ears, tails, antennae, a dangling sign |\n| `random_pulse` | brief eased events at seeded random intervals (`minInterval`, `intervalSpread`, `attack`/`hold`/`release`, `burstChance`) | blinks (`eyeOpen` from 1 to 0), lamp flicker, twinkling stars, glitch hits |\n| `random_hold` | a seeded random value held, then a quick eased jump (`transition`) to the next, `minInterval` + `intervalSpread` apart; one `seed` shares the jump times, `channel` picks the value stream, `half` keeps its `positive` or `negative` side, `centerBias` gathers values mid-range | eyes looking around (`lookLeft`/`lookRight`/`lookUp`/`lookDown`), random pose or colour picks, a jittering needle |\n| `cycle` | a repeating `sine`/`triangle`/`saw`/`square` wave every `period` seconds | breathing (`breath`, sine ~3.5 s), bobbing, a pulsing glow, UI pulses, beacons |\n\nDrive eyelids or the eyes' y-scale from `eyeOpen`; drive chest or shoulder scale and a small head\nbob from `breath`. A different `seed` per character keeps two characters from blinking together.\n\nEyes that look around: give each eye a `composition` layer holding its white and its pupil. Mask the\npupil with a clip that repeats the white's own `transform` and shape: a clip keeps its own transform,\nso inside the eye it lands exactly on the white and the pupil never leaves it. A clip on the eye layer\nitself does not sit on the white, and the eye draws nothing. The gaze is four one-sided 0..1 parameters,\nthe standard expression names `lookLeft`, `lookRight`, `lookUp`, `lookDown`. The pupil's position reads\nthem, `value + Vec.v2((p:lookRight() - p:lookLeft()) * r, (p:lookDown() - p:lookUp()) * r)` with\n`p = ctx.composition:getParameters()` and `r` the room the white leaves. Apply `random_hold` to all four\nwith one `seed` and `centerBias` about 0.5: `lookRight` channel 0 `half: \"positive\"`, `lookLeft`\nchannel 0 `half: \"negative\"`, `lookUp` channel 1 `positive`, `lookDown` channel 1 `negative`. The eye\nnever looks left and right at once, and both axes jump at the same moments, as a glance does.\n\n## Secondary motion and characters\n\nPick by what moves the part: a rig control (a head turn drives the hair) is parameter-mode\n`follow_through`; a parent layer's world motion, under gravity or wind too, is layer-mode\n`follow_through` (`layerId`, a layer constraint); a keyed part that should carry on past its own stop\nis `settle`; a part that never holds still is `wiggle`; a slow regular loop is `sway`; an impact is\n`shake`. Layer-mode springs, their ranges and starting values per part, a worked five-link hair chain,\nnested clocks, seeking cost and pitfalls are in [secondary-motion.md](references/secondary-motion.md).\n`settle` and `wiggle` on a layer or, with `item`, on one named group of a `shape` layer (a drawn tail,\nantennae, whiskers) are in [settle-and-wiggle.md](references/settle-and-wiggle.md).\n\nHair, ears, a tail or an antenna that lag a turning head are one parameter following others through a\ndamped spring: apply `follow_through` to the PARAMETER (`\"follow\"` lists the driving parameters with\ntheir weights; `frequency` and `damping` set the lag), never write the spring yourself. Its value is\nthe swing, 0 while the drivers hold still. A chain of any length takes one value per piece through\n`segments`. The full recipe, with the parameter wiring and the units, is in `character-rigging`\n(fetch with `picsart_scene_recipe`, name `character-rigging`).\n\nA sketchy, hand-inked look comes from the `line_boil` preset on a shape's `path` items: each outline\npoint sits up to `amplitude` px off its place and takes a new one `rate` times a second, where `shake`\nmoves the layer and a group `wiggle` moves a part rigidly. Worked calls, `item` for one outline and the\nrefusals: [references/line-boil.md](references/line-boil.md).\n\nA character that walks, waves or jumps from a few looped keys, a shape's outline that morphs, bends or\nis swapped (`vertices` tracks, `deformers`, outline expressions), bent limbs and two-bone `ik` foot\ntargets are all in `character-rigging` as well. Pose the catalog rig (`rig-humanoid`, `rig-face`) when it\nfits; build by hand only when it does not. A humanoid rig holds a prop itself through its `held` parameter, and a `reach` constraint on its instance layer (`{\"type\": \"reach\", \"socket\": \"rightHand\", \"target\": {\"layer\": \"ball\"}, \"mix\": 1}`) puts a hand, foot or the `seat` on a stage point: both in `character-rigging`. Within a shape's `items`, and a group's `contents`, the\nfirst item paints on top, as After Effects stacks layers: list a face's mouth and eyes before the head\nthey sit on.\n\n## Held drawings: animating on twos\n\nA nested composition (an inline `composition` or a `scene_ref` body) whose `composition.fps` is\nLOWER than its host's rate draws on its own frame grid: every host frame shows the start of the\nnested frame it falls in. `\"fps\": 12` inside a 24 fps scene is animation on twos, the stepped look of\nhand-drawn animation, without duplicating a keyframe. The hold covers the whole composition:\nkeyframes, expressions (their `time` is the held one, so a wobble boils on twos), media, Lottie and\nnested playback, which of its layers are live and reads between its own layers. A held frame keeps the\nmotion blur of its own instant. An effect's rolling seed follows the host clock (the grain is the\nfilm, not the drawing), and sound is not held: audio inside plays on the host clock.\n\n```json\n{\"id\": \"character\", \"content\": {\"kind\": \"composition\",\n \"composition\": {\"width\": 1080, \"height\": 1080, \"fps\": 12},\n \"layers\": [{\"id\": \"ball\", \"content\": {\"kind\": \"shape\", \"items\": [\"...\"]},\n \"animations\": {\"position\": {\"keyframes\": [{\"time\": 0, \"value\": [100, 500]}, {\"time\": 1, \"value\": [900, 500]}]}}}]}}\n```\n\nAn equal or higher rate, or none, holds nothing. A rate that does not divide the host's holds\nunevenly (24 in 30 is a pulldown), so pick a divisor of the output rate. Put whatever must stay\nsmooth, such as a camera move, outside the held composition. Measure the result per frame: the ink\ncentroid moves only on the nested frames.\n\n## Depth and the camera\n\nEvery composition is seen through one perspective camera, `composition.camera`. Omitted, it is the\ndefault: pivot at the composition centre, `distance` `width * 50 / 36` (a 50 mm lens), no orbit. On\nthe `z = 0` plane that draws exactly the flat composition, so depth costs nothing until a layer asks.\n\n| Field | Meaning |\n|---|---|\n| layer `transform.z` | depth in composition px, **positive toward the viewer** |\n| layer `transform.rotationX` / `rotationY` | tilt in degrees, the `perspective_3d` effect's signs: +X tips the top edge away, +Y turns the right edge away; `rotation` stays the clockwise roll |\n| `camera.position` | the pivot that zoom, roll and orbit turn about. The camera does **not pan**: moving only the pivot leaves every `z = 0` layer where it is, so pan with a parent layer ([film-camera.md](references/film-camera.md)) |\n| `camera.zoom` | image scale about the pivot — perspective unchanged |\n| `camera.distance` | eye-to-pivot px, > 0; the `z = 0` plane keeps its size at any distance, so animating it is a **dolly zoom** (nearer layers grow, farther ones shrink) — a push-in is `zoom` |\n| `camera.rotationX` / `rotationY` | orbit of the eye: the view is the inverse of a layer rotation of the same values (eye right = world turned left) — +X raises the eye, +Y moves it right |\n\nThe layer matrix is `T(x, y, z) · Rx · Ry · Rz · S · T(-anchor)` (intrinsic XYZ, as `perspective_3d`); `anchor`, `scale` and `position`\nstay `[x, y]`. All six layer/camera depth fields animate like any track; a layer's `animations.z`,\n`rotationX` and `rotationY` are replace-only, and motion components carry them too, so a preset can\nflip a card in depth.\n\nLayers in one run of camera-participating, non-adjustment layers draw **far to near**, re-sorted\nevery frame; equal depth keeps document order. `cameraExempt: true` on a root keeps its subtree flat\nand in place (a HUD). A mask follows its host's plane and carries no depth of its own. A nested\ncomposition, `scene_ref` or track has its own camera and is drawn as ONE flat card at its layer's\n`z` and tilt — put layers that must interleave in depth in the same composition. A look (such as\n`rounded_corners`) keeps its layer's depth, tilt and draw order. A look that turns its layer\n(`flip`, `tilt_3d`, `tilt_reflection`, tagged `2.5d`) adds that turn to the layer itself as a\n`look:<id>` motion component, so the composition camera draws it and it moves with an orbit.\n\nCamera moves ship as motion presets: `orbit`, `dolly` and `push_in`, each `appliesTo: [\"camera\"]`.\n`picsart_scene_apply_preset` with `motionPreset:<id>` and no `layerId` keys them onto the root composition's camera as editable\ntracks; their parameters are listed under `supports.motionPresets` in `picsart_scene_capabilities`.\n\nDepth is verified by measurement. `picsart_scene_query_layout` reports each projected layer's `quad`, `depth`\n(eye distance, larger is farther) and `zIndex` (this frame's paint order). In `picsart_scene_lint_layout`, a\nrelationship `{ \"kind\": \"order\", \"axis\": \"depth\", \"members\": [...] }` (members front to back) checks the\nstack over a window, and `covered` names each layer left under half visible by the layers drawn after it.\nAn overlap between two planes stays a collision finding, annotated `depthStacked` (`near`, `far`): judge\nwhether the stack is intended, with `covered` as the check for text it hides.\n\nThree laws for a scene in depth:\n\n1. **A label rides its plane.** Make it a child of the plane (`parentId`) with no `z` of its own: it\n takes the plane's depth and tilt and draws in front of it. A label given its own `z` floats free\n of the plane and sorts on its own.\n2. **Titles and HUD stay flat.** Make them `cameraExempt: true` roots.\n3. **Read the orbit's sign, don't guess it.** `camera.rotationX > 0` raises the eye, so nearer planes\n project LOWER on screen; the classic exploded diagram, front plane highest, is `rotationX < 0`\n (measured: a four-plane stack at `distance` 2400 under ±42°). Render one frame at the held orbit\n before building on it.\n\nA 2D film camera (a pan on an empty `world` parent, a push-in on `camera.zoom`, parallax by depth,\na sky kept still with `cameraExempt`) is in [film-camera.md](references/film-camera.md).\n\n## Motion blur\n\n`\"motionBlur\": true` on the layer smears it along its own motion, keyframed or expression-driven.\nIt is what makes a fast move read as speed rather than a teleport. `composition.motionBlurSampleCount`\nsets the shutter samples per frame (clamped 1..64); omit it for the default (16). It is refused in a\ncomposition whose camera orbits or whose layers author depth (`motion_blur_3d_unsupported`).\n\n## Transitions\n\nA `transitions[]` entry needs `between` — which seam of the track it sits in — as well as `id` and\n`duration`. Omitting it fails `transition_between_out_of_range`, which names the legal range.\n\nEvery shipped transition fills the `duration` it is given: its keyframes are written against the\nwindow, so a longer window is a slower move — `card_flip` goes edge-on exactly at the seam, as\nauthored. None plays a video or lottie matte (those families were removed: their `.webm` mattes do\nnot decode on iOS).\n\n## Validate the mechanism and its result\n\nFor reversals, jumps, overshoot, acceleration peaks or settling, inspect the actual output-frame times. Read [Frame-complete motion validation](references/frame-motion-validation.md) for independent thresholds and coverage limits. Run `picsart_scene_check_motion` with an explicit root-time window and the actual export FPS; explicit queries cover only the times actually requested. Do not claim frame-complete evidence unless every relevant frame and channel was compared. Construct rigid relationships with a shared owner or supported binding first; numerical checks do not replace ownership or visual inspection.\n\nRead `picsart_scene_recipe motion-pattern-library` and fetch its **Validation by pattern** reference\nbefore accepting a motion. Use its **mechanics**\nrows for pivots/transform order, easing, local clocks, expressions, text selectors, and motion blur;\nuse its pattern rows for the intended beat. `picsart_scene_validate` accepts structure, not choreography.\nQuery evaluated geometry at the decisive events and extrema; run supported relationship contracts;\ninspect rendered frames and playback for paint-only effects and perceived timing. Never substitute\nauthored keyframe values or a successful export for evidence that the evaluated result is correct.\n\n## When it renders wrong\n\n| Symptom | Look at |\n|---|---|\n| `preset_kind_mismatch` | a look or preset on a content kind outside its `appliesTo` (`ken_burns` on a non-media layer) |\n| `unknown_text_animation_preset` | the name is absent from both the document and shipped text-animation catalogs |\n| `invalid_text_animation_params` | a named text animation has a missing, unknown, or out-of-range parameter |\n| the layer slides while it scales | a component `anchor` explicitly set to `[0,0]` |\n| a transition fires but feels wrong | a mask-driven one whose `duration` is not its `sweep` |\n| motion reads mechanical | `easing` omitted somewhere — that is `linear` |\n| a layer moved in `z` does not reorder against a sibling | the sibling sits in another composition (a nested card), or a `cameraExempt`/adjustment layer splits the run |\n"
}SHA-256 of public snapshot: f03d2f24b34fad7ec0008332250b3622184a0721b65665745ef62953a15a9e4f