@origingame/engine 0.4.0 → 0.5.0

package/knowledge/wiki/anim.md

@@ -18,7 +18,7 @@ module anim {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 7707</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. |
@@ -106,7 +118,7 @@ fn graph {
 }
 ```
 
-<sub>`api.ogt` line 8022</sub>
+<sub>`api.ogt` line 8300</sub>
 
 <a id="fn-humanoid"></a>
 
@@ -136,13 +148,13 @@ fn humanoid {
 }
 ```
 
-<sub>`api.ogt` line 8050</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 8070</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 8155</sub>
+<sub>`api.ogt` line 8454</sub>
 
 <a id="fn-clip-2"></a>
 
@@ -228,7 +270,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 8163</sub>
+<sub>`api.ogt` line 8462</sub>
 
 <a id="fn-clip-3"></a>
 
@@ -259,7 +301,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 8171</sub>
+<sub>`api.ogt` line 8470</sub>
 
 <a id="fn-rig2dInfo"></a>
 
@@ -289,7 +331,7 @@ fn rig2dInfo {
 }
 ```
 
-<sub>`api.ogt` line 8281</sub>
+<sub>`api.ogt` line 8580</sub>
 
 <a id="fn-skeleton2dBoxes"></a>
 
@@ -319,7 +361,7 @@ fn skeleton2dBoxes {
 }
 ```
 
-<sub>`api.ogt` line 8295</sub>
+<sub>`api.ogt` line 8594</sub>
 
 ## Components, resources and events
 
@@ -356,7 +398,7 @@ component Skeleton {
 }
 ```
 
-<sub>`api.ogt` line 7791</sub>
+<sub>`api.ogt` line 7845</sub>
 
 <a id="record-AnimationPlayer"></a>
 
@@ -418,7 +460,7 @@ component AnimationPlayer {
 }
 ```
 
-<sub>`api.ogt` line 7806</sub>
+<sub>`api.ogt` line 7860</sub>
 
 <a id="record-AnimationGraph"></a>
 
@@ -494,7 +536,7 @@ component AnimationGraph {
 }
 ```
 
-<sub>`api.ogt` line 7845</sub>
+<sub>`api.ogt` line 7899</sub>
 
 <a id="record-Blendshapes"></a>
 
@@ -567,7 +609,7 @@ component Blendshapes {
 }
 ```
 
-<sub>`api.ogt` line 7893</sub>
+<sub>`api.ogt` line 7947</sub>
 
 <a id="record-IkChain"></a>
 
@@ -638,7 +680,325 @@ component IkChain {
 }
 ```
 
-<sub>`api.ogt` line 7941</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 7985</sub>
+<sub>`api.ogt` line 8263</sub>
 
 <a id="record-Flipbook"></a>
 
@@ -725,7 +1085,7 @@ component Flipbook {
 }
 ```
 
-<sub>`api.ogt` line 8093</sub>
+<sub>`api.ogt` line 8392</sub>
 
 <a id="record-FlipbookEvent"></a>
 
@@ -752,7 +1112,7 @@ event FlipbookEvent {
 }
 ```
 
-<sub>`api.ogt` line 8124</sub>
+<sub>`api.ogt` line 8423</sub>
 
 <a id="record-Skeleton2D"></a>
 
@@ -808,7 +1168,7 @@ component Skeleton2D {
 }
 ```
 
-<sub>`api.ogt` line 8188</sub>
+<sub>`api.ogt` line 8487</sub>
 
 <a id="record-Skeleton2DEvent"></a>
 
@@ -839,7 +1199,7 @@ event Skeleton2DEvent {
 }
 ```
 
-<sub>`api.ogt` line 8218</sub>
+<sub>`api.ogt` line 8517</sub>
 
 <a id="record-IkTarget2D"></a>
 
@@ -890,7 +1250,7 @@ component IkTarget2D {
 }
 ```
 
-<sub>`api.ogt` line 8229</sub>
+<sub>`api.ogt` line 8528</sub>
 
 ## Types
 
@@ -906,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 7713</sub>
+<sub>`api.ogt` line 7767</sub>
 
 <a id="type-ClipAsset"></a>
 
@@ -920,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 7714</sub>
+<sub>`api.ogt` line 7768</sub>
 
 <a id="type-GraphAsset"></a>
 
@@ -934,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 7715</sub>
+<sub>`api.ogt` line 7769</sub>
 
 <a id="type-RootMotion"></a>
 
@@ -959,7 +1319,7 @@ enum RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 7738</sub>
+<sub>`api.ogt` line 7792</sub>
 
 <a id="type-BlendshapeSource"></a>
 
@@ -982,7 +1342,7 @@ enum BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 7752</sub>
+<sub>`api.ogt` line 7806</sub>
 
 <a id="type-IkSolver"></a>
 
@@ -1005,7 +1365,7 @@ enum IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 7765</sub>
+<sub>`api.ogt` line 7819</sub>
 
 <a id="type-IkSpace"></a>
 
@@ -1028,7 +1388,53 @@ enum IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 7778</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>
 
@@ -1055,7 +1461,7 @@ struct ClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 7996</sub>
+<sub>`api.ogt` line 8274</sub>
 
 <a id="type-Animation"></a>
 
@@ -1082,7 +1488,7 @@ struct Animation {
 }
 ```
 
-<sub>`api.ogt` line 8006</sub>
+<sub>`api.ogt` line 8284</sub>
 
 <a id="type-GraphDesc"></a>
 
@@ -1106,21 +1512,21 @@ struct GraphDesc {
 }
 ```
 
-<sub>`api.ogt` line 8015</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 8029</sub>
+<sub>`api.ogt` line 8307</sub>
 
 <a id="type-HumanBone"></a>
 
@@ -1130,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 8031</sub>
+<sub>`api.ogt` line 8316</sub>
 
 <a id="type-Humanoid"></a>
 
@@ -1162,7 +1568,7 @@ struct Humanoid {
 }
 ```
 
-<sub>`api.ogt` line 8037</sub>
+<sub>`api.ogt` line 8322</sub>
 
 <a id="type-HumanoidDesc"></a>
 
@@ -1186,7 +1592,7 @@ struct HumanoidDesc {
 }
 ```
 
-<sub>`api.ogt` line 8043</sub>
+<sub>`api.ogt` line 8328</sub>
 
 <a id="type-RetargetDesc"></a>
 
@@ -1220,7 +1626,31 @@ struct RetargetDesc {
 }
 ```
 
-<sub>`api.ogt` line 8057</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>
 
@@ -1234,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 8077</sub>
+<sub>`api.ogt` line 8376</sub>
 
 <a id="type-FlipMode"></a>
 
@@ -1259,7 +1689,7 @@ enum FlipMode {
 }
 ```
 
-<sub>`api.ogt` line 8086</sub>
+<sub>`api.ogt` line 8385</sub>
 
 <a id="type-FlipbookClipInfo"></a>
 
@@ -1290,7 +1720,7 @@ struct FlipbookClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 8132</sub>
+<sub>`api.ogt` line 8431</sub>
 
 <a id="type-FlipbookInfo"></a>
 
@@ -1321,7 +1751,7 @@ struct FlipbookInfo {
 }
 ```
 
-<sub>`api.ogt` line 8144</sub>
+<sub>`api.ogt` line 8443</sub>
 
 <a id="type-Rig2D"></a>
 
@@ -1335,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 8179</sub>
+<sub>`api.ogt` line 8478</sub>
 
 <a id="type-Rig2DClipInfo"></a>
 
@@ -1364,7 +1794,7 @@ struct Rig2DClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 8258</sub>
+<sub>`api.ogt` line 8557</sub>
 
 <a id="type-Rig2DInfo"></a>
 
@@ -1397,7 +1827,7 @@ struct Rig2DInfo {
 }
 ```
 
-<sub>`api.ogt` line 8269</sub>
+<sub>`api.ogt` line 8568</sub>
 
 <a id="type-Skeleton2DBox"></a>
 
@@ -1420,7 +1850,7 @@ struct Skeleton2DBox {
 }
 ```
 
-<sub>`api.ogt` line 8288</sub>
+<sub>`api.ogt` line 8587</sub>
 
 ## Column kinds
 
@@ -1435,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. |
 
@@ -1447,7 +1880,7 @@ column SkeletonAsset {
 }
 ```
 
-<sub>`api.ogt` line 7717</sub>
+<sub>`api.ogt` line 7771</sub>
 
 ```ogt
 column ClipAsset {
@@ -1458,7 +1891,7 @@ column ClipAsset {
 }
 ```
 
-<sub>`api.ogt` line 7724</sub>
+<sub>`api.ogt` line 7778</sub>
 
 ```ogt
 column GraphAsset {
@@ -1469,7 +1902,7 @@ column GraphAsset {
 }
 ```
 
-<sub>`api.ogt` line 7731</sub>
+<sub>`api.ogt` line 7785</sub>
 
 ```ogt
 column RootMotion {
@@ -1480,7 +1913,7 @@ column RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 7745</sub>
+<sub>`api.ogt` line 7799</sub>
 
 ```ogt
 column BlendshapeSource {
@@ -1491,7 +1924,7 @@ column BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 7758</sub>
+<sub>`api.ogt` line 7812</sub>
 
 ```ogt
 column IkSolver {
@@ -1502,7 +1935,7 @@ column IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 7771</sub>
+<sub>`api.ogt` line 7825</sub>
 
 ```ogt
 column IkSpace {
@@ -1513,7 +1946,40 @@ column IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 7784</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 {
@@ -1524,7 +1990,7 @@ column FlipbookSheet {
 }
 ```
 
-<sub>`api.ogt` line 8079</sub>
+<sub>`api.ogt` line 8378</sub>
 
 ```ogt
 column Rig2D {
@@ -1535,4 +2001,4 @@ column Rig2D {
 }
 ```
 
-<sub>`api.ogt` line 8181</sub>
+<sub>`api.ogt` line 8480</sub>