@origingame/engine 0.3.0 → 0.5.0

package/knowledge/wiki/anim.md

@@ -18,7 +18,7 @@ module anim {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 7139</sub>
+<sub>`api.ogt` line 7761</sub>
 
 ## Contents
 
@@ -43,18 +43,30 @@ module anim {
 | [`og.AnimationGraph`](#record-AnimationGraph) | component | Runs a blend-tree graph (og.anim.graph) on a skeleton: its layers' state machines pick motions by the parameters p0...p7, which the graph names in `param` order (`param speed` is p0, the next `param` is p1, ...). |
 | [`og.Blendshapes`](#record-Blendshapes) | component | Morph-target weights of the skeleton entity's mesh, in the order of the glTF mesh's targets. With `source` clips the playing clips' weight channels write them; with `component` game code does. |
 | [`og.IkChain`](#record-IkChain) | component | An inverse-kinematics constraint on a skeleton, applied after its clips and graph: the chain of `bones` bones ending at joint `tip` turns so the tip reaches `target`. Put it on its own entity (a skeleton can have many chains); chains apply in query order. |
+| [`og.LookAt`](#record-LookAt) | component | An aim constraint on a skeleton, applied after its clips, graph and IK chains: `joint` turns so its `axis` points at `target` and its `upAxis` leans towards `up` (three.js Object3D.lookAt: +Z at the target, +Y up). The direction is held within maxYaw and maxPitch of the animated forward; with `bones` above 1 the joint's parents share the turn. Put it on its own entity (a head, the eyes, a turret's barrel); constraints apply in query order, and og.JointLimit clamps the joints it turns. |
+| [`og.JointLimit`](#record-JointLimit) | component | How far a joint may turn from its rest rotation when og.anim's solvers (og.IkChain, og.LookAt, og.FootLock) turn it: a swing of `axis` within a cone and a twist about it within a range. A hinge (a knee, an elbow) is `axis` along the hinge, `swing` 0 (or a little play) and the bend range as twistMin...twistMax. Put it on its own entity, one per joint; the animated pose itself is never clamped. |
+| [`og.FootLock`](#record-FootLock) | component | Foot locking: while the playing clips plant `foot` (within 5 mm of its lowest in each clip, the notion retargeting uses, weighed across blends and cross-fades: planted when the planting clips hold at least half the pose), the foot stays where it touched the ground, through clip blends and root motion, its leg bent by two-bone IK and the foot keeping its animated orientation; when the clips lift it, the foot rejoins its animation over `release`. Put it on its own entity, one per foot; locks apply after root motion and before og.IkChain, in query order, and og.JointLimit clamps the leg. The lock is world state (the `og.anim` state block). |
+| [`SpringSpace`](#type-SpringSpace) | enum | Where a spring bone's tails move. |
+| [`SpringSpace()`](#column-SpringSpace) | column kind | A SpringSpace field: the variant's index. |
+| [`og.SpringBone`](#record-SpringBone) | component | A spring (jiggle) bone chain, three-vrm's VRMSpringBone: `joint` and its `bones` - 1 parents swing after their parents' motion. Each joint's tail (the next joint of the chain; for the last joint its first child, or its parent bone continued at the same length) is a point pulled towards where the animated pose puts it by a damped spring (`frequency`, `damping`), under `gravity`, held at the bone's length, and the joint turns to point at it. Applied after og.IkChain and og.LookAt, top joint first; put it on its own entity (a tail, an ear, a strand of hair, a single jiggling node), one per chain. Deterministic under the fixed tick; the tails' positions and velocities are world state (the `og.anim` state block), so a restore continues a swing exactly. A changed chain (another skeleton, length or space) restarts at the animated pose. |
+| [`SpringColliderShape`](#type-SpringColliderShape) | enum | The shape of a spring collider. |
+| [`SpringColliderShape()`](#column-SpringColliderShape) | column kind | A SpringColliderShape field: the variant's index. |
+| [`og.SpringCollider`](#record-SpringCollider) | component | A collider spring bones are kept out of, three-vrm's VRMSpringBoneCollider: a sphere or a capsule riding on a joint of a skeleton (a head, a chest, an upper arm), so hair, ears and tails do not swing through the body. Each tick, after a tail of an og.SpringBone of the same skeleton has stepped and before its joint turns, the tail is pushed out of every collider whose `layers` meet the spring's `colliders` (in query order) to `radius` plus the spring's `radius`, keeping its bone's length. Put it on its own entity, one per shape; colliders follow the pose as it is when a chain is swung, so one on a joint an earlier chain swung follows that swing. |
 | [`og.AnimationEvent`](#record-AnimationEvent) | event | A named marker of a clip that playback passed in the last tick (read in the tick after it fired, like every event). Cross-fades and blends fire every contributing clip's markers. |
 | [`ClipInfo`](#type-ClipInfo) | struct | One clip of a loaded animation. |
 | [`Animation`](#type-Animation) | struct | What og.load.animation registered from a model's `#anim` blob. |
 | [`GraphDesc`](#type-GraphDesc) | desc struct | A blend-tree graph to register. |
 | [`og.anim.graph`](#fn-graph) | function | Register a blend-tree graph for AnimationGraph.asset. Its `clip` lines are resolved by name against `clips`. |
-| [`Rig`](#type-Rig) | handle | A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow and the standard bones it names outright. |
+| [`Rig`](#type-Rig) | handle | A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow, the standard bones it names outright and, with `footHeight`, how high its ankles stand above the ground. |
+| [`Rig()`](#column-Rig) | column kind | A Rig handle field (0 is none): a humanoid map og.load.rig answered. |
 | [`HumanBone`](#type-HumanBone) | struct | One standard humanoid bone of a skeleton. |
 | [`Humanoid`](#type-Humanoid) | struct | Which node of a skeleton is each standard humanoid bone (what retargeting maps). |
 | [`HumanoidDesc`](#type-HumanoidDesc) | desc struct | A skeleton and, optionally, the rig that says how its bones are named. |
 | [`og.anim.humanoid`](#fn-humanoid) | function | The standard humanoid bones of a skeleton, as retargeting sees them: to check a rig before retargeting onto it. |
 | [`RetargetDesc`](#type-RetargetDesc) | desc struct | A clip made for one skeleton, to play on another (other proportions, rest pose or bone names). |
-| [`og.anim.retarget`](#fn-retarget) | function | A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time. |
+| [`og.anim.retarget`](#fn-retarget) | function | A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree; fingers turn from their hand, so a hand pose holds whatever the arm does), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled, on the ground each rig's `footHeight` names (else its rest pose's foot heights). The target's twist bones (unmapped nodes named `twist`, or Rigify's `DEF-….001`, on an upper or lower arm or leg) take a share of their segment's twist by how far along it they sit. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time. |
+| [`MirrorDesc`](#type-MirrorDesc) | desc struct | A clip to play on the other side of the skeleton it was made for. |
+| [`og.anim.mirror`](#fn-mirror) | function | A new clip that plays `clip` on the other side: every frame reflected in the skeleton's x = 0 plane, each node taking its counterpart's motion (a left swing becomes the right's), rotations moved in model space so left and right bone frames need not mirror each other, root motion's sideways travel and turns flipped. Assumes a symmetric rest pose; a sided node without a counterpart keeps its rest pose. Same name, duration and markers (markers keep their names). Mirroring twice gives the clip back. A clip known ahead needs no call: a graph's `clip` line with `mirror true` plays it mirrored, and the cook's `animation { mirror "<clip>" }` writes the mirrored clip into the model. |
 | [`FlipbookSheet`](#type-FlipbookSheet) | handle | A sprite sheet's frames and clips (a cooked `.ogt` of `type flipbook`), from og.load.flipbook. |
 | [`FlipbookSheet()`](#column-FlipbookSheet) | column kind | A FlipbookSheet handle field. |
 | [`FlipMode`](#type-FlipMode) | enum | How a flipbook clip runs past its last frame. |
@@ -68,7 +80,7 @@ module anim {
 | [`Rig2D`](#type-Rig2D) | handle | A 2D rig (a cooked `.ogt` of `type rig2d`): bones, slots, region, mesh, bounding-box and child-armature attachments, IK constraints, child armatures and clips, from og.load.rig2d. |
 | [`Rig2D()`](#column-Rig2D) | column kind | A Rig2D handle field. |
 | [`og.Skeleton2D`](#record-Skeleton2D) | component | Plays a clip of a 2D rig at the entity: the og.skeleton2d system advances it by scaled time (Time.scaledDt) after the game's systems and fires its events as og.Skeleton2DEvent; extraction draws its slots, in their order, as textured triangles of the sprite batch at `layer` (region attachments as quads, mesh attachments weighted to bones and deformed by the clip), lit by og.Lighting2D when the layer is in its range, as a sprite there is. The rig's pixels are `unit` to a world unit and +y is up; the entity's og.Transform places, turns (about z) and scales it. |
-| [`og.Skeleton2DEvent`](#record-Skeleton2DEvent) | event | A 2D skeleton's clip passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass. |
+| [`og.Skeleton2DEvent`](#record-Skeleton2DEvent) | event | A 2D skeleton's clip, or the clip a child armature in one of its slots plays, passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass. |
 | [`og.IkTarget2D`](#record-IkTarget2D) | component | Moves one IK constraint of a 2D skeleton (Rig2DInfo.constraints) to a point: a foot planted on the ground under it, a hand on a ledge, a tail's tip. A constraint is a chain of any length: one bone points at the target, two are solved exactly (bending the way the rig says), three or more by FABRIK from the animated pose, curling the way the rig says. Put it on its own entity, one per constraint; og.skeleton2d writes `reached` and `error`, and the drawn pose solves the same way. |
 | [`Rig2DClipInfo`](#type-Rig2DClipInfo) | struct | One clip of a loaded 2D rig. |
 | [`Rig2DInfo`](#type-Rig2DInfo) | struct | What og.load.rig2d registered, or og.anim.rig2dInfo reads back from a handle. |
@@ -106,7 +118,7 @@ fn graph {
 }
 ```
 
-<sub>`api.ogt` line 7454</sub>
+<sub>`api.ogt` line 8300</sub>
 
 <a id="fn-humanoid"></a>
 
@@ -136,13 +148,13 @@ fn humanoid {
 }
 ```
 
-<sub>`api.ogt` line 7482</sub>
+<sub>`api.ogt` line 8335</sub>
 
 <a id="fn-retarget"></a>
 
 ### `og.anim.retarget`
 
-A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time.
+A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree; fingers turn from their hand, so a hand pose holds whatever the arm does), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled, on the ground each rig's `footHeight` names (else its rest pose's foot heights). The target's twist bones (unmapped nodes named `twist`, or Rigify's `DEF-….001`, on an upper or lower arm or leg) take a share of their segment's twist by how far along it they sit. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time.
 
 ```ts
 og.anim.retarget(world: World, desc?: RetargetDesc): Result<ClipInfo>
@@ -159,14 +171,44 @@ Binding symbol `og_anim_retarget` · publish builds: kept
 
 ```ogt
 fn retarget {
-  doc "A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time."
+  doc "A new clip for `target` from a clip of `source`: each animated humanoid bone turns as the source's does from its rest pose (after a rest correction, so a T-pose drives an A-pose and other bone frames agree; fingers turn from their hand, so a hand pose holds whatever the arm does), the target keeps its bone lengths, the hips travel the source's distance scaled by the leg ratio (root motion kept, hip height scaled), and with footIk the feet land where the source's do, scaled, on the ground each rig's `footHeight` names (else its rest pose's foot heights). The target's twist bones (unmapped nodes named `twist`, or Rigify's `DEF-….001`, on an upper or lower arm or leg) take a share of their segment's twist by how far along it they sit. Same name, duration and markers. The cook does the same for a model's `animation { library }` import setting; this is for clips chosen at run time."
   param world World "The world whose animation owns the skeletons and the clip."
   param desc RetargetDesc "The clip, the two skeletons and their rigs."
   returns Result.ClipInfo "The new clip (what AnimationPlayer.clip takes). Refused for an unregistered clip, skeleton or rig, a skeleton without recognisable hips (name them in a `type rig` file), or a rig naming a missing node."
 }
 ```
 
-<sub>`api.ogt` line 7502</sub>
+<sub>`api.ogt` line 8355</sub>
+
+<a id="fn-mirror"></a>
+
+### `og.anim.mirror`
+
+A new clip that plays `clip` on the other side: every frame reflected in the skeleton's x = 0 plane, each node taking its counterpart's motion (a left swing becomes the right's), rotations moved in model space so left and right bone frames need not mirror each other, root motion's sideways travel and turns flipped. Assumes a symmetric rest pose; a sided node without a counterpart keeps its rest pose. Same name, duration and markers (markers keep their names). Mirroring twice gives the clip back. A clip known ahead needs no call: a graph's `clip` line with `mirror true` plays it mirrored, and the cook's `animation { mirror "<clip>" }` writes the mirrored clip into the model.
+
+```ts
+og.anim.mirror(world: World, desc?: MirrorDesc): Result<ClipInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose animation owns the skeleton and the clip. |
+| `desc` | `MirrorDesc` | yes | The clip and its skeleton. |
+
+**Returns** `Result<ClipInfo>`: The new clip (what AnimationPlayer.clip takes). Refused for an unregistered clip or skeleton.
+
+Binding symbol `og_anim_mirror` · publish builds: kept
+
+```ogt
+fn mirror {
+  doc "A new clip that plays `clip` on the other side: every frame reflected in the skeleton's x = 0 plane, each node taking its counterpart's motion (a left swing becomes the right's), rotations moved in model space so left and right bone frames need not mirror each other, root motion's sideways travel and turns flipped. Assumes a symmetric rest pose; a sided node without a counterpart keeps its rest pose. Same name, duration and markers (markers keep their names). Mirroring twice gives the clip back. A clip known ahead needs no call: a graph's `clip` line with `mirror true` plays it mirrored, and the cook's `animation { mirror \"<clip>\" }` writes the mirrored clip into the model."
+  param world World "The world whose animation owns the skeleton and the clip."
+  param desc MirrorDesc "The clip and its skeleton."
+  returns Result.ClipInfo "The new clip (what AnimationPlayer.clip takes). Refused for an unregistered clip or skeleton."
+}
+```
+
+<sub>`api.ogt` line 8369</sub>
 
 <a id="fn-clip"></a>
 
@@ -197,7 +239,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 7587</sub>
+<sub>`api.ogt` line 8454</sub>
 
 <a id="fn-clip-2"></a>
 
@@ -228,7 +270,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 7595</sub>
+<sub>`api.ogt` line 8462</sub>
 
 <a id="fn-clip-3"></a>
 
@@ -259,7 +301,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 7603</sub>
+<sub>`api.ogt` line 8470</sub>
 
 <a id="fn-rig2dInfo"></a>
 
@@ -289,7 +331,7 @@ fn rig2dInfo {
 }
 ```
 
-<sub>`api.ogt` line 7708</sub>
+<sub>`api.ogt` line 8580</sub>
 
 <a id="fn-skeleton2dBoxes"></a>
 
@@ -319,7 +361,7 @@ fn skeleton2dBoxes {
 }
 ```
 
-<sub>`api.ogt` line 7722</sub>
+<sub>`api.ogt` line 8594</sub>
 
 ## Components, resources and events
 
@@ -356,7 +398,7 @@ component Skeleton {
 }
 ```
 
-<sub>`api.ogt` line 7223</sub>
+<sub>`api.ogt` line 7845</sub>
 
 <a id="record-AnimationPlayer"></a>
 
@@ -418,7 +460,7 @@ component AnimationPlayer {
 }
 ```
 
-<sub>`api.ogt` line 7238</sub>
+<sub>`api.ogt` line 7860</sub>
 
 <a id="record-AnimationGraph"></a>
 
@@ -494,7 +536,7 @@ component AnimationGraph {
 }
 ```
 
-<sub>`api.ogt` line 7277</sub>
+<sub>`api.ogt` line 7899</sub>
 
 <a id="record-Blendshapes"></a>
 
@@ -567,7 +609,7 @@ component Blendshapes {
 }
 ```
 
-<sub>`api.ogt` line 7325</sub>
+<sub>`api.ogt` line 7947</sub>
 
 <a id="record-IkChain"></a>
 
@@ -638,7 +680,325 @@ component IkChain {
 }
 ```
 
-<sub>`api.ogt` line 7373</sub>
+<sub>`api.ogt` line 7995</sub>
+
+<a id="record-LookAt"></a>
+
+### `og.LookAt` (component)
+
+An aim constraint on a skeleton, applied after its clips, graph and IK chains: `joint` turns so its `axis` points at `target` and its `upAxis` leans towards `up` (three.js Object3D.lookAt: +Z at the target, +Y up). The direction is held within maxYaw and maxPitch of the animated forward; with `bones` above 1 the joint's parents share the turn. Put it on its own entity (a head, the eyes, a turret's barrel); constraints apply in query order, and og.JointLimit clamps the joints it turns.
+
+Token `og.LookAt`, registered under the schema name `og.LookAt`; its value type is `LookAt`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton this constraint turns. |
+| `joint` | `number` | `0` | ≥ 0 | — | — | The joint that aims (an index into the skin's joints): the head, an eye. |
+| `bones` | `number` | `1` | 1 … 8 | — | — | How many joints share the turn: `joint` and its parents (3 spreads a look over neck, chest and spine), each parent taking an even share and `joint` the rest. |
+| `target` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | The point to look at, in `space`. |
+| `space` | `IkSpace` | `"world"` | — | — | — | What `target` and `up` are relative to: world (the frame the skeleton entity's og.Transform is in) or model. |
+| `axis` | `Vector3` | `{ x: 0, y: 0, z: 1 }` | — | — | — | The joint's forward, in its own frame: the axis turned onto the target. |
+| `upAxis` | `Vector3` | `{ x: 0, y: 1, z: 0 }` | — | — | — | The joint's up, in its own frame: yaw turns about it, pitch towards it, and it rolls towards `up`. |
+| `up` | `Vector3` | `{ x: 0, y: 1, z: 0 }` | — | — | — | The up hint, a direction in `space` the joint's `upAxis` leans to (three.js Object3D.up); the zero vector keeps the animated roll. |
+| `maxYaw` | `number` | `3.1416` | 0 … 3.1416 | `rad` | tunable | The largest turn about `upAxis`, left or right of the animated forward. |
+| `maxPitch` | `number` | `1.5708` | 0 … 1.5708 | `rad` | tunable | The largest turn towards or away from `upAxis`, from the animated forward. |
+| `weight` | `number` | `1` | 0 … 1 | — | tunable | How much of the turn is applied (0 = the animated pose, 1 = aimed). |
+| `clamped` | `boolean` | `false` | — | — | read only | Written: the target lay outside maxYaw or maxPitch, so the joint aims at the nearest direction inside them. |
+
+```ogt
+component LookAt {
+  doc "An aim constraint on a skeleton, applied after its clips, graph and IK chains: `joint` turns so its `axis` points at `target` and its `upAxis` leans towards `up` (three.js Object3D.lookAt: +Z at the target, +Y up). The direction is held within maxYaw and maxPitch of the animated forward; with `bones` above 1 the joint's parents share the turn. Put it on its own entity (a head, the eyes, a turret's barrel); constraints apply in query order, and og.JointLimit clamps the joints it turns."
+  field skeleton Entity "The entity with the og.Skeleton this constraint turns."
+  field joint u32 "The joint that aims (an index into the skin's joints): the head, an eye." {
+    min 0
+  }
+  field bones u32 "How many joints share the turn: `joint` and its parents (3 spreads a look over neck, chest and spine), each parent taking an even share and `joint` the rest." {
+    default 1
+    min 1
+    max 8
+  }
+  field target Vector3 "The point to look at, in `space`." {
+    unit m
+  }
+  field space IkSpace "What `target` and `up` are relative to: world (the frame the skeleton entity's og.Transform is in) or model."
+  field axis Vector3 "The joint's forward, in its own frame: the axis turned onto the target." {
+    default 0 0 1
+  }
+  field upAxis Vector3 "The joint's up, in its own frame: yaw turns about it, pitch towards it, and it rolls towards `up`." {
+    default 0 1 0
+  }
+  field up Vector3 "The up hint, a direction in `space` the joint's `upAxis` leans to (three.js Object3D.up); the zero vector keeps the animated roll." {
+    default 0 1 0
+  }
+  field maxYaw f32 "The largest turn about `upAxis`, left or right of the animated forward." {
+    default 3.1416
+    min 0
+    max 3.1416
+    unit rad
+    tunable true
+  }
+  field maxPitch f32 "The largest turn towards or away from `upAxis`, from the animated forward." {
+    default 1.5708
+    min 0
+    max 1.5708
+    unit rad
+    tunable true
+  }
+  field weight f32 "How much of the turn is applied (0 = the animated pose, 1 = aimed)." {
+    default 1
+    min 0
+    max 1
+    tunable true
+  }
+  field clamped bool "Written: the target lay outside maxYaw or maxPitch, so the joint aims at the nearest direction inside them." {
+    readonly true
+  }
+}
+```
+
+<sub>`api.ogt` line 8039</sub>
+
+<a id="record-JointLimit"></a>
+
+### `og.JointLimit` (component)
+
+How far a joint may turn from its rest rotation when og.anim's solvers (og.IkChain, og.LookAt, og.FootLock) turn it: a swing of `axis` within a cone and a twist about it within a range. A hinge (a knee, an elbow) is `axis` along the hinge, `swing` 0 (or a little play) and the bend range as twistMin...twistMax. Put it on its own entity, one per joint; the animated pose itself is never clamped.
+
+Token `og.JointLimit`, registered under the schema name `og.JointLimit`; its value type is `JointLimit`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton whose joint this limits. |
+| `joint` | `number` | `0` | ≥ 0 | — | — | The limited joint (an index into the skin's joints). |
+| `axis` | `Vector3` | `{ x: 0, y: 1, z: 0 }` | — | — | — | The twist axis in the joint's rest frame: along the bone for a ball joint, along the hinge for a hinge. |
+| `swing` | `number` | `3.1416` | 0 … 3.1416 | `rad` | tunable | The cone half-angle the axis may swing away from its rest direction (0 locks it: a hinge; pi is free). |
+| `twistMin` | `number` | `-3.1416` | -3.1416 … 3.1416 | `rad` | tunable | The least twist about `axis` from rest (a hinge's bend one way). |
+| `twistMax` | `number` | `3.1416` | -3.1416 … 3.1416 | `rad` | tunable | The most twist about `axis` from rest (a hinge's bend the other way). |
+
+```ogt
+component JointLimit {
+  doc "How far a joint may turn from its rest rotation when og.anim's solvers (og.IkChain, og.LookAt, og.FootLock) turn it: a swing of `axis` within a cone and a twist about it within a range. A hinge (a knee, an elbow) is `axis` along the hinge, `swing` 0 (or a little play) and the bend range as twistMin...twistMax. Put it on its own entity, one per joint; the animated pose itself is never clamped."
+  field skeleton Entity "The entity with the og.Skeleton whose joint this limits."
+  field joint u32 "The limited joint (an index into the skin's joints)." {
+    min 0
+  }
+  field axis Vector3 "The twist axis in the joint's rest frame: along the bone for a ball joint, along the hinge for a hinge." {
+    default 0 1 0
+  }
+  field swing f32 "The cone half-angle the axis may swing away from its rest direction (0 locks it: a hinge; pi is free)." {
+    default 3.1416
+    min 0
+    max 3.1416
+    unit rad
+    tunable true
+  }
+  field twistMin f32 "The least twist about `axis` from rest (a hinge's bend one way)." {
+    default -3.1416
+    min -3.1416
+    max 3.1416
+    unit rad
+    tunable true
+  }
+  field twistMax f32 "The most twist about `axis` from rest (a hinge's bend the other way)." {
+    default 3.1416
+    min -3.1416
+    max 3.1416
+    unit rad
+    tunable true
+  }
+}
+```
+
+<sub>`api.ogt` line 8088</sub>
+
+<a id="record-FootLock"></a>
+
+### `og.FootLock` (component)
+
+Foot locking: while the playing clips plant `foot` (within 5 mm of its lowest in each clip, the notion retargeting uses, weighed across blends and cross-fades: planted when the planting clips hold at least half the pose), the foot stays where it touched the ground, through clip blends and root motion, its leg bent by two-bone IK and the foot keeping its animated orientation; when the clips lift it, the foot rejoins its animation over `release`. Put it on its own entity, one per foot; locks apply after root motion and before og.IkChain, in query order, and og.JointLimit clamps the leg. The lock is world state (the `og.anim` state block).
+
+Token `og.FootLock`, registered under the schema name `og.FootLock`; its value type is `FootLock`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton whose foot this holds. |
+| `foot` | `number` | `0` | ≥ 0 | — | — | The foot joint (an index into the skin's joints); the two bones above it are the leg that bends. |
+| `weight` | `number` | `1` | 0 … 1 | — | tunable | How much of the lock is applied (0 = the animated foot, 1 = held). |
+| `release` | `number` | `0.15` | 0 … 2 | `s` | tunable | Seconds the foot takes to rejoin its animation once lifted (0: at once). |
+| `maxDistance` | `number` | `0.5` | ≥ 0 | `m` | tunable | Farther than this from where the animation puts the foot, the lock lets go (a leg cannot stretch). |
+| `planted` | `boolean` | `false` | — | — | read only | Written: the playing clips plant the foot this tick. |
+| `locked` | `boolean` | `false` | — | — | read only | Written: the foot is held at its lock this tick. |
+
+```ogt
+component FootLock {
+  doc "Foot locking: while the playing clips plant `foot` (within 5 mm of its lowest in each clip, the notion retargeting uses, weighed across blends and cross-fades: planted when the planting clips hold at least half the pose), the foot stays where it touched the ground, through clip blends and root motion, its leg bent by two-bone IK and the foot keeping its animated orientation; when the clips lift it, the foot rejoins its animation over `release`. Put it on its own entity, one per foot; locks apply after root motion and before og.IkChain, in query order, and og.JointLimit clamps the leg. The lock is world state (the `og.anim` state block)."
+  field skeleton Entity "The entity with the og.Skeleton whose foot this holds."
+  field foot u32 "The foot joint (an index into the skin's joints); the two bones above it are the leg that bends." {
+    min 0
+  }
+  field weight f32 "How much of the lock is applied (0 = the animated foot, 1 = held)." {
+    default 1
+    min 0
+    max 1
+    tunable true
+  }
+  field release f32 "Seconds the foot takes to rejoin its animation once lifted (0: at once)." {
+    default 0.15
+    min 0
+    max 2
+    unit s
+    tunable true
+  }
+  field maxDistance f32 "Farther than this from where the animation puts the foot, the lock lets go (a leg cannot stretch)." {
+    default 0.5
+    min 0
+    unit m
+    tunable true
+  }
+  field planted bool "Written: the playing clips plant the foot this tick." {
+    readonly true
+  }
+  field locked bool "Written: the foot is held at its lock this tick." {
+    readonly true
+  }
+}
+```
+
+<sub>`api.ogt` line 8120</sub>
+
+<a id="record-SpringBone"></a>
+
+### `og.SpringBone` (component)
+
+A spring (jiggle) bone chain, three-vrm's VRMSpringBone: `joint` and its `bones` - 1 parents swing after their parents' motion. Each joint's tail (the next joint of the chain; for the last joint its first child, or its parent bone continued at the same length) is a point pulled towards where the animated pose puts it by a damped spring (`frequency`, `damping`), under `gravity`, held at the bone's length, and the joint turns to point at it. Applied after og.IkChain and og.LookAt, top joint first; put it on its own entity (a tail, an ear, a strand of hair, a single jiggling node), one per chain. Deterministic under the fixed tick; the tails' positions and velocities are world state (the `og.anim` state block), so a restore continues a swing exactly. A changed chain (another skeleton, length or space) restarts at the animated pose.
+
+Token `og.SpringBone`, registered under the schema name `og.SpringBone`; its value type is `SpringBone`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton whose joints this swings. |
+| `joint` | `number` | `0` | ≥ 0 | — | — | The chain's last joint (an index into the skin's joints): the tip of a tail, an ear. |
+| `bones` | `number` | `1` | 1 … 16 | — | — | How many joints swing: `joint` and its parents (1 is the joint alone). |
+| `frequency` | `number` | `3` | 0 … 30 | `hz` | tunable | How fast a tail springs back to its animated place: the spring's natural frequency (0: no spring, it only hangs and swings). |
+| `damping` | `number` | `0.3` | 0 … 2 | — | tunable | The damping ratio: 0 swings on, 1 settles without overshooting (critical damping). |
+| `tipFrequency` | `number` | `1` | 0 … 4 | — | tunable | The last joint's frequency as a multiple of `frequency`, the joints between in proportion along the chain (1: every joint alike; 0.25: the tip springs back four times slower than the top, a soft strand on a stiff root). |
+| `tipDamping` | `number` | `1` | 0 … 4 | — | tunable | The last joint's damping ratio as a multiple of `damping`, the joints between in proportion along the chain (1: every joint alike). |
+| `gravity` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `mps2` | — | An acceleration on every tail, in `space` (three-vrm's gravityDir times gravityPower): (0, -9.8, 0) makes a chain droop. |
+| `space` | `SpringSpace` | `"world"` | — | — | — | Where the tails move: world (the frame the skeleton entity's og.Transform is in, so the chain lags behind the entity's motion) or model (only the animation moves it). |
+| `weight` | `number` | `1` | 0 … 1 | — | tunable | How much of the swing is applied (0 = the animated pose, 1 = the spring's). |
+| `radius` | `number` | `0` | ≥ 0 | `m` | tunable | The tails' radius against og.SpringCollider (three-vrm's hitRadius): a tail stays this far outside every collider it meets (0: a point). |
+| `colliders` | `number` | `4294967295` | — | — | — | The og.SpringCollider layers the tails are pushed out of, as bits: a collider on the same skeleton counts when its `layers` meet these. |
+| `lag` | `number` | `0` | — | `m` | read only | Written: the farthest a tail is from its animated place this tick. |
+
+```ogt
+component SpringBone {
+  doc "A spring (jiggle) bone chain, three-vrm's VRMSpringBone: `joint` and its `bones` - 1 parents swing after their parents' motion. Each joint's tail (the next joint of the chain; for the last joint its first child, or its parent bone continued at the same length) is a point pulled towards where the animated pose puts it by a damped spring (`frequency`, `damping`), under `gravity`, held at the bone's length, and the joint turns to point at it. Applied after og.IkChain and og.LookAt, top joint first; put it on its own entity (a tail, an ear, a strand of hair, a single jiggling node), one per chain. Deterministic under the fixed tick; the tails' positions and velocities are world state (the `og.anim` state block), so a restore continues a swing exactly. A changed chain (another skeleton, length or space) restarts at the animated pose."
+  field skeleton Entity "The entity with the og.Skeleton whose joints this swings."
+  field joint u32 "The chain's last joint (an index into the skin's joints): the tip of a tail, an ear." {
+    min 0
+  }
+  field bones u32 "How many joints swing: `joint` and its parents (1 is the joint alone)." {
+    default 1
+    min 1
+    max 16
+  }
+  field frequency f32 "How fast a tail springs back to its animated place: the spring's natural frequency (0: no spring, it only hangs and swings)." {
+    default 3
+    min 0
+    max 30
+    unit hz
+    tunable true
+  }
+  field damping f32 "The damping ratio: 0 swings on, 1 settles without overshooting (critical damping)." {
+    default 0.3
+    min 0
+    max 2
+    tunable true
+  }
+  field tipFrequency f32 "The last joint's frequency as a multiple of `frequency`, the joints between in proportion along the chain (1: every joint alike; 0.25: the tip springs back four times slower than the top, a soft strand on a stiff root)." {
+    default 1
+    min 0
+    max 4
+    tunable true
+  }
+  field tipDamping f32 "The last joint's damping ratio as a multiple of `damping`, the joints between in proportion along the chain (1: every joint alike)." {
+    default 1
+    min 0
+    max 4
+    tunable true
+  }
+  field gravity Vector3 "An acceleration on every tail, in `space` (three-vrm's gravityDir times gravityPower): (0, -9.8, 0) makes a chain droop." {
+    unit mps2
+  }
+  field space SpringSpace "Where the tails move: world (the frame the skeleton entity's og.Transform is in, so the chain lags behind the entity's motion) or model (only the animation moves it)."
+  field weight f32 "How much of the swing is applied (0 = the animated pose, 1 = the spring's)." {
+    default 1
+    min 0
+    max 1
+    tunable true
+  }
+  field radius f32 "The tails' radius against og.SpringCollider (three-vrm's hitRadius): a tail stays this far outside every collider it meets (0: a point)." {
+    min 0
+    unit m
+    tunable true
+  }
+  field colliders u32 "The og.SpringCollider layers the tails are pushed out of, as bits: a collider on the same skeleton counts when its `layers` meet these." {
+    default 4294967295
+  }
+  field lag f32 "Written: the farthest a tail is from its animated place this tick." {
+    readonly true
+    unit m
+  }
+}
+```
+
+<sub>`api.ogt` line 8166</sub>
+
+<a id="record-SpringCollider"></a>
+
+### `og.SpringCollider` (component)
+
+A collider spring bones are kept out of, three-vrm's VRMSpringBoneCollider: a sphere or a capsule riding on a joint of a skeleton (a head, a chest, an upper arm), so hair, ears and tails do not swing through the body. Each tick, after a tail of an og.SpringBone of the same skeleton has stepped and before its joint turns, the tail is pushed out of every collider whose `layers` meet the spring's `colliders` (in query order) to `radius` plus the spring's `radius`, keeping its bone's length. Put it on its own entity, one per shape; colliders follow the pose as it is when a chain is swung, so one on a joint an earlier chain swung follows that swing.
+
+Token `og.SpringCollider`, registered under the schema name `og.SpringCollider`; its value type is `SpringCollider`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton whose spring bones this keeps out. |
+| `joint` | `number` | `0` | ≥ 0 | — | — | The joint the collider rides on (an index into the skin's joints). |
+| `shape` | `SpringColliderShape` | `"sphere"` | — | — | — | A sphere about `offset`, or a capsule from `offset` to `tail`. |
+| `offset` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | The sphere's centre, or the capsule's first end, in the joint's frame. |
+| `tail` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | The capsule's other end, in the joint's frame (a sphere ignores it). |
+| `radius` | `number` | `0.1` | ≥ 0 | `m` | tunable | The radius, in metres of the skeleton's model space (the joint's own scale does not apply). |
+| `layers` | `number` | `1` | — | — | — | The layers this collider is on, as bits (a spring bone's `colliders` picks them). |
+
+```ogt
+component SpringCollider {
+  doc "A collider spring bones are kept out of, three-vrm's VRMSpringBoneCollider: a sphere or a capsule riding on a joint of a skeleton (a head, a chest, an upper arm), so hair, ears and tails do not swing through the body. Each tick, after a tail of an og.SpringBone of the same skeleton has stepped and before its joint turns, the tail is pushed out of every collider whose `layers` meet the spring's `colliders` (in query order) to `radius` plus the spring's `radius`, keeping its bone's length. Put it on its own entity, one per shape; colliders follow the pose as it is when a chain is swung, so one on a joint an earlier chain swung follows that swing."
+  field skeleton Entity "The entity with the og.Skeleton whose spring bones this keeps out."
+  field joint u32 "The joint the collider rides on (an index into the skin's joints)." {
+    min 0
+  }
+  field shape SpringColliderShape "A sphere about `offset`, or a capsule from `offset` to `tail`."
+  field offset Vector3 "The sphere's centre, or the capsule's first end, in the joint's frame." {
+    unit m
+  }
+  field tail Vector3 "The capsule's other end, in the joint's frame (a sphere ignores it)." {
+    unit m
+  }
+  field radius f32 "The radius, in metres of the skeleton's model space (the joint's own scale does not apply)." {
+    default 0.1
+    min 0
+    unit m
+    tunable true
+  }
+  field layers u32 "The layers this collider is on, as bits (a spring bone's `colliders` picks them)." {
+    default 1
+  }
+}
+```
+
+<sub>`api.ogt` line 8239</sub>
 
 <a id="record-AnimationEvent"></a>
 
@@ -669,7 +1029,7 @@ event AnimationEvent {
 }
 ```
 
-<sub>`api.ogt` line 7417</sub>
+<sub>`api.ogt` line 8263</sub>
 
 <a id="record-Flipbook"></a>
 
@@ -725,7 +1085,7 @@ component Flipbook {
 }
 ```
 
-<sub>`api.ogt` line 7525</sub>
+<sub>`api.ogt` line 8392</sub>
 
 <a id="record-FlipbookEvent"></a>
 
@@ -752,7 +1112,7 @@ event FlipbookEvent {
 }
 ```
 
-<sub>`api.ogt` line 7556</sub>
+<sub>`api.ogt` line 8423</sub>
 
 <a id="record-Skeleton2D"></a>
 
@@ -773,6 +1133,7 @@ Token `og.Skeleton2D`, registered under the schema name `og.Skeleton2D`; its val
 | `loop` | `boolean` | `true` | — | — | — | Wrap at the clip's end; otherwise hold the last pose and set `finished`. Rig2DInfo.clips says what the rig's author meant. |
 | `flipX` | `boolean` | `false` | — | — | — | Mirror the rig left to right about the entity's position (a character facing left). |
 | `layer` | `number` | `0` | — | — | — | The sprite layer it draws in, sorted with the sprites there (after them when they share the layer). |
+| `skin` | `number` | `0` | ≥ 0 | — | — | The skin it wears: an index into Rig2DInfo.skins (0 is the rig's default; `rig.skins.indexOf("armor")` finds one by name). A skin shows its own attachment wherever the setup pose or a clip shows the default's; a slot the skin leaves alone shows the default's. Change it any tick: the pose is drawn from it. |
 | `finished` | `boolean` | `false` | — | — | read only | Written: a clip that does not loop reached its end (or its start, played backwards). |
 
 ```ogt
@@ -798,19 +1159,22 @@ component Skeleton2D {
   }
   field flipX bool "Mirror the rig left to right about the entity's position (a character facing left)."
   field layer i32 "The sprite layer it draws in, sorted with the sprites there (after them when they share the layer)."
+  field skin u32 "The skin it wears: an index into Rig2DInfo.skins (0 is the rig's default; `rig.skins.indexOf(\"armor\")` finds one by name). A skin shows its own attachment wherever the setup pose or a clip shows the default's; a slot the skin leaves alone shows the default's. Change it any tick: the pose is drawn from it." {
+    min 0
+  }
   field finished bool "Written: a clip that does not loop reached its end (or its start, played backwards)." {
     readonly true
   }
 }
 ```
 
-<sub>`api.ogt` line 7620</sub>
+<sub>`api.ogt` line 8487</sub>
 
 <a id="record-Skeleton2DEvent"></a>
 
 ### `og.Skeleton2DEvent` (event)
 
-A 2D skeleton's clip passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
+A 2D skeleton's clip, or the clip a child armature in one of its slots plays, passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
 
 Token `og.Skeleton2DEvent`, registered under the schema name `og.Skeleton2DEvent`; its value type is `Skeleton2DEvent`.
 
@@ -820,20 +1184,22 @@ Token `og.Skeleton2DEvent`, registered under the schema name `og.Skeleton2DEvent
 | `clip` | `number` | `0` | — | — | — | The clip index. |
 | `name` | `string` | `""` | — | — | — | The event's name (at most 63 bytes). |
 | `time` | `number` | `0` | — | `s` | — | The event's time in the clip. |
+| `armature` | `string` | `""` | — | — | — | Empty for the skeleton's own clip; for an event of a child armature shown in one of its slots, that armature's name (`clip` and `time` are then the child's clip and its time): a flame's crackle apart from the keeper's footsteps (at most 63 bytes). |
 
 ```ogt
 event Skeleton2DEvent {
-  doc "A 2D skeleton's clip passed one of its events (`event 0.2 \"step\"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass."
+  doc "A 2D skeleton's clip, or the clip a child armature in one of its slots plays, passed one of its events (`event 0.2 \"step\"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass."
   field entity Entity "The entity with the og.Skeleton2D."
   field clip u32 "The clip index."
   field name String "The event's name (at most 63 bytes)."
   field time f32 "The event's time in the clip." {
     unit s
   }
+  field armature String "Empty for the skeleton's own clip; for an event of a child armature shown in one of its slots, that armature's name (`clip` and `time` are then the child's clip and its time): a flame's crackle apart from the keeper's footsteps (at most 63 bytes)."
 }
 ```
 
-<sub>`api.ogt` line 7647</sub>
+<sub>`api.ogt` line 8517</sub>
 
 <a id="record-IkTarget2D"></a>
 
@@ -884,7 +1250,7 @@ component IkTarget2D {
 }
 ```
 
-<sub>`api.ogt` line 7657</sub>
+<sub>`api.ogt` line 8528</sub>
 
 ## Types
 
@@ -900,7 +1266,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle SkeletonAsset "A rig: a glTF's nodes in topological order with their rest transforms, and its skins (joints and inverse bind matrices)."
 ```
 
-<sub>`api.ogt` line 7145</sub>
+<sub>`api.ogt` line 7767</sub>
 
 <a id="type-ClipAsset"></a>
 
@@ -914,7 +1280,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle ClipAsset "An animation clip, resampled at the cook's rate, with its markers."
 ```
 
-<sub>`api.ogt` line 7146</sub>
+<sub>`api.ogt` line 7768</sub>
 
 <a id="type-GraphAsset"></a>
 
@@ -928,7 +1294,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle GraphAsset "A blend-tree graph (`type animgraph`) whose clip references were resolved to clip handles."
 ```
 
-<sub>`api.ogt` line 7147</sub>
+<sub>`api.ogt` line 7769</sub>
 
 <a id="type-RootMotion"></a>
 
@@ -953,7 +1319,7 @@ enum RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 7170</sub>
+<sub>`api.ogt` line 7792</sub>
 
 <a id="type-BlendshapeSource"></a>
 
@@ -976,7 +1342,7 @@ enum BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 7184</sub>
+<sub>`api.ogt` line 7806</sub>
 
 <a id="type-IkSolver"></a>
 
@@ -999,7 +1365,7 @@ enum IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 7197</sub>
+<sub>`api.ogt` line 7819</sub>
 
 <a id="type-IkSpace"></a>
 
@@ -1022,7 +1388,53 @@ enum IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 7210</sub>
+<sub>`api.ogt` line 7832</sub>
+
+<a id="type-SpringSpace"></a>
+
+### `SpringSpace` (enum)
+
+Where a spring bone's tails move.
+
+A string: one of the variants below. The zero value is `"world"`.
+
+| Variant | Doc |
+|---|---|
+| `"world"` | The frame the skeleton entity's og.Transform is written in: the chain lags behind the entity's motion (walking, root motion, a jump). |
+| `"model"` | The skeleton's model space: only the animation moves the chain (a teleport or a vehicle carrying the entity does not). |
+
+```ogt
+enum SpringSpace {
+  doc "Where a spring bone's tails move."
+  variant world "The frame the skeleton entity's og.Transform is written in: the chain lags behind the entity's motion (walking, root motion, a jump)."
+  variant model "The skeleton's model space: only the animation moves the chain (a teleport or a vehicle carrying the entity does not)."
+}
+```
+
+<sub>`api.ogt` line 8153</sub>
+
+<a id="type-SpringColliderShape"></a>
+
+### `SpringColliderShape` (enum)
+
+The shape of a spring collider.
+
+A string: one of the variants below. The zero value is `"sphere"`.
+
+| Variant | Doc |
+|---|---|
+| `"sphere"` | A ball of `radius` about `offset`. |
+| `"capsule"` | A capsule of `radius` about the segment from `offset` to `tail`. |
+
+```ogt
+enum SpringColliderShape {
+  doc "The shape of a spring collider."
+  variant sphere "A ball of `radius` about `offset`."
+  variant capsule "A capsule of `radius` about the segment from `offset` to `tail`."
+}
+```
+
+<sub>`api.ogt` line 8226</sub>
 
 <a id="type-ClipInfo"></a>
 
@@ -1049,7 +1461,7 @@ struct ClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 7428</sub>
+<sub>`api.ogt` line 8274</sub>
 
 <a id="type-Animation"></a>
 
@@ -1076,7 +1488,7 @@ struct Animation {
 }
 ```
 
-<sub>`api.ogt` line 7438</sub>
+<sub>`api.ogt` line 8284</sub>
 
 <a id="type-GraphDesc"></a>
 
@@ -1100,21 +1512,21 @@ struct GraphDesc {
 }
 ```
 
-<sub>`api.ogt` line 7447</sub>
+<sub>`api.ogt` line 8293</sub>
 
 <a id="type-Rig"></a>
 
 ### `Rig` (handle)
 
-A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow and the standard bones it names outright.
+A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow, the standard bones it names outright and, with `footHeight`, how high its ankles stand above the ground.
 
 A generational handle: a number the engine hands out. A dead handle is an error value, never a crash.
 
 ```ogt
-handle Rig "A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow and the standard bones it names outright."
+handle Rig "A humanoid map from og.load.rig (a cooked `.ogt` of `type rig`): the naming scheme a skeleton's node names follow, the standard bones it names outright and, with `footHeight`, how high its ankles stand above the ground."
 ```
 
-<sub>`api.ogt` line 7461</sub>
+<sub>`api.ogt` line 8307</sub>
 
 <a id="type-HumanBone"></a>
 
@@ -1124,18 +1536,18 @@ One standard humanoid bone of a skeleton.
 
 | Field | Type | Default | Range | Unit | Notes | Doc |
 |---|---|---|---|---|---|---|
-| `bone` | `string` | `""` | — | — | — | The standard bone: hips, spine, chest, upperChest, neck, head, then leftShoulder, leftUpperArm, leftLowerArm, leftHand, the right arm, leftUpperLeg, leftLowerLeg, leftFoot, leftToes and the right leg. |
+| `bone` | `string` | `""` | — | — | — | The standard bone: hips, spine, chest, upperChest, neck, head, then leftShoulder, leftUpperArm, leftLowerArm, leftHand, the right arm, leftUpperLeg, leftLowerLeg, leftFoot, leftToes and the right leg, then each hand's fingers (VRM 1.0 names): leftThumbMetacarpal, leftThumbProximal, leftThumbDistal, leftIndexProximal, leftIndexIntermediate, leftIndexDistal, the same for Middle, Ring and Little, and the right hand's. |
 | `node` | `string` | `""` | — | — | — | The skeleton node that is that bone. |
 
 ```ogt
 struct HumanBone {
   doc "One standard humanoid bone of a skeleton."
-  field bone String "The standard bone: hips, spine, chest, upperChest, neck, head, then leftShoulder, leftUpperArm, leftLowerArm, leftHand, the right arm, leftUpperLeg, leftLowerLeg, leftFoot, leftToes and the right leg."
+  field bone String "The standard bone: hips, spine, chest, upperChest, neck, head, then leftShoulder, leftUpperArm, leftLowerArm, leftHand, the right arm, leftUpperLeg, leftLowerLeg, leftFoot, leftToes and the right leg, then each hand's fingers (VRM 1.0 names): leftThumbMetacarpal, leftThumbProximal, leftThumbDistal, leftIndexProximal, leftIndexIntermediate, leftIndexDistal, the same for Middle, Ring and Little, and the right hand's."
   field node String "The skeleton node that is that bone."
 }
 ```
 
-<sub>`api.ogt` line 7463</sub>
+<sub>`api.ogt` line 8316</sub>
 
 <a id="type-Humanoid"></a>
 
@@ -1156,7 +1568,7 @@ struct Humanoid {
 }
 ```
 
-<sub>`api.ogt` line 7469</sub>
+<sub>`api.ogt` line 8322</sub>
 
 <a id="type-HumanoidDesc"></a>
 
@@ -1180,7 +1592,7 @@ struct HumanoidDesc {
 }
 ```
 
-<sub>`api.ogt` line 7475</sub>
+<sub>`api.ogt` line 8328</sub>
 
 <a id="type-RetargetDesc"></a>
 
@@ -1214,7 +1626,31 @@ struct RetargetDesc {
 }
 ```
 
-<sub>`api.ogt` line 7489</sub>
+<sub>`api.ogt` line 8342</sub>
+
+<a id="type-MirrorDesc"></a>
+
+### `MirrorDesc` (desc struct)
+
+A clip to play on the other side of the skeleton it was made for.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `clip` | `ClipAsset` | `0` | — | — | — | The clip, made for `skeleton`. |
+| `skeleton` | `SkeletonAsset` | `0` | — | — | — | The skeleton the clip was made for (og.load.animation's `skeleton`); its left and right nodes are paired by name, the side tokens every rig naming scheme writes swapped (LeftArm and RightArm, thigh.L and thigh.R, J_Bip_L_ and J_Bip_R_, calf_l and calf_r). |
+
+```ogt
+struct MirrorDesc {
+  doc "A clip to play on the other side of the skeleton it was made for."
+  desc true
+  field clip ClipAsset "The clip, made for `skeleton`."
+  field skeleton SkeletonAsset "The skeleton the clip was made for (og.load.animation's `skeleton`); its left and right nodes are paired by name, the side tokens every rig naming scheme writes swapped (LeftArm and RightArm, thigh.L and thigh.R, J_Bip_L_ and J_Bip_R_, calf_l and calf_r)."
+}
+```
+
+<sub>`api.ogt` line 8362</sub>
 
 <a id="type-FlipbookSheet"></a>
 
@@ -1228,7 +1664,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle FlipbookSheet "A sprite sheet's frames and clips (a cooked `.ogt` of `type flipbook`), from og.load.flipbook."
 ```
 
-<sub>`api.ogt` line 7509</sub>
+<sub>`api.ogt` line 8376</sub>
 
 <a id="type-FlipMode"></a>
 
@@ -1253,7 +1689,7 @@ enum FlipMode {
 }
 ```
 
-<sub>`api.ogt` line 7518</sub>
+<sub>`api.ogt` line 8385</sub>
 
 <a id="type-FlipbookClipInfo"></a>
 
@@ -1284,7 +1720,7 @@ struct FlipbookClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 7564</sub>
+<sub>`api.ogt` line 8431</sub>
 
 <a id="type-FlipbookInfo"></a>
 
@@ -1315,7 +1751,7 @@ struct FlipbookInfo {
 }
 ```
 
-<sub>`api.ogt` line 7576</sub>
+<sub>`api.ogt` line 8443</sub>
 
 <a id="type-Rig2D"></a>
 
@@ -1329,7 +1765,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Rig2D "A 2D rig (a cooked `.ogt` of `type rig2d`): bones, slots, region, mesh, bounding-box and child-armature attachments, IK constraints, child armatures and clips, from og.load.rig2d."
 ```
 
-<sub>`api.ogt` line 7611</sub>
+<sub>`api.ogt` line 8478</sub>
 
 <a id="type-Rig2DClipInfo"></a>
 
@@ -1358,7 +1794,7 @@ struct Rig2DClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 7686</sub>
+<sub>`api.ogt` line 8557</sub>
 
 <a id="type-Rig2DInfo"></a>
 
@@ -1374,6 +1810,7 @@ What og.load.rig2d registered, or og.anim.rig2dInfo reads back from a handle.
 | `bones` | `readonly string[]` | `[]` | — | — | — | The bones' names, parents first. |
 | `slots` | `readonly string[]` | `[]` | — | — | — | The slots' names, in draw order. |
 | `constraints` | `readonly string[]` | `[]` | — | — | — | The IK constraints' names: an index here is IkTarget2D.constraint. |
+| `skins` | `readonly string[]` | `[]` | — | — | — | Its skins' names, `default` (the rig's own attachments) first: an index here is Skeleton2D.skin. |
 | `clips` | `readonly Rig2DClipInfo[]` | `[]` | — | — | — | Its clips, in file order. |
 
 ```ogt
@@ -1385,11 +1822,12 @@ struct Rig2DInfo {
   field bones List.String "The bones' names, parents first."
   field slots List.String "The slots' names, in draw order."
   field constraints List.String "The IK constraints' names: an index here is IkTarget2D.constraint."
+  field skins List.String "Its skins' names, `default` (the rig's own attachments) first: an index here is Skeleton2D.skin."
   field clips List.Rig2DClipInfo "Its clips, in file order."
 }
 ```
 
-<sub>`api.ogt` line 7697</sub>
+<sub>`api.ogt` line 8568</sub>
 
 <a id="type-Skeleton2DBox"></a>
 
@@ -1412,7 +1850,7 @@ struct Skeleton2DBox {
 }
 ```
 
-<sub>`api.ogt` line 7715</sub>
+<sub>`api.ogt` line 8587</sub>
 
 ## Column kinds
 
@@ -1427,6 +1865,9 @@ Each is a factory, `SkeletonAsset(value?, options?)`, that makes one field of a
 | <a id="column-BlendshapeSource"></a>`BlendshapeSource` | `BlendshapeSource` | `Uint32Array` | 1 | A BlendshapeSource field: the variant's index. |
 | <a id="column-IkSolver"></a>`IkSolver` | `IkSolver` | `Uint32Array` | 1 | An IkSolver field: the variant's index. |
 | <a id="column-IkSpace"></a>`IkSpace` | `IkSpace` | `Uint32Array` | 1 | An IkSpace field: the variant's index. |
+| <a id="column-SpringSpace"></a>`SpringSpace` | `SpringSpace` | `Uint32Array` | 1 | A SpringSpace field: the variant's index. |
+| <a id="column-SpringColliderShape"></a>`SpringColliderShape` | `SpringColliderShape` | `Uint32Array` | 1 | A SpringColliderShape field: the variant's index. |
+| <a id="column-Rig"></a>`Rig` | `Rig` | `Uint32Array` | 2 | A Rig handle field (0 is none): a humanoid map og.load.rig answered. |
 | <a id="column-FlipbookSheet"></a>`FlipbookSheet` | `FlipbookSheet` | `Uint32Array` | 2 | A FlipbookSheet handle field. |
 | <a id="column-Rig2D"></a>`Rig2D` | `Rig2D` | `Uint32Array` | 2 | A Rig2D handle field. |
 
@@ -1439,7 +1880,7 @@ column SkeletonAsset {
 }
 ```
 
-<sub>`api.ogt` line 7149</sub>
+<sub>`api.ogt` line 7771</sub>
 
 ```ogt
 column ClipAsset {
@@ -1450,7 +1891,7 @@ column ClipAsset {
 }
 ```
 
-<sub>`api.ogt` line 7156</sub>
+<sub>`api.ogt` line 7778</sub>
 
 ```ogt
 column GraphAsset {
@@ -1461,7 +1902,7 @@ column GraphAsset {
 }
 ```
 
-<sub>`api.ogt` line 7163</sub>
+<sub>`api.ogt` line 7785</sub>
 
 ```ogt
 column RootMotion {
@@ -1472,7 +1913,7 @@ column RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 7177</sub>
+<sub>`api.ogt` line 7799</sub>
 
 ```ogt
 column BlendshapeSource {
@@ -1483,7 +1924,7 @@ column BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 7190</sub>
+<sub>`api.ogt` line 7812</sub>
 
 ```ogt
 column IkSolver {
@@ -1494,7 +1935,7 @@ column IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 7203</sub>
+<sub>`api.ogt` line 7825</sub>
 
 ```ogt
 column IkSpace {
@@ -1505,7 +1946,40 @@ column IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 7216</sub>
+<sub>`api.ogt` line 7838</sub>
+
+```ogt
+column SpringSpace {
+  doc "A SpringSpace field: the variant's index."
+  array Uint32Array
+  stride 1
+  value SpringSpace
+}
+```
+
+<sub>`api.ogt` line 8159</sub>
+
+```ogt
+column SpringColliderShape {
+  doc "A SpringColliderShape field: the variant's index."
+  array Uint32Array
+  stride 1
+  value SpringColliderShape
+}
+```
+
+<sub>`api.ogt` line 8232</sub>
+
+```ogt
+column Rig {
+  doc "A Rig handle field (0 is none): a humanoid map og.load.rig answered."
+  array Uint32Array
+  stride 2
+  value Rig
+}
+```
+
+<sub>`api.ogt` line 8309</sub>
 
 ```ogt
 column FlipbookSheet {
@@ -1516,7 +1990,7 @@ column FlipbookSheet {
 }
 ```
 
-<sub>`api.ogt` line 7511</sub>
+<sub>`api.ogt` line 8378</sub>
 
 ```ogt
 column Rig2D {
@@ -1527,4 +2001,4 @@ column Rig2D {
 }
 ```
 
-<sub>`api.ogt` line 7613</sub>
+<sub>`api.ogt` line 8480</sub>