@origingame/engine 0.2.0 → 0.4.0

package/knowledge/wiki/anim.md

@@ -18,7 +18,7 @@ module anim {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 5636</sub>
+<sub>`api.ogt` line 7707</sub>
 
 ## Contents
 
@@ -64,6 +64,17 @@ module anim {
 | [`FlipbookInfo`](#type-FlipbookInfo) | struct | What og.load.flipbook registered. |
 | [`og.anim.clip`](#fn-clip) | function | The index of a flipbook clip by name, for Flipbook.clip: `og.anim.clip(hero, "walk_down")`. -1 when the sheet has no such clip. |
 | [`og.anim.clip`](#fn-clip) | function | A loaded model's clip by name, for AnimationPlayer.clip: `og.anim.clip(og.load.animation(world, "models/slime.glb").value, "chase")`, the same lookup as a flipbook's (Animation.clips by ClipInfo.name). A skinned glTF's clips are its animations' names; an animated `.vox`'s are `frames` or its `voxClip` names. 0 (plays nothing) when the model has no such clip. |
+| [`og.anim.clip`](#fn-clip) | function | The index of a 2D rig's clip by name, for Skeleton2D.clip: `og.anim.clip(og.load.rig2d(world, "rigs/hero.ogt").value, "walk")`. -1 when the rig has no such clip. |
+| [`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, 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. |
+| [`og.anim.rig2dInfo`](#fn-rig2dInfo) | function | What a loaded 2D rig holds: its bones, slots, IK constraints and clips, by the handle Skeleton2D.rig keeps (og.load.rig2d answers the same on load). |
+| [`Skeleton2DBox`](#type-Skeleton2DBox) | struct | A bounding box a 2D skeleton's pose shows: a `box` attachment of its rig (or of a child armature in one of its slots) while its slot shows it. |
+| [`og.anim.skeleton2dBoxes`](#fn-skeleton2dBoxes) | function | The bounding boxes an og.Skeleton2D's pose showed when og.skeleton2d last ran (after the game's systems, so a system reads the previous tick's): hurt and hit boxes a clip switches on and off with its slots' attachments, to test against points or other shapes. Empty for a rig without boxes or when no slot shows one. They are part of the og.skeleton2d state block, so a restored snapshot answers what it saved. |
 
 ## Functions
 
@@ -95,7 +106,7 @@ fn graph {
 }
 ```
 
-<sub>`api.ogt` line 5951</sub>
+<sub>`api.ogt` line 8022</sub>
 
 <a id="fn-humanoid"></a>
 
@@ -125,7 +136,7 @@ fn humanoid {
 }
 ```
 
-<sub>`api.ogt` line 5979</sub>
+<sub>`api.ogt` line 8050</sub>
 
 <a id="fn-retarget"></a>
 
@@ -155,7 +166,7 @@ fn retarget {
 }
 ```
 
-<sub>`api.ogt` line 5999</sub>
+<sub>`api.ogt` line 8070</sub>
 
 <a id="fn-clip"></a>
 
@@ -186,7 +197,7 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 6084</sub>
+<sub>`api.ogt` line 8155</sub>
 
 <a id="fn-clip-2"></a>
 
@@ -217,7 +228,98 @@ fn clip {
 }
 ```
 
-<sub>`api.ogt` line 6092</sub>
+<sub>`api.ogt` line 8163</sub>
+
+<a id="fn-clip-3"></a>
+
+### `og.anim.clip`
+
+The index of a 2D rig's clip by name, for Skeleton2D.clip: `og.anim.clip(og.load.rig2d(world, "rigs/hero.ogt").value, "walk")`. -1 when the rig has no such clip.
+
+```ts
+og.anim.clip(info: Rig2DInfo, name: string): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `info` | `Rig2DInfo` | no | What og.load.rig2d or og.anim.rig2dInfo answered. |
+| `name` | `string` | no | The clip's name. |
+
+**Returns** `number`.
+
+Implemented by the TypeScript runtime over the members of this module: no binding symbol.
+
+```ogt
+fn clip {
+  doc "The index of a 2D rig's clip by name, for Skeleton2D.clip: `og.anim.clip(og.load.rig2d(world, \"rigs/hero.ogt\").value, \"walk\")`. -1 when the rig has no such clip."
+  host false
+  param info Rig2DInfo "What og.load.rig2d or og.anim.rig2dInfo answered."
+  param name String "The clip's name."
+  returns i32
+}
+```
+
+<sub>`api.ogt` line 8171</sub>
+
+<a id="fn-rig2dInfo"></a>
+
+### `og.anim.rig2dInfo`
+
+What a loaded 2D rig holds: its bones, slots, IK constraints and clips, by the handle Skeleton2D.rig keeps (og.load.rig2d answers the same on load).
+
+```ts
+og.anim.rig2dInfo(world: World, rig: Rig2D): Result<Rig2DInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose animation owns the rig. |
+| `rig` | `Rig2D` | no | The rig. |
+
+**Returns** `Result<Rig2DInfo>`: Refused for a handle og.load.rig2d did not answer.
+
+Binding symbol `og_anim_rig2d_info` · publish builds: kept
+
+```ogt
+fn rig2dInfo {
+  doc "What a loaded 2D rig holds: its bones, slots, IK constraints and clips, by the handle Skeleton2D.rig keeps (og.load.rig2d answers the same on load)."
+  param world World "The world whose animation owns the rig."
+  param rig Rig2D "The rig."
+  returns Result.Rig2DInfo "Refused for a handle og.load.rig2d did not answer."
+}
+```
+
+<sub>`api.ogt` line 8281</sub>
+
+<a id="fn-skeleton2dBoxes"></a>
+
+### `og.anim.skeleton2dBoxes`
+
+The bounding boxes an og.Skeleton2D's pose showed when og.skeleton2d last ran (after the game's systems, so a system reads the previous tick's): hurt and hit boxes a clip switches on and off with its slots' attachments, to test against points or other shapes. Empty for a rig without boxes or when no slot shows one. They are part of the og.skeleton2d state block, so a restored snapshot answers what it saved.
+
+```ts
+og.anim.skeleton2dBoxes(world: World, entity: Entity): Result<readonly Skeleton2DBox[]>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose animation poses the skeleton. |
+| `entity` | `Entity` | no | The entity with the og.Skeleton2D. |
+
+**Returns** `Result<readonly Skeleton2DBox[]>`: Refused for an entity og.skeleton2d has not posed: no og.Skeleton2D with a loaded rig, or before its first tick.
+
+Binding symbol `og_anim_skeleton2d_boxes` · publish builds: kept
+
+```ogt
+fn skeleton2dBoxes {
+  doc "The bounding boxes an og.Skeleton2D's pose showed when og.skeleton2d last ran (after the game's systems, so a system reads the previous tick's): hurt and hit boxes a clip switches on and off with its slots' attachments, to test against points or other shapes. Empty for a rig without boxes or when no slot shows one. They are part of the og.skeleton2d state block, so a restored snapshot answers what it saved."
+  param world World "The world whose animation poses the skeleton."
+  param entity Entity "The entity with the og.Skeleton2D."
+  returns Result.List.Skeleton2DBox "Refused for an entity og.skeleton2d has not posed: no og.Skeleton2D with a loaded rig, or before its first tick."
+}
+```
+
+<sub>`api.ogt` line 8295</sub>
 
 ## Components, resources and events
 
@@ -254,7 +356,7 @@ component Skeleton {
 }
 ```
 
-<sub>`api.ogt` line 5720</sub>
+<sub>`api.ogt` line 7791</sub>
 
 <a id="record-AnimationPlayer"></a>
 
@@ -316,7 +418,7 @@ component AnimationPlayer {
 }
 ```
 
-<sub>`api.ogt` line 5735</sub>
+<sub>`api.ogt` line 7806</sub>
 
 <a id="record-AnimationGraph"></a>
 
@@ -392,7 +494,7 @@ component AnimationGraph {
 }
 ```
 
-<sub>`api.ogt` line 5774</sub>
+<sub>`api.ogt` line 7845</sub>
 
 <a id="record-Blendshapes"></a>
 
@@ -465,7 +567,7 @@ component Blendshapes {
 }
 ```
 
-<sub>`api.ogt` line 5822</sub>
+<sub>`api.ogt` line 7893</sub>
 
 <a id="record-IkChain"></a>
 
@@ -536,7 +638,7 @@ component IkChain {
 }
 ```
 
-<sub>`api.ogt` line 5870</sub>
+<sub>`api.ogt` line 7941</sub>
 
 <a id="record-AnimationEvent"></a>
 
@@ -567,7 +669,7 @@ event AnimationEvent {
 }
 ```
 
-<sub>`api.ogt` line 5914</sub>
+<sub>`api.ogt` line 7985</sub>
 
 <a id="record-Flipbook"></a>
 
@@ -623,7 +725,7 @@ component Flipbook {
 }
 ```
 
-<sub>`api.ogt` line 6022</sub>
+<sub>`api.ogt` line 8093</sub>
 
 <a id="record-FlipbookEvent"></a>
 
@@ -650,7 +752,145 @@ event FlipbookEvent {
 }
 ```
 
-<sub>`api.ogt` line 6053</sub>
+<sub>`api.ogt` line 8124</sub>
+
+<a id="record-Skeleton2D"></a>
+
+### `og.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.
+
+Changing `clip` restarts at 0 (or at `time`, written in the same tick); writing a different time is a seek and fires no events. The pose is a function of these fields, the Transform and the og.IkTarget2D on it; the playback position is world state (the og.skeleton2d state block).
+
+Token `og.Skeleton2D`, registered under the schema name `og.Skeleton2D`; its value type is `Skeleton2D`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `rig` | `Rig2D` | `0` | — | — | — | The rig (og.load.rig2d's `rig`); 0 is none. |
+| `clip` | `number` | `0` | ≥ 0 | — | — | The clip: an index into Rig2DInfo.clips (og.anim.clip finds one by name). |
+| `time` | `number` | `0` | ≥ 0 | `s` | — | Seconds into the clip; written every tick, set it to seek. |
+| `speed` | `number` | `1` | -10 … 10 | — | tunable | The playback rate: 1 as authored, 2 twice as fast, negative backwards. |
+| `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
+component Skeleton2D {
+  doc "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."
+  doc "Changing `clip` restarts at 0 (or at `time`, written in the same tick); writing a different time is a seek and fires no events. The pose is a function of these fields, the Transform and the og.IkTarget2D on it; the playback position is world state (the og.skeleton2d state block)."
+  field rig Rig2D "The rig (og.load.rig2d's `rig`); 0 is none."
+  field clip u32 "The clip: an index into Rig2DInfo.clips (og.anim.clip finds one by name)." {
+    min 0
+  }
+  field time f32 "Seconds into the clip; written every tick, set it to seek." {
+    min 0
+    unit s
+  }
+  field speed f32 "The playback rate: 1 as authored, 2 twice as fast, negative backwards." {
+    default 1
+    min -10
+    max 10
+    tunable true
+  }
+  field loop bool "Wrap at the clip's end; otherwise hold the last pose and set `finished`. Rig2DInfo.clips says what the rig's author meant." {
+    default true
+  }
+  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 8188</sub>
+
+<a id="record-Skeleton2DEvent"></a>
+
+### `og.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.
+
+Token `og.Skeleton2DEvent`, registered under the schema name `og.Skeleton2DEvent`; its value type is `Skeleton2DEvent`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `entity` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton2D. |
+| `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, 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 8218</sub>
+
+<a id="record-IkTarget2D"></a>
+
+### `og.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.
+
+Token `og.IkTarget2D`, registered under the schema name `og.IkTarget2D`; its value type is `IkTarget2D`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `skeleton` | `Entity` | `0` | — | — | — | The entity with the og.Skeleton2D. |
+| `constraint` | `number` | `0` | ≥ 0 | — | — | The constraint: an index into Rig2DInfo.constraints. |
+| `target` | `Vector2` | `{ x: 0, y: 0 }` | — | `m` | — | Where the chain's tip should be, in the frame the skeleton entity's og.Transform is written in (the world for an entity without a parent). |
+| `weight` | `number` | `1` | 0 … 1 | — | tunable | How much of the solve applies (0 is the animated pose, 1 fully solved), times the constraint's own weight (its `weight` line, or its clip's IK keys). |
+| `tolerance` | `number` | `0.01` | ≥ 0 | `m` | — | The distance at which the target counts as reached. |
+| `reached` | `boolean` | `false` | — | — | read only | Written: the tip is within `tolerance` of the target after solving. |
+| `error` | `number` | `0` | — | `m` | read only | Written: the tip's distance from the target after solving (for a one-bone constraint, how far the target lies off the bone's line). |
+
+```ogt
+component IkTarget2D {
+  doc "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."
+  field skeleton Entity "The entity with the og.Skeleton2D."
+  field constraint u32 "The constraint: an index into Rig2DInfo.constraints." {
+    min 0
+  }
+  field target Vector2 "Where the chain's tip should be, in the frame the skeleton entity's og.Transform is written in (the world for an entity without a parent)." {
+    unit m
+  }
+  field weight f32 "How much of the solve applies (0 is the animated pose, 1 fully solved), times the constraint's own weight (its `weight` line, or its clip's IK keys)." {
+    default 1
+    min 0
+    max 1
+    tunable true
+  }
+  field tolerance f32 "The distance at which the target counts as reached." {
+    default 0.01
+    min 0
+    unit m
+  }
+  field reached bool "Written: the tip is within `tolerance` of the target after solving." {
+    readonly true
+  }
+  field error f32 "Written: the tip's distance from the target after solving (for a one-bone constraint, how far the target lies off the bone's line)." {
+    unit m
+    readonly true
+  }
+}
+```
+
+<sub>`api.ogt` line 8229</sub>
 
 ## Types
 
@@ -666,7 +906,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 5642</sub>
+<sub>`api.ogt` line 7713</sub>
 
 <a id="type-ClipAsset"></a>
 
@@ -680,7 +920,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 5643</sub>
+<sub>`api.ogt` line 7714</sub>
 
 <a id="type-GraphAsset"></a>
 
@@ -694,7 +934,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 5644</sub>
+<sub>`api.ogt` line 7715</sub>
 
 <a id="type-RootMotion"></a>
 
@@ -719,7 +959,7 @@ enum RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 5667</sub>
+<sub>`api.ogt` line 7738</sub>
 
 <a id="type-BlendshapeSource"></a>
 
@@ -742,7 +982,7 @@ enum BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 5681</sub>
+<sub>`api.ogt` line 7752</sub>
 
 <a id="type-IkSolver"></a>
 
@@ -765,7 +1005,7 @@ enum IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 5694</sub>
+<sub>`api.ogt` line 7765</sub>
 
 <a id="type-IkSpace"></a>
 
@@ -788,7 +1028,7 @@ enum IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 5707</sub>
+<sub>`api.ogt` line 7778</sub>
 
 <a id="type-ClipInfo"></a>
 
@@ -815,7 +1055,7 @@ struct ClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 5925</sub>
+<sub>`api.ogt` line 7996</sub>
 
 <a id="type-Animation"></a>
 
@@ -842,7 +1082,7 @@ struct Animation {
 }
 ```
 
-<sub>`api.ogt` line 5935</sub>
+<sub>`api.ogt` line 8006</sub>
 
 <a id="type-GraphDesc"></a>
 
@@ -866,7 +1106,7 @@ struct GraphDesc {
 }
 ```
 
-<sub>`api.ogt` line 5944</sub>
+<sub>`api.ogt` line 8015</sub>
 
 <a id="type-Rig"></a>
 
@@ -880,7 +1120,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 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."
 ```
 
-<sub>`api.ogt` line 5958</sub>
+<sub>`api.ogt` line 8029</sub>
 
 <a id="type-HumanBone"></a>
 
@@ -901,7 +1141,7 @@ struct HumanBone {
 }
 ```
 
-<sub>`api.ogt` line 5960</sub>
+<sub>`api.ogt` line 8031</sub>
 
 <a id="type-Humanoid"></a>
 
@@ -922,7 +1162,7 @@ struct Humanoid {
 }
 ```
 
-<sub>`api.ogt` line 5966</sub>
+<sub>`api.ogt` line 8037</sub>
 
 <a id="type-HumanoidDesc"></a>
 
@@ -946,7 +1186,7 @@ struct HumanoidDesc {
 }
 ```
 
-<sub>`api.ogt` line 5972</sub>
+<sub>`api.ogt` line 8043</sub>
 
 <a id="type-RetargetDesc"></a>
 
@@ -980,7 +1220,7 @@ struct RetargetDesc {
 }
 ```
 
-<sub>`api.ogt` line 5986</sub>
+<sub>`api.ogt` line 8057</sub>
 
 <a id="type-FlipbookSheet"></a>
 
@@ -994,7 +1234,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 6006</sub>
+<sub>`api.ogt` line 8077</sub>
 
 <a id="type-FlipMode"></a>
 
@@ -1019,7 +1259,7 @@ enum FlipMode {
 }
 ```
 
-<sub>`api.ogt` line 6015</sub>
+<sub>`api.ogt` line 8086</sub>
 
 <a id="type-FlipbookClipInfo"></a>
 
@@ -1050,7 +1290,7 @@ struct FlipbookClipInfo {
 }
 ```
 
-<sub>`api.ogt` line 6061</sub>
+<sub>`api.ogt` line 8132</sub>
 
 <a id="type-FlipbookInfo"></a>
 
@@ -1081,7 +1321,106 @@ struct FlipbookInfo {
 }
 ```
 
-<sub>`api.ogt` line 6073</sub>
+<sub>`api.ogt` line 8144</sub>
+
+<a id="type-Rig2D"></a>
+
+### `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.
+
+A generational handle: a number the engine hands out. A dead handle is an error value, never a crash.
+
+```ogt
+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>
+
+<a id="type-Rig2DClipInfo"></a>
+
+### `Rig2DClipInfo` (struct)
+
+One clip of a loaded 2D rig.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `clip` | `number` | `0` | — | — | — | Its index, what Skeleton2D.clip takes. |
+| `name` | `string` | `""` | — | — | — | Its name in the rig. |
+| `duration` | `number` | `0` | — | `s` | — | Its length. |
+| `loop` | `boolean` | `false` | — | — | — | Whether the rig's author meant it to loop (its `loop` line): copy it into Skeleton2D.loop. |
+| `events` | `readonly string[]` | `[]` | — | — | — | Its events' names, in time order. |
+
+```ogt
+struct Rig2DClipInfo {
+  doc "One clip of a loaded 2D rig."
+  field clip u32 "Its index, what Skeleton2D.clip takes."
+  field name String "Its name in the rig."
+  field duration f32 "Its length." {
+    unit s
+  }
+  field loop bool "Whether the rig's author meant it to loop (its `loop` line): copy it into Skeleton2D.loop."
+  field events List.String "Its events' names, in time order."
+}
+```
+
+<sub>`api.ogt` line 8258</sub>
+
+<a id="type-Rig2DInfo"></a>
+
+### `Rig2DInfo` (struct)
+
+What og.load.rig2d registered, or og.anim.rig2dInfo reads back from a handle.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `rig` | `Rig2D` | `0` | — | — | — | What Skeleton2D.rig takes. |
+| `texture` | `Texture` | `0` | — | — | — | The rig's texture (loaded with it). |
+| `unit` | `number` | `0` | — | — | — | Pixels of the rig per world unit. |
+| `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
+struct Rig2DInfo {
+  doc "What og.load.rig2d registered, or og.anim.rig2dInfo reads back from a handle."
+  field rig Rig2D "What Skeleton2D.rig takes."
+  field texture Texture "The rig's texture (loaded with it)."
+  field unit f32 "Pixels of the rig per world unit."
+  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 8269</sub>
+
+<a id="type-Skeleton2DBox"></a>
+
+### `Skeleton2DBox` (struct)
+
+A bounding box a 2D skeleton's pose shows: a `box` attachment of its rig (or of a child armature in one of its slots) while its slot shows it.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `slot` | `string` | `""` | — | — | — | The slot showing it (`slot/child-slot` inside a child armature). |
+| `name` | `string` | `""` | — | — | — | The box's name in the rig. |
+| `points` | `readonly Vector2[]` | `[]` | — | — | — | Its polygon, moved by its bones (IK included), in the frame the skeleton entity's og.Transform is written in (the world for an entity without a parent). |
+
+```ogt
+struct Skeleton2DBox {
+  doc "A bounding box a 2D skeleton's pose shows: a `box` attachment of its rig (or of a child armature in one of its slots) while its slot shows it."
+  field slot String "The slot showing it (`slot/child-slot` inside a child armature)."
+  field name String "The box's name in the rig."
+  field points List.Vector2 "Its polygon, moved by its bones (IK included), in the frame the skeleton entity's og.Transform is written in (the world for an entity without a parent)."
+}
+```
+
+<sub>`api.ogt` line 8288</sub>
 
 ## Column kinds
 
@@ -1097,6 +1436,7 @@ Each is a factory, `SkeletonAsset(value?, options?)`, that makes one field of a
 | <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-FlipbookSheet"></a>`FlipbookSheet` | `FlipbookSheet` | `Uint32Array` | 2 | A FlipbookSheet handle field. |
+| <a id="column-Rig2D"></a>`Rig2D` | `Rig2D` | `Uint32Array` | 2 | A Rig2D handle field. |
 
 ```ogt
 column SkeletonAsset {
@@ -1107,7 +1447,7 @@ column SkeletonAsset {
 }
 ```
 
-<sub>`api.ogt` line 5646</sub>
+<sub>`api.ogt` line 7717</sub>
 
 ```ogt
 column ClipAsset {
@@ -1118,7 +1458,7 @@ column ClipAsset {
 }
 ```
 
-<sub>`api.ogt` line 5653</sub>
+<sub>`api.ogt` line 7724</sub>
 
 ```ogt
 column GraphAsset {
@@ -1129,7 +1469,7 @@ column GraphAsset {
 }
 ```
 
-<sub>`api.ogt` line 5660</sub>
+<sub>`api.ogt` line 7731</sub>
 
 ```ogt
 column RootMotion {
@@ -1140,7 +1480,7 @@ column RootMotion {
 }
 ```
 
-<sub>`api.ogt` line 5674</sub>
+<sub>`api.ogt` line 7745</sub>
 
 ```ogt
 column BlendshapeSource {
@@ -1151,7 +1491,7 @@ column BlendshapeSource {
 }
 ```
 
-<sub>`api.ogt` line 5687</sub>
+<sub>`api.ogt` line 7758</sub>
 
 ```ogt
 column IkSolver {
@@ -1162,7 +1502,7 @@ column IkSolver {
 }
 ```
 
-<sub>`api.ogt` line 5700</sub>
+<sub>`api.ogt` line 7771</sub>
 
 ```ogt
 column IkSpace {
@@ -1173,7 +1513,7 @@ column IkSpace {
 }
 ```
 
-<sub>`api.ogt` line 5713</sub>
+<sub>`api.ogt` line 7784</sub>
 
 ```ogt
 column FlipbookSheet {
@@ -1184,4 +1524,15 @@ column FlipbookSheet {
 }
 ```
 
-<sub>`api.ogt` line 6008</sub>
+<sub>`api.ogt` line 8079</sub>
+
+```ogt
+column Rig2D {
+  doc "A Rig2D handle field."
+  array Uint32Array
+  stride 2
+  value Rig2D
+}
+```
+
+<sub>`api.ogt` line 8181</sub>