ByteTerrace/Puck / .claude/skills/sdf-authoring
sdf-authoring
VerifiedAuthors creations: shape rows, primitives, blends, folds, palettes, paints, render lanes, rigs, bake work and bytes, creation stats. Use to sculpt or fix a part. Grammar: puck-dsl; GPU: rendering.
references/rig.md
View on GitHub# Rig, motion, and the rest of the creation document
Everything here is presentation only, read by the client's stamp pool. None of it
moves a collider or the simulation.
## Attaching a shape
| Field | Meaning |
|---|---|
| `parent` | the `name` of a shape declared **earlier**, whose animated motion carries this one, pivots included. This is the skeleton. Null means the creation root |
| `joint` | the point the shape turns about: an effector's solve turns a bone about it. Without one, the pivot of its first swing, else its own position (`CreationRig.Joint`). It poses nothing on its own |
| `swings` | rotations about a pivot, any number, composed in the order written |
| `slides` | translations, any number, applied after every swing |
Because a parent must be declared earlier in the list, a chain resolves in one
pass and can never cycle. The refusals are
`names no shape '<parent>'.` and
`parent '<parent>' must be declared before the shape it carries.`
A swing is `{ driver, pivot, axis, amplitude, phase, wave }`, rotating
`amplitude × wave(phase + φ)` radians about `axis` at `pivot`; amplitude is
capped at π except for the `linear` wave. A slide is the same shape without a
pivot, in creation units, capped at 4.
`wave` is `sine` (the default), `halfSine` (`max(0, sin)`), `linear` (the
argument itself, unbounded), `constant` (1, so the facet is a pose the driver's
weight blends in), or `curve:<row>`, which samples a world `curves` row by arc
fraction: the argument's fraction of a turn maps onto the row's arc length and
the sampled Z is the value. A curve wave on a `state.<row>` driver is how a part
holds still until a cell crosses a threshold and then moves: draw the row flat
to the threshold, then rising, and pick the cadence that maps the cell's range
onto one turn.
A live edit of `parent`, `swings` or `slides` (`world.row.set`, `world.row.add`,
`world.reload`) applies on the next frame: any change to a creation's content
changes its hash, and the stamp pool replaces the registration, re-resolving
the parent chain, the effectors and the tight group bounds from the edited
document. `parent` carries only the parent's animated delta, so a shape
reparented at rest does not move until the new parent's motion differs from the
old one's. `body.rig <body> <shape>` reads back the parent the shape's motion
chains under and the delta the last frame composed for it
(`shape:<name> parent=<name>|root delta=(x, y, z) turn=r`).
`WorldCreationInstancesLiveRigEditLawTests` pins both edits through the scene emitter.
A placement anchor naming a shape (an audio emitter, an overlay subject, a
camera view's `placement` anchor) reads `WorldCreationInstances.TryShapePosition`, which
answers where the last frame drew the shape: its rest or frame pose under the
composed delta (own swings and slides, the parent chain, effector corrections)
and its part follower. It reads the latch `PackRegistration` left, the same one
`TryBodyPartAuthoredPose` reads (`LatchedShapePose`), and evaluates no rig of its
own. `WorldCreationInstancesLiveRigEditLawTests` pins it to the drawn slot every frame.
A shape carrying `domain` folds may carry neither, since a fold rides its
parent's frame. It may still carry a `parent`: the folded shape shares its motion
owner's slot, packed with the rigid delta the parent's chain imparts (identity
with no parent, translation in placement units), and its chain applies
`Scale(placementScale)`, the domain ops, then its own rest pose, so the fold
plane travels with the parent's driver and effector motion at any look scale.
Its cull bound rides that slot with the static stamper's `RenderReach` radius.
It refuses a named `frames` entry and a look `partDynamics` follower, and a frame
posing its parent moves the parent alone, since a frame replaces a base pose
outside the delta chain. A `parts` entry may name it: `TryBodyPartPose` and
`TryBodyPartAuthoredPose` compose its rest pose onto the carried frame and agree.
`CreationDomainParentLawTests` pins this.
## The compiled rig
Every reader of motion takes the creation's compiled rig (`CreationRig`,
`WorldPrototype.Rig`), never the document's facets. It lists each shape's
writers (`CreationRigWriters`): the terms its drivers play (each swing in order,
then each clip's turn in clip order, then each slide and keyed slide), an effector's solve on every bone of its chain, an effector's
`align` on its tip whether or not the tip is a bone, a timeline frame that poses
it, and, for a look, a part follower (`CreationRig.Follow`). A shape with any
writer owns a transform slot (`CreationRig.Owner`), and a creation with none is
rigid. The document every renderer, collider and anchor reads
(`WorldPrototype.EngineDocument`) carries no swings, slides or clips, and
`CreationRig.Compile` refuses it, so no reader can move a shape around the rig.
The rig also lists what the pose reads from outside (`CreationRig.Reads`):
state cells as truth or eased, body facts, the body's motion, time, a surface
probe, another body and curve rows. The pose pass reads only through
`WorldRigReads`, which answers those reads and nothing else; its revision is
what the wake test hashes, so a hand on another body follows that body when only
the target moves, and the presentation manifest registers exactly the state
cells in the list. A body another rig reads is rated no slower than its reader.
`CreationRig.Reach` is how far the rig can carry any point from the root,
derived from the pivots on each shape's chain and the slides' limits; the rate
tiers judge a body unseen by it. A slide with an unbounded wave, a state-bound
pivot or a follower has no finite reach, and `puck creation stats` names which
(`rig: ... reach unbounded: <why>`), with each moving slot and its writers.
## Drivers
`sizeBy: "state.<row>[.<key>]"` reads a numeric authority-state value, clamped
to [0, 1], and uniformly scales the creation about its origin. It reads stored
truth, without a presentation driver, easing or a driver weight. Author the
origin where contraction should end; author any cadence, gate or smoothing as
state rules or state dynamics. A solid's size is sampled before body motion,
checkpointed with the moving root, and published in the tick's snapshot, so its
drawn root uses the size contact actually read even when a later rule writes a
new value. Attached solids may use `$body` for their carrier's keyed state.
At zero it hides and contributes no contact. Growing and shrinking supports use
the same ride, step-up, snap, depenetration and sleeper-wake path as translated
supports. The support's material point supplies the ride; the body's skin and
overhang do not scale, and the ride sweeps against every other solid. A solid
born at zero lifts an intersecting grounded body onto its new support surface.
Relief, blend radii and the solid's authored contact margin scale with that root;
query padding and the body's contact skin stay in world units. The local mesh stays
baked. The debug glacier is the standard family's example.
`drivers` is any number of named `{ name, signal, cadence, when, blendInSeconds,
blendOutSeconds, dynamics, cadenceBy, weightBy, parts, mode, lead, leadSeconds }`. Everything
animated names one. They advance in declaration order, and a driver reads only
drivers declared before it, the rule a shape's `parent` follows.
A driver is a layer. `parts` (part ids) is its mask: its swings, slides and
clip poses play only on the shapes those parts cover (omitted, the shapes it
poses), and a motion it authors outside its mask is warned about (PUCK132), not
refused. `mode` is `add` (default) or `replace`: a replacing driver of weight
`w` scales every driver declared before it by `1 - w` on its mask's shapes and
nowhere else, so a stance takes the arms from the gait, the run and the jump
without editing them. A driver's share on a shape is its weight times `1 - w`
for each replacing driver declared after it that covers the shape
(`CreationRig.Share`, the one place a share is formed); every swing, slide and
clip term uses it, and a term at share zero is skipped. Declaration order sets
shares only: the order turns compose in on a shape is the shape's own, so a
driver's row can move above or below a stance without changing how the turns
interleave. A replacing layer at weight zero leaves every pose bit for bit as it
was.
A smooth seam's envelope (`CreationMotion.Envelope`) counts each swing and slide
in full and a shape's clip turns as one turn about its joint
(`CreationMotion.ClipLimit`): each adding driver's tracks on the shape summed,
plus the largest such sum among replacing drivers. The seam box is the overlap
of the two parts' boxes widened by the smooth radius `k` on every side, so the
reach from any joint inside it is at least `√3·k`, and a clip turn over about
16.6 degrees at a joint cannot skin whatever `k` is.
| Signal | Behavior |
|---|---|
| `planarTravel`, `travel`, `time` | integrate |
| `speed`, `verticalSpeed`, `turnRate` | set directly; `speed` is ground speed in m/s read per frame (vertical travel reads zero, and so never trips `moving`; a read is capped at 60 m/s, never by the frame's length), `turnRate` is positive turning left; a frame that charges no time (a capture renders its held frame with none passing) holds all three phases, since travel over zero seconds would read as standing still |
| `travelDirection` | set directly: eased planar travel off the facing, (−π, π], 0 forward, π backpedal, positive left; holds at rest |
| `lateralAcceleration`, `forwardAcceleration` | set directly: eased planar acceleration across (positive left) and along (positive forward) the facing, m/s² |
| `state.<row>[.<key>]` | set directly: the cell's numeric value at the frame's tick, times the cadence, is the phase (a cycle-trait clock, a counter, an `hp` cell) |
| `driver.<name>` | set directly: cadence × the phase an earlier driver reached this frame, so several drivers ride one cycle (cadence 2 is twice its rate) and never leave step |
`dynamics` names a world `dynamics` row a setting driver's phase follows through
(second-order: trail, overshoot, settle). An integrating driver and a
`driver.<name>` driver refuse it; the world validator refuses an undeclared row.
`lead` (an input channel's name) and `leadSeconds` (default 0.25) let a
state-cell driver show the presenting seat's own press before the authority's
answer is drawn: a guess, which colours only that seat's own presented picture.
The guess is a separate pose layer (`WorldCreationInstances.Guess.cs`): the stamp
pool of the world the seat's body is in (`WorldClient.SeatGuessAt`, offered only
while the client presents one seat) poses that body a second time with a guessing
view (`WorldRigReads.ForGuess`) into rows past its own, and only the seat's own view
reads those rows (`WorldCreationInstances.GuessOverlay`, carried as
`SdfViewSnapshot.PoseOverlay` and read through `sdfViewPoseSlot`). The shared pose
every other reader resolves (part anchors and part-anchored cameras, carried
screens and so the pointer ray, other bodies' effectors, rates, the other views,
camera screens and session windows) never reads a lead: a pool registration's view
answers none and refuses a guess (`WorldRigReads.BindGuess`). In the layer, while
that seat is admitted with no lost capture, the channel is live in the mapping the
authority last published, and an edge the seat sent on it (a press, a release or
an axis sample) has not had its answer presented, the phase follows the seat's own
folded level in place of the cell, for at most `leadSeconds` of presented time
(the frames' summed delta, so it repeats under lockstep), never the wall clock.
The outstanding test is `WorldSeatInput.TryLead`, over `WorldSeatInput.ReadGuess`,
and the authority never reads `lead`. The answer is `WorldInputAnswer` (the epoch,
the highest event sequence of the last batch of the owner's current epoch the
authority took or refused, and the tick it answered in), written through
`WorldInputRuntime.Answer` before any check that can refuse the batch and
delivered to that owner alone; the client reads it under whichever owner the
route's authority publishes the body's input as (`WorldSessionMirror.TryInputOf`),
and marks an edge answered once that tick is fully presented, so a later delivery
without the answer revives nothing. `body.rig` prints the shared pose's drivers;
the layer's as `layer:<driver> phase=… source=lead|cell`; and, for a seat's body
and in a headless World too, a `guess:<creation>.<driver>[<channel>]=` reading of
the seat side (`WorldClient.DescribeGuess`): `off(<why>)` when this client offers
the seat no guess, else `lead` or `cell` with the state, the seat's outstanding
event sequence, the authority's answer (epoch/sequence@tick), and the presented
tick and fraction. A headless World presents every tick whole, so it never reads
an edge outstanding, and poses no creation, so it prints no `layer:`. Refused by name: `lead`
on a signal that is not a state cell, `leadSeconds` without `lead`, and (world
validator) a channel that is not declared, or is relative or text.
`cadenceBy` and `weightBy` are each `{ driver, curve }`: the height (Z) of a
world `curves` row where its X equals that earlier driver's phase, held at the
end knots outside the row. `cadenceBy` multiplies the cadence every frame, so a
stride on `planarTravel` whose radians per metre fall as a `speed` driver rises
lengthens its stride with speed. `weightBy`, clamped to [0, 1], is the level the
weight eases toward while the gate holds instead of 1, through the blend times
(in while it rises, out while it falls); a `driver.<name>` driver weighted by a
rising curve of speed fades a run's swings in on the same cycle a walk's ride.
The curve row must be open and drawn left to right, each knot further along X
than the last with its tangent toward +X, or the world validator refuses it.
Author each knot's `tangentYaw` and `curvature` from the function it samples
(`atan(f′)` and `f″/(1+f′²)^1.5`): a straight segment at a slant does not
compile, because its fixed-point tangents never line up exactly with its chord.
A driver with neither keeps its authored cadence and eases its weight toward 1.
`CreationCharacterLawTests` pins the three.
`cadence` is capped at 256 in magnitude. `when` takes up to 4 gate tokens from
the body-facts vocabulary plus `moving`, `still`, and `always`; `always` may not
appear in a conjunction and `moving` with `still` is refused. Blend times default
to a 0.15 second ease. `blendInSeconds`/`blendOutSeconds` are finite
non-negative exponential time constants; zero is immediate on a positive render
delta. They control gate weights independently of phase cadence and the shared
movement-speed filter (`CreationAnimationLawTests`).
## Pose clips
`clips` is any number of `{ name, driver, keys, wrap, period }`: key poses on
joints that interpolate, played by one driver whose phase is the position in
the clip and whose weight is the blend. A key is `{ at, ease, poses }`, and a
pose is `{ shape, turn, slide }`: `turn` is a list of `{ axis, angle }` steps
composed in the order written (the first turns first; `angle` takes `deg`), and
`slide` a translation. Both are literal, measured from the shape's rest pose,
and turn it about its joint (`joint`, else its first swing's pivot, else its
position; `CreationRig.Joint`), so a keyed forearm carries the hand. A pose
with neither is the rest pose: write it at the clip's start, or a track begins
at its only key. A clip's turn crosses the author frame as a swing does.
A shape's track is the keys that pose it. The compiler stores each key's
composed turn as the one quaternion with a positive scalar
(`CreationClipCompiler`), and between keys the turn follows the arc between
them with no change of sign (`VectorFunctions.Arc`): a quarter turn to the
opposite quarter turn passes through rest, and the turn never exceeds the
larger of its two keys, which the seam bound relies on. `ease` (on the key the
stretch arrives at) is `linear` (default), `smooth` or `hold`. A driver's share
scales the interpolated turn's angle about its own axis and the slide's length.
On a shape, swings compose first, then clip turns in clip order, then slides and
keyed slides.
A held clip (the default) holds a track's first key before it and its last key
after it. A looping clip (`wrap: true`) reads the phase modulo `period` (one
turn unless authored, every key inside it), and its last key interpolates back
to its first. A travel or time driver wraps its phase every turn, and one that
follows it wraps over one turn times its cadence, so such a phase plays only a
looping clip whose period divides that span; a held clip is played by a level
(a state cell, a rate signal or a driver following one). Refused by name: a
held clip on a wrapping phase, a period that does not divide the span, a
`cadenceBy` or state-bound cadence on the follower of a wrapping driver, a key
out of order or outside the period, an unknown driver or shape, a shape with
domain folds, and a composed turn of a half turn or more.
## Chains and effectors
When every surface effector reports `target=none`, check the presentation query
field before changing probe reach or geometry. `WorldFramePresenter` builds the
field used by camera clearance and limb probes; `WorldPlacementStamper.Queryable`
excludes unsupported placements individually, as the motion CLI's camera check
does: one the contact evaluator refuses, or one whose own field cannot answer at
its copies (its frame stops short of them), which would otherwise shrink the
combined field's frame and refuse every query. The log names each excluded placement and reports a combined-field failure
as `[world.presentation-field: unavailable; ...]`. An excluded prop has no query
surface, but cannot remove the supported floor and other placements. `body.rig`
reads the last packed rig; a read scheduled before a screenshot is not a read of
the new frame that screenshot will compose.
`chains` groups shape **ids** root to tip. `kind` is `limb` or `spine`; null
resolves to `limb` when there are exactly three shapes, and a `limb` with any
other count demotes to `spine`. A chain naming a missing shape id is dropped.
`effectors` is any number of CCD solvers, `{ name, chain, tip, target, when, weight,
plant, align, weightBy, blendInSeconds, blendOutSeconds }`, where `chain` and `tip`
name shapes **by name**, 2 to 8 bones, solved over 64 iterations. Effectors solve
after every driver, in declaration order, each on the pose the one before it left:
a constraint on the final pose, so motion a later layer adds to a constrained chain
shows above the tip and not at it. An effector writes every bone of its chain and,
when it aligns, its tip (`CreationRigEffector.Writes`).
A `target` is `{ kind }` of `surface`, `body`, `state`, or `shape`:
| Kind | Fields |
|---|---|
| `surface` | `direction` (author frame, nonzero), `reach` in (0, 8], `standoff` ≤ 1 |
| `body` | exactly one of `index` (fixed) and `reference` (a numeric `state.<row>[.<key>]` holding the body's index, read as stored truth: a whole number naming an active body selects it, anything else selects none, so zero is body zero and -1 clears it); `part` (optional, a part id the body's look publishes, read as last drawn, the root when it publishes none); `offset` ≤ 16 riding the target's attitude |
| `state` | `reference` = `state.<row>[.<key>]` holding a world-space point |
| `shape` | `shape`, a shape of the same creation; `offset` ≤ 16, a rest point in the author frame that rides the shape (omitted, the shape's origin); `direction` (optional), the approach the shape carries, whose reverse is the normal `align` turns the tip onto |
A `shape` target is read on the pose of the same frame, after every driver and
every earlier effector. Refused by name: a target shape that is, or hangs from, a
bone or the tip of the effector's own chain; a later effector that writes the
target shape or a shape it hangs from; and a `plant` on a `shape` target. A later
effector that writes a shape an earlier effector's tip hangs from is warned about
(PUCK133, `CreationRig.Contests`): the later one solves last and holds its own
target.
Each frame an effector first resolves who its target is: the shape, the body's
`WorldEntityAddress` (slot and occupant generation), the cell holding a point, or
the field a probe reads. When that differs from the target it last acted on, or
there is none, it releases its plant latch and its step through one function
(`ReleaseLatch`), so a reused slot or a cleared cell never keeps the old latch. A
frame that resolves no target (a lost target, a probe that misses with no latch)
reports `target=none`, and the solve keeps running toward the last goal it drew,
held in the creation's own frame, while the weight eases out: nothing about a lost
target is read again.
The weight the solve and `align` use is three numbers multiplied. The eased level
eases toward the gate times the contact weight times `weightBy`'s curve height at
its driver's phase (`{ driver, curve }`, as a driver's), over `blendInSeconds` and
`blendOutSeconds` (default 0.15), snapping onto its level within a thousandth. The
authored `weight` is the second. The layer share is the third, read fresh every
frame and never eased (`CreationRig.EffectorShare`): for each shape the effector
writes, the owner's share there (the `weightBy` driver's weight times `1 - w` of
each later replacing driver covering the shape; with no owner, every replacing
driver counts), the smallest across its writes. A layer that takes any written
shape at full weight removes the effector in that frame and releases its latch, so
a foot plants afresh where the body stands when the layer leaves. A driver with no
`parts` covers what its effectors write; one whose `parts` leave out a shape its
effector writes is refused, naming the shape. `body.rig` prints each effector's
`applied` weight and its `error`, the distance from its tip to its target on the
final pose after every effector and follower.
`reach`, `standoff` and a replant's `distance` and `height` are creation
lengths: at a look or `bodies.scale` scale other than one they scale with the
body, as its shapes do, so a quarter-size Moth stands her boots a quarter-size
sole height off the floor (`WorldCreationInstances.Effectors`).
A `plant` is `{ driver, window, swingWeight }`, where the window is a
`[from, to]` pair in [0, 2π) that wraps when `from` exceeds `to`. This is what
keeps a foot still while the gait carries the body past it.
`swingWeight` is a nullable fraction in [0, 1] controlling the target's influence
outside the plant window while the driver is active: zero releases to the
authored swing, omission keeps following the target, and driver rest restores
contact influence. A false effector `when` gate clears the latch, so
reacquisition cannot reuse a pre-flight world target. `CreationEffectorLawTests`
holds the pack-path controls; Moth opts into zero swing influence.
`replant: { distance, seconds, height }` on a plant is the resting latch: while
the driver rests, the tip holds its world point and steps to the freshly
resolved target once it drifts past `distance`, over `seconds`, along an arc
`height` high. Effectors sharing a plant driver step one at a time; `body.rig`
prints `planted=stepping` mid-step. `CreationLocomotionLawTests` pins it.
`align` in [0, 1] (omitted = 0) keeps a planted tip's sole on the contact. The
solve moves only the tip's origin, and the tip inherits the turn the chain made,
so without it a boot planted off its rest offset tilts with its shin (toe in the
ground, heel lifted). With it the solved tip turns about its own origin, the
shortest way, until its rest axis against the probe `direction` (creation up for
a `body` or `state` target) lies along the surface normal at the target: the
probe's field gradient, latched with the plant and turned over a replant step,
world up when there is no surface. It scales by the eased weight the goal blends
by, so with `swingWeight: 0` the swing's own toe-off and heel lift are untouched
off the ground, while the tip's own swings are levelled with the rest of its tilt
on the ground. `standoff` stays measured to the tip's origin, since an aligned
tip's origin sits exactly its rest height above the sole. `body.rig` appends
`align=w normal=(x, y, z)` for an effector that authors it.
`CreationLocomotionLawTests` pins it.
## How the moth moves
Every part of the moth's motion is a driver, a swing or an effector in
`avatars/moth.puck`; nothing is special-cased in the client.
| Motion | Driver | Where |
|---|---|---|
| Pace, the X every gait curve reads | `pace` (`speed` through `gait-pace`) | none |
| Stride cycle, its length opening with pace | `stride` (`planarTravel`, `Grounded` + `moving`, `cadenceBy` `moth-stride`: 1.5 steps/s and 0.7 m strides at 0.5 m/s, 2 at 1.5 m/s, 3.75 and 2.7 m at 5 m/s) | the feet's plant windows; every gait driver rides its phase |
| Stride, arm swing, knee fold and ankle, hip and chest counter-yaw, head steady | `gait` (`driver.stride`, `weightBy` `moth-gait`: half at a walk, whole from 4.5 m/s) | thighs, shins, boots, upper arms, forearms; pelvis yaw and roll, torso, helmet |
| Forward lean, arms carried out, elbows bent | `run` (`driver.stride`, `weightBy` `moth-run`: none to 1.5 m/s, whole from 4.5 m/s) | pelvis, upper arms, forearms (`constant` waves) |
| Bob and chest dip, twice per stride | `bob` (`driver.stride`, cadence 2, `weightBy` `moth-run`) | pelvis slide, torso |
| Hips into a forward diagonal, chest and head back to the facing | `heading` (`travelDirection`, cadence 2, `sine`) | pelvis +0.7, torso −0.4, helmet −0.3 |
| Stride plane steered to the travel direction (sidestep, backpedal) | `heading`, `linear` ±0.5 between `sine` ±0.7 | each thigh, about the hip, around its stride swing |
| Hips trail a turn, chest and head lead | `trail` (`turnRate` through `body-turn`) | pelvis −0.12, torso +0.08, helmet +0.07 |
| Lean into a curving run, a start or a stop | `lean`, `surge` (accelerations through `body-lean`) | pelvis, pivoting about the ground point |
| Feet plant while walking, step when turning in place or settling, soles flat on the ground | `foot-left`/`foot-right` effectors, `stride` windows plus `replant`, `align: 1` with `standoff` the boot centre's rest height | thigh–shin chains, boot tips |
| Breath, flight pose, wings, and in flight alone the bank and cruise | `breath`, `flight`, `wings`, `bank`, `cruise` (the last two gated on `state.airPose.$body` too) | torso, limbs, pods |
| Jump: legs tucked and arms open in the air, tighter rising and reaching for the ground falling | `air` (`verticalSpeed` through `body-air`, `Airborne`, `linear` swings with a phase offset, so the peak pose is amplitude × phase) | thighs, shins, boots, upper arms, forearms |
| Landing give: a crouch that springs back past rest | `land` (`verticalSpeed` through the underdamped `body-land`, `Grounded`): still the fall's speed a beat after touchdown | pelvis pitch and drop, thighs, shins, boots, forearms |
### Judging motion
Judge a change to any driver, swing or effector above with `puck motion`, never
with one-off captures: it runs the walk, run, stops, turns, jumps and flight
(suited and out of the suit) on exact ticks through the `motion` layout's four
cameras riding body 0, and writes a contact sheet per scenario and camera with
every frame labelled by tick. Read `<scenario>/sheet.png` first, then the
camera's own sheet for the part you changed; `puck motion --reproduce` shows
that a repeat stills the same poses. Add a case by editing
`worlds/debug/motion.scenarios.json`
([the verb](../../../../docs/reference/cli.md#puck-motiontick-pinned-motion-stills-and-contact-sheets)).
The root shape is the pelvis, so a swing on it carries the whole body; the
upper body undoes part of it through the torso and helmet, and each thigh's
stride swing sits between yaw swings that turn the stride plane without
turning the leg at rest.
Chain refusals worth recognizing:
- `bone '<name>' does not descend from '<prev>' through parent, so the chain is not one limb.`
- `bone '<name>' carries domain operators — a fold rides its parent's frame and never its own solve, so it cannot be a bone.`
- `tip '<tip>' does not descend from the chain's last bone '<name>', so a solve could not move it.`
- `<n> bones is fewer than the 2 a chain needs; one bone has no joint to bend at, which a swing already says.`
## Frames
`frames` is a list of `{ name, transforms }` where each transform is
`{ id, position, rotation }` addressing a shape by id. A frame snapshots
**base** poses, replacing the parent's base pose rather than joining the delta
chain. There is no interpolation between frames; `rest` is the live pose. A
transform naming a missing shape id is refused, not dropped. A frame carries no
scale: its pose rides the shape's dynamic slot, which holds a position and an
orientation only, while scale is baked into the shape's geometry, so nothing in
the motion vocabulary scales a shape over time.
## The remaining sections
| Section | Shape | Caps and notes |
|---|---|---|
| `cameras` | `{ id, shapeId, position, yaw, pitch, fov, focus, feed }` | rides the anchored shape's live pose. `position` converts to the engine frame; `yaw` and `pitch` do not |
| `parts` | `{ id, shapeId, shapes, except }` | a named body part: `shapeId` is the anchor whose dynamic transform an anchor or a look's `partDynamics` reads; the part covers each shape `shapes` names and every shape that hangs from it through `parent` (omitted: the anchor's subtree), less the shapes of the earlier parts `except` names. Parts may overlap, and `CreationPartCompiler` is the one place a part becomes shapes; `creation stats` prints each part's shapes. An unknown shape or an `except` naming no earlier part is refused by name |
| `behavior` | `{ locomotion, faces, sounds }` | a face is `{ name, shapeId, defaultSource }` with a source of `none`, `test`, `camera:<name>`, or `feed:<name>`; a sound carries an inline `puck.synth.v1` patch with `level` capped at 8 |
| `textRuns` | `{ text, position, rotation, emHeight, depth, mode, material, font, maxWidth, align, tracking, lineSpacing, shapeId }` | local +X advances, +Y is ascent, +Z is the relief normal. `mode` is `emboss` (default) or `engrave`; engrave forces the creation-wide scope. Each non-whitespace glyph adds a field operand to bake. `position` is the first line's baseline; `\n` breaks a line. An embossed run bakes alone, refined toward `min(depth, 0.08 × emHeight / 3)`, a third of a regular weight's thinnest stroke (`SdfProgramBuilder.GlyphDetail`), on a lattice spaced to reach it (`SdfMeshPathBake.OwnFinal`), so each stroke spans three cells; an engraved run refines its own glyphs' box at that detail inside its creation's group (`SdfInstanceRange.Glyphs`); the view's tier floors that at a cell under half a display pixel, so lettering is kept wherever its strokes span a pixel |
| `noise` | `{ frequency, amplitude, octaves, gain, lacunarity, seed }` | frequency in (0, 8], amplitude in (0, 4] creation units, octaves 1 to 8. Forces the creation-wide scope. Root motion and `sizeBy` carry the baked relief; independently moving parts (frames, shape drivers, effectors or look part followers) refuse it. Static scale changes amplitude and wavelength together in render and contact. |
| `volumes` | see `surface.md` | up to 64 |
## What crosses the author frame
Converted on the way to the engine: shape `position`, `rotation`, and `joint`;
`symmetry` fold normals; swing `pivot` and `axis`; slide `axis`; frame transform
`position` and `rotation`; camera `position`; effector target `direction` and
`offset`; a clip key's turn axes and slide; a root-parented volume's `position` and `rotation`; and an unridden
text run's `position` and `rotation`.
Not converted: scalars, camera `yaw` and `pitch`, chain `goal` and `pole`, a
shape-ridden run or volume (its host shape carries it), and a `state` target's
cell, which is already a world point.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |