@origingame/engine 0.4.0 → 0.5.0

package/schema/api.schema.json

@@ -17,6 +17,7 @@
     "bytes": "bytes",
     "kg": "kilograms",
     "newton": "newtons: the force that gives a kilogram one metre per second squared",
+    "newtonSecond": "newton-seconds: an impulse, the momentum that changes a kilogram's velocity by one metre per second",
     "mps": "metres per second",
     "mps2": "metres per second squared",
     "radps": "radians per second",
@@ -1614,7 +1615,7 @@
     },
     {
       "name": "reflect",
-      "doc": "Reflection: components and resources are declared once with their field layout and metadata, and registered by name.\nThe inspector, Tune, the probe, scene text and the wiki read this one schema. Each column factory below makes one field.\nA field holds one value, or a list of at most a fixed number of one number type or handle: `list(u32(), 8)`, `list(Asset(), 4)` (the list factory below). A list is read as a frozen copy (`push` throws) and written whole (`chain.passes = [...chain.passes, h]`); one over its capacity is refused, never truncated. A few vectors are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things with fields of their own is an entity each, with its own component, looped over by a query (a ring of skid marks, the laps of a race); a long record (a lap's taped inputs) is text in `str` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.\nA handle (an og.load answer, a texture, a sound, a geometry, a material, an entity) is a 64-bit number: keep it in a field of its own kind (`Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()`, `Entity()`, the factories of the API's handle types), in a component or a resource. A `u32` field refuses one (handles pass 2^32: `4294967298 is not a u32`); an `f64` holds the number but loses its type.",
+      "doc": "Reflection: components and resources are declared once with their field layout and metadata, and registered by name.\nThe inspector, Tune, the probe, scene text and the wiki read this one schema. Each column factory below makes one field.\nA field holds one value, or a list of at most a fixed number of one number type or handle: `list(u32(), 8)`, `list(Asset(), 4)` (the list factory below). A list is read as a frozen copy (`push` throws) and written whole (`chain.passes = [...chain.passes, h]`); one over its capacity is refused, never truncated. A few vectors are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things with fields of their own is an entity each, with its own component, looped over by a query (a ring of skid marks, the laps of a race); a long record (a lap's taped inputs) is text in `str` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.\nA handle (an og.load answer, a texture, a sound, a geometry, a material, an entity) is a 64-bit number: keep it in a field of its own kind (`Asset()`, `Texture()`, `Sound()`, `Font()`, `Style()`, `Geometry()`, `Material()`, `Entity()`: every handle type of the API has its factory, named as the type), never cast to another kind, in a component or a resource. A `u32` field refuses one (handles pass 2^32: `4294967298 is not a u32`); an `f64` holds the number but loses its type.",
       "place": "top",
       "publish": true,
       "types": [
@@ -2772,12 +2773,15 @@
         "DofQuality",
         "SpriteBlend",
         "SpriteBlend",
+        "SpriteFacing",
+        "SpriteFacing",
         "StripBlend",
         "StripBlend",
         "PostEffects",
         "Palette",
         "Look",
         "Palette",
+        "Look",
         "DitherPattern",
         "DitherPattern",
         "StyliseSpace",
@@ -2809,6 +2813,7 @@
         "ReflectionProbeMode",
         "ReflectionProbe",
         "Shader",
+        "Shader",
         "BufferGeometryDesc",
         "GeometryInfo",
         "CylinderGeometryDesc",
@@ -4375,6 +4380,8 @@
         "TextureArray",
         "Asset",
         "Sound",
+        "Font",
+        "Style",
         "LoadStatus",
         "GltfDesc",
         "GltfInfo",
@@ -5848,15 +5855,26 @@
         "AnimationGraph",
         "Blendshapes",
         "IkChain",
+        "LookAt",
+        "JointLimit",
+        "FootLock",
+        "SpringSpace",
+        "SpringSpace",
+        "SpringBone",
+        "SpringColliderShape",
+        "SpringColliderShape",
+        "SpringCollider",
         "AnimationEvent",
         "ClipInfo",
         "Animation",
         "GraphDesc",
         "Rig",
+        "Rig",
         "HumanBone",
         "Humanoid",
         "HumanoidDesc",
         "RetargetDesc",
+        "MirrorDesc",
         "FlipbookSheet",
         "FlipbookSheet",
         "FlipMode",
@@ -5919,7 +5937,7 @@
         },
         {
           "name": "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.",
           "params": [
             {
               "name": "world",
@@ -5938,6 +5956,27 @@
           "returnsDoc": "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.",
           "publish": true
         },
+        {
+          "name": "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.",
+          "params": [
+            {
+              "name": "world",
+              "type": "World",
+              "optional": false,
+              "doc": "The world whose animation owns the skeleton and the clip."
+            },
+            {
+              "name": "desc",
+              "type": "MirrorDesc",
+              "optional": true,
+              "doc": "The clip and its skeleton."
+            }
+          ],
+          "returns": "Result<ClipInfo>",
+          "returnsDoc": "The new clip (what AnimationPlayer.clip takes). Refused for an unregistered clip or skeleton.",
+          "publish": true
+        },
         {
           "name": "clip",
           "doc": "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.",
@@ -6385,12 +6424,16 @@
     },
     {
       "name": "audio",
-      "doc": "Sound: inside the tick, the engine's og.audio system (after the game's systems and physics) turns AudioSource changes into a deterministic, time-stamped command stream; outside the tick the host's mixer renders it (an AudioWorklet on the web, the output device, a capture or a null sink natively).\nThe stream, not the PCM, is world state: snapshots, restore and the world hash cover it, and nothing a sink does reaches the world. Load sounds with og.load.sound; inserting a source plays it, setting `playing` false stops it, and a one-shot sets `playing` back to false when it ends.\nSpatial gain and pan are computed in the tick from the source's world transform relative to the first AudioListener's (three.js convention: the listener looks down -Z, +X is right; with none, the origin looking down -Z). A source, listener or zone on a child entity is placed at its og.Transform composed down og.Parent, as og.MatrixWorld is: a sound on a child is heard where its parent carries it, a listener under a camera rig hears from the rig.",
+      "doc": "Sound: inside the tick, the engine's og.audio system (after the game's systems and physics) turns AudioSource changes into a deterministic, time-stamped command stream; outside the tick the host's mixer renders it (an AudioWorklet on the web, the output device, a capture or a null sink natively).\nThe stream, not the PCM, is world state: snapshots, restore and the world hash cover it, and nothing a sink does reaches the world. Load sounds with og.load.sound; inserting a source plays it, setting `playing` false stops it, and a one-shot sets `playing` back to false when it ends.\nSpatial gain and pan are computed in the tick from the source's world transform relative to the first AudioListener's (three.js convention: the listener looks down -Z, +X is right; with none, the origin looking down -Z). A source, listener or zone on a child entity is placed at its og.Transform composed down og.Parent, as og.MatrixWorld is: a sound on a child is heard where its parent carries it, a listener under a camera rig hears from the rig.\nPropagation, all in the tick and so in the stream: a spatial source or listener that moves shifts the pitch (Doppler, from their tick velocities: AudioSource.dopplerFactor, AudioListener.dopplerFactor, Audio.speedOfSound), a source with a cone is turned down away from its +Z (coneInnerAngle, coneOuterAngle, coneOuterGain, as three.js's setDirectionalCone), and a listener whose panningModel is hrtf places sources for headphones (interaural delay and head shadow) instead of the stereo panner.",
       "place": "namespace",
       "publish": true,
       "types": [
         "AudioBus",
         "AudioBus",
+        "PanningModel",
+        "AudioResampler",
+        "AudioResampler",
+        "PanningModel",
         "AudioSource",
         "AudioListener",
         "Audio",
@@ -6431,6 +6474,12 @@
           "type": "u32",
           "value": 4,
           "doc": "SoundEnded.reason: more sources played than Audio.maxVoices and this one stood lowest (priority, then volume, then age)."
+        },
+        {
+          "name": "SOUND_RETRIGGERED",
+          "type": "u32",
+          "value": 5,
+          "doc": "SoundEnded.reason: AudioSource.retrigger started the sound again from the top; a new voice plays it."
         }
       ],
       "functions": [
@@ -15596,6 +15645,22 @@
         "additive": "Added (light, fire, magic): order-independent within a layer."
       }
     },
+    "SpriteFacing": {
+      "x-og-kind": "enum",
+      "x-og-module": "render",
+      "description": "How a world sprite turns towards the camera that draws it: a billboard (three.js Sprite). Decided as a mode of og.Sprite and SpriteDesc rather than a component of its own: a billboard is the same quad, texture, region, flash, glow, blend, layer, drop shadow and texture array layer as any sprite, drawn by the same sprite batch and shader, which only stands its corners differently. The turn is computed on the GPU from each camera's own axes (the main camera, every og.CameraView and og.Mirror, every face of a reflection probe), so it never feeds back into the simulation and a snapshot holds only the mode. The sprite turns about its anchor (a nine-slice turns as one panel), `rotation` still turns it within its own plane, and its drop shadow is cast by the quad stood upright facing the sun, so it shows the whole shape from every camera. Within its layer a faced sprite without sortY draws back to front from the camera's eye (by view depth; a probe's six faces by distance from the probe), after the layer's drop shadows and before its unfaced sprites; and it is culled by its bounds (a sphere round the anchor through the farthest corner) against the camera's view. Sprites draw over the 3D scene after its transparent meshes and particles, depth tested and not depth writing, so a billboard behind a transparent mesh still draws over it.",
+      "type": "string",
+      "enum": [
+        "none",
+        "camera",
+        "cameraY"
+      ],
+      "x-og-variants": {
+        "none": "In the world's xy plane facing +z, as every sprite before billboards.",
+        "camera": "In the camera's view plane: its x along the camera's right, its y along its up, as particle billboards (smoke, glints, impostors seen from any side).",
+        "cameraY": "Upright, turned about the world's y axis towards the camera: its y stays +y, its x the camera's right laid level. Trees, characters and props that must stand while the camera looks down on them."
+      }
+    },
     "StripBlend": {
       "x-og-kind": "enum",
       "x-og-module": "render",
@@ -17225,7 +17290,7 @@
     "SpriteDesc": {
       "x-og-kind": "desc",
       "x-og-module": "render",
-      "description": "A textured or solid quad in the world's xy plane facing +z, drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene.",
+      "description": "A textured or solid quad in the world's xy plane facing +z (or turned to the camera, `facing`), drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene.",
       "type": "object",
       "properties": {
         "texture": {
@@ -17387,6 +17452,11 @@
           "description": "As three.js Material.toneMapped: true draws the sprite into the lit scene, carried by exposure (auto exposure included), bloom and the tone curve like any surface. false keeps its colours as given: still placed in the world, depth tested and sorted with the other sprites, but shown unexposed and uncurved (clamped to 0 to 1), outside bloom and fog; the grade, vignette, grain and screen flash still apply. For world UI that must read the same at noon and at dusk: speech bubbles, name tags, markers. Alpha blending only: an additive sprite adds light and is always tone mapped.",
           "default": true
         },
+        "facing": {
+          "$ref": "#/$defs/SpriteFacing",
+          "description": "A billboard: none keeps the quad in the world's xy plane; camera turns it into the view plane of each camera that draws it; cameraY stands it upright turned about y towards the camera (trees, characters). World sprites only (a screen sprite ignores it); see SpriteFacing for sorting, culling and its drop shadow.",
+          "default": "none"
+        },
         "flipX": {
           "type": "boolean",
           "description": "Mirror the region left to right.",
@@ -17453,7 +17523,7 @@
     "Sprite": {
       "x-og-kind": "component",
       "x-og-module": "render",
-      "description": "A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame.\nSorted with the immediate sprites and text by layer, then (sortY) by y, then texture: one draw per run of one texture. Tile layers draw before the sprites of their layer.",
+      "description": "A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z, in the xy plane or turned to the camera by `facing`; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame.\nSorted with the immediate sprites and text by layer, then (sortY) by y, then texture: one draw per run of one texture. Tile layers draw before the sprites of their layer.",
       "type": "object",
       "properties": {
         "texture": {
@@ -17542,6 +17612,11 @@
           "description": "Within its layer, lower y draws in front: top-down characters, props and trees overlap by their feet.",
           "default": false
         },
+        "facing": {
+          "$ref": "#/$defs/SpriteFacing",
+          "description": "A billboard (SpriteDesc.facing): none keeps the quad in the world's xy plane; camera turns it into each camera's view plane; cameraY stands it upright turned about y towards the camera, for trees and characters in a 3D set. Its afterimages face as it does; its blob shadow stays flat.",
+          "default": "none"
+        },
         "flipX": {
           "type": "boolean",
           "description": "Mirror left to right (a character facing left).",
@@ -20863,7 +20938,7 @@
     "CollisionStarted": {
       "x-og-kind": "event",
       "x-og-module": "physics",
-      "description": "Two solid colliders started touching during the tick.",
+      "description": "Two solid colliders started touching during the tick. Read in the tick after, when og.Velocity already holds the solver's answer (the bodies parting): how hard they met is `impulse` and `relativeVelocity`, taken in the step itself.",
       "type": "object",
       "properties": {
         "a": {
@@ -20876,18 +20951,32 @@
         },
         "point": {
           "$ref": "#/$defs/Vector3",
-          "description": "The deepest contact point in world space (z is 0 in 2D)."
+          "description": "The deepest contact point in world space (z is 0 in 2D).",
+          "x-og-unit": "m"
         },
         "normal": {
           "$ref": "#/$defs/Vector3",
           "description": "The contact normal, from a towards b."
+        },
+        "impulse": {
+          "type": "number",
+          "description": "The normal impulse the solver gave the pair in the step that made the contact (every substep, every contact point), in newton-seconds: b took `impulse` along `normal`, a the same against it. Its momentum answer to the hit, at least 0; heavier and faster hits give more.",
+          "minimum": 0,
+          "x-og-unit": "newtonSecond"
+        },
+        "relativeVelocity": {
+          "$ref": "#/$defs/Vector3",
+          "description": "a's velocity relative to b at `point` as that step began, before the solver answered: each body's linear velocity plus its angular velocity crossed with the point's offset from its centre of mass (a static collider is still; z is 0 in 2D). Along `normal` it is the closing speed, positive while they approach: max(0, relativeVelocity · normal) is how hard they hit, in m/s.",
+          "x-og-unit": "mps"
         }
       },
       "required": [
         "a",
         "b",
         "point",
-        "normal"
+        "normal",
+        "impulse",
+        "relativeVelocity"
       ],
       "additionalProperties": false
     },
@@ -24368,6 +24457,427 @@
       },
       "additionalProperties": false
     },
+    "LookAt": {
+      "x-og-kind": "component",
+      "x-og-module": "anim",
+      "description": "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.",
+      "type": "object",
+      "properties": {
+        "skeleton": {
+          "$ref": "#/$defs/Entity",
+          "description": "The entity with the og.Skeleton this constraint turns.",
+          "default": 0
+        },
+        "joint": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The joint that aims (an index into the skin's joints): the head, an eye.",
+          "default": 0,
+          "minimum": 0
+        },
+        "bones": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "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,
+          "minimum": 1,
+          "maximum": 8
+        },
+        "target": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The point to look at, in `space`.",
+          "default": {
+            "x": 0,
+            "y": 0,
+            "z": 0
+          },
+          "x-og-unit": "m"
+        },
+        "space": {
+          "$ref": "#/$defs/IkSpace",
+          "description": "What `target` and `up` are relative to: world (the frame the skeleton entity's og.Transform is in) or model.",
+          "default": "world"
+        },
+        "axis": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The joint's forward, in its own frame: the axis turned onto the target.",
+          "default": {
+            "x": 0,
+            "y": 0,
+            "z": 1
+          }
+        },
+        "upAxis": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The joint's up, in its own frame: yaw turns about it, pitch towards it, and it rolls towards `up`.",
+          "default": {
+            "x": 0,
+            "y": 1,
+            "z": 0
+          }
+        },
+        "up": {
+          "$ref": "#/$defs/Vector3",
+          "description": "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": {
+            "x": 0,
+            "y": 1,
+            "z": 0
+          }
+        },
+        "maxYaw": {
+          "type": "number",
+          "description": "The largest turn about `upAxis`, left or right of the animated forward.",
+          "default": 3.1416,
+          "minimum": 0,
+          "maximum": 3.1416,
+          "x-og-unit": "rad",
+          "x-og-tunable": true
+        },
+        "maxPitch": {
+          "type": "number",
+          "description": "The largest turn towards or away from `upAxis`, from the animated forward.",
+          "default": 1.5708,
+          "minimum": 0,
+          "maximum": 1.5708,
+          "x-og-unit": "rad",
+          "x-og-tunable": true
+        },
+        "weight": {
+          "type": "number",
+          "description": "How much of the turn is applied (0 = the animated pose, 1 = aimed).",
+          "default": 1,
+          "minimum": 0,
+          "maximum": 1,
+          "x-og-tunable": true
+        },
+        "clamped": {
+          "type": "boolean",
+          "description": "Written: the target lay outside maxYaw or maxPitch, so the joint aims at the nearest direction inside them.",
+          "default": false,
+          "readOnly": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "JointLimit": {
+      "x-og-kind": "component",
+      "x-og-module": "anim",
+      "description": "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.",
+      "type": "object",
+      "properties": {
+        "skeleton": {
+          "$ref": "#/$defs/Entity",
+          "description": "The entity with the og.Skeleton whose joint this limits.",
+          "default": 0
+        },
+        "joint": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The limited joint (an index into the skin's joints).",
+          "default": 0,
+          "minimum": 0
+        },
+        "axis": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The twist axis in the joint's rest frame: along the bone for a ball joint, along the hinge for a hinge.",
+          "default": {
+            "x": 0,
+            "y": 1,
+            "z": 0
+          }
+        },
+        "swing": {
+          "type": "number",
+          "description": "The cone half-angle the axis may swing away from its rest direction (0 locks it: a hinge; pi is free).",
+          "default": 3.1416,
+          "minimum": 0,
+          "maximum": 3.1416,
+          "x-og-unit": "rad",
+          "x-og-tunable": true
+        },
+        "twistMin": {
+          "type": "number",
+          "description": "The least twist about `axis` from rest (a hinge's bend one way).",
+          "default": -3.1416,
+          "minimum": -3.1416,
+          "maximum": 3.1416,
+          "x-og-unit": "rad",
+          "x-og-tunable": true
+        },
+        "twistMax": {
+          "type": "number",
+          "description": "The most twist about `axis` from rest (a hinge's bend the other way).",
+          "default": 3.1416,
+          "minimum": -3.1416,
+          "maximum": 3.1416,
+          "x-og-unit": "rad",
+          "x-og-tunable": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "FootLock": {
+      "x-og-kind": "component",
+      "x-og-module": "anim",
+      "description": "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).",
+      "type": "object",
+      "properties": {
+        "skeleton": {
+          "$ref": "#/$defs/Entity",
+          "description": "The entity with the og.Skeleton whose foot this holds.",
+          "default": 0
+        },
+        "foot": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The foot joint (an index into the skin's joints); the two bones above it are the leg that bends.",
+          "default": 0,
+          "minimum": 0
+        },
+        "weight": {
+          "type": "number",
+          "description": "How much of the lock is applied (0 = the animated foot, 1 = held).",
+          "default": 1,
+          "minimum": 0,
+          "maximum": 1,
+          "x-og-tunable": true
+        },
+        "release": {
+          "type": "number",
+          "description": "Seconds the foot takes to rejoin its animation once lifted (0: at once).",
+          "default": 0.15,
+          "minimum": 0,
+          "maximum": 2,
+          "x-og-unit": "s",
+          "x-og-tunable": true
+        },
+        "maxDistance": {
+          "type": "number",
+          "description": "Farther than this from where the animation puts the foot, the lock lets go (a leg cannot stretch).",
+          "default": 0.5,
+          "minimum": 0,
+          "x-og-unit": "m",
+          "x-og-tunable": true
+        },
+        "planted": {
+          "type": "boolean",
+          "description": "Written: the playing clips plant the foot this tick.",
+          "default": false,
+          "readOnly": true
+        },
+        "locked": {
+          "type": "boolean",
+          "description": "Written: the foot is held at its lock this tick.",
+          "default": false,
+          "readOnly": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "SpringSpace": {
+      "x-og-kind": "enum",
+      "x-og-module": "anim",
+      "description": "Where a spring bone's tails move.",
+      "type": "string",
+      "enum": [
+        "world",
+        "model"
+      ],
+      "x-og-variants": {
+        "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)."
+      }
+    },
+    "SpringBone": {
+      "x-og-kind": "component",
+      "x-og-module": "anim",
+      "description": "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.",
+      "type": "object",
+      "properties": {
+        "skeleton": {
+          "$ref": "#/$defs/Entity",
+          "description": "The entity with the og.Skeleton whose joints this swings.",
+          "default": 0
+        },
+        "joint": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The chain's last joint (an index into the skin's joints): the tip of a tail, an ear.",
+          "default": 0,
+          "minimum": 0
+        },
+        "bones": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "How many joints swing: `joint` and its parents (1 is the joint alone).",
+          "default": 1,
+          "minimum": 1,
+          "maximum": 16
+        },
+        "frequency": {
+          "type": "number",
+          "description": "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,
+          "minimum": 0,
+          "maximum": 30,
+          "x-og-unit": "hz",
+          "x-og-tunable": true
+        },
+        "damping": {
+          "type": "number",
+          "description": "The damping ratio: 0 swings on, 1 settles without overshooting (critical damping).",
+          "default": 0.3,
+          "minimum": 0,
+          "maximum": 2,
+          "x-og-tunable": true
+        },
+        "tipFrequency": {
+          "type": "number",
+          "description": "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,
+          "minimum": 0,
+          "maximum": 4,
+          "x-og-tunable": true
+        },
+        "tipDamping": {
+          "type": "number",
+          "description": "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,
+          "minimum": 0,
+          "maximum": 4,
+          "x-og-tunable": true
+        },
+        "gravity": {
+          "$ref": "#/$defs/Vector3",
+          "description": "An acceleration on every tail, in `space` (three-vrm's gravityDir times gravityPower): (0, -9.8, 0) makes a chain droop.",
+          "default": {
+            "x": 0,
+            "y": 0,
+            "z": 0
+          },
+          "x-og-unit": "mps2"
+        },
+        "space": {
+          "$ref": "#/$defs/SpringSpace",
+          "description": "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).",
+          "default": "world"
+        },
+        "weight": {
+          "type": "number",
+          "description": "How much of the swing is applied (0 = the animated pose, 1 = the spring's).",
+          "default": 1,
+          "minimum": 0,
+          "maximum": 1,
+          "x-og-tunable": true
+        },
+        "radius": {
+          "type": "number",
+          "description": "The tails' radius against og.SpringCollider (three-vrm's hitRadius): a tail stays this far outside every collider it meets (0: a point).",
+          "default": 0,
+          "minimum": 0,
+          "x-og-unit": "m",
+          "x-og-tunable": true
+        },
+        "colliders": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "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
+        },
+        "lag": {
+          "type": "number",
+          "description": "Written: the farthest a tail is from its animated place this tick.",
+          "default": 0,
+          "x-og-unit": "m",
+          "readOnly": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "SpringColliderShape": {
+      "x-og-kind": "enum",
+      "x-og-module": "anim",
+      "description": "The shape of a spring collider.",
+      "type": "string",
+      "enum": [
+        "sphere",
+        "capsule"
+      ],
+      "x-og-variants": {
+        "sphere": "A ball of `radius` about `offset`.",
+        "capsule": "A capsule of `radius` about the segment from `offset` to `tail`."
+      }
+    },
+    "SpringCollider": {
+      "x-og-kind": "component",
+      "x-og-module": "anim",
+      "description": "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.",
+      "type": "object",
+      "properties": {
+        "skeleton": {
+          "$ref": "#/$defs/Entity",
+          "description": "The entity with the og.Skeleton whose spring bones this keeps out.",
+          "default": 0
+        },
+        "joint": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The joint the collider rides on (an index into the skin's joints).",
+          "default": 0,
+          "minimum": 0
+        },
+        "shape": {
+          "$ref": "#/$defs/SpringColliderShape",
+          "description": "A sphere about `offset`, or a capsule from `offset` to `tail`.",
+          "default": "sphere"
+        },
+        "offset": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The sphere's centre, or the capsule's first end, in the joint's frame.",
+          "default": {
+            "x": 0,
+            "y": 0,
+            "z": 0
+          },
+          "x-og-unit": "m"
+        },
+        "tail": {
+          "$ref": "#/$defs/Vector3",
+          "description": "The capsule's other end, in the joint's frame (a sphere ignores it).",
+          "default": {
+            "x": 0,
+            "y": 0,
+            "z": 0
+          },
+          "x-og-unit": "m"
+        },
+        "radius": {
+          "type": "number",
+          "description": "The radius, in metres of the skeleton's model space (the joint's own scale does not apply).",
+          "default": 0.1,
+          "minimum": 0,
+          "x-og-unit": "m",
+          "x-og-tunable": true
+        },
+        "layers": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The layers this collider is on, as bits (a spring bone's `colliders` picks them).",
+          "default": 1
+        }
+      },
+      "additionalProperties": false
+    },
     "AnimationEvent": {
       "x-og-kind": "event",
       "x-og-module": "anim",
@@ -24514,7 +25024,7 @@
     "Rig": {
       "x-og-kind": "handle",
       "x-og-module": "anim",
-      "description": "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.",
+      "description": "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.",
       "type": "integer",
       "minimum": 0
     },
@@ -24526,7 +25036,7 @@
       "properties": {
         "bone": {
           "type": "string",
-          "description": "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."
+          "description": "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": {
           "type": "string",
@@ -24621,6 +25131,25 @@
       },
       "additionalProperties": false
     },
+    "MirrorDesc": {
+      "x-og-kind": "desc",
+      "x-og-module": "anim",
+      "description": "A clip to play on the other side of the skeleton it was made for.",
+      "type": "object",
+      "properties": {
+        "clip": {
+          "$ref": "#/$defs/ClipAsset",
+          "description": "The clip, made for `skeleton`.",
+          "default": 0
+        },
+        "skeleton": {
+          "$ref": "#/$defs/SkeletonAsset",
+          "description": "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).",
+          "default": 0
+        }
+      },
+      "additionalProperties": false
+    },
     "FlipbookSheet": {
       "x-og-kind": "handle",
       "x-og-module": "anim",
@@ -25791,6 +26320,34 @@
         "ui": "Interface sounds."
       }
     },
+    "PanningModel": {
+      "x-og-kind": "enum",
+      "x-og-module": "audio",
+      "description": "How an AudioListener places spatial sources between the ears, as Web Audio's PannerNode.panningModel.",
+      "type": "string",
+      "enum": [
+        "equalpower",
+        "hrtf"
+      ],
+      "x-og-variants": {
+        "equalpower": "The stereo panner (Web Audio's equal-power law): for speakers.",
+        "hrtf": "For headphones: a spherical-head model (Brown and Duda, 1998) that delays the far ear by the interaural time difference (up to 0.66 ms) and shadows its highs (up to -20 dB), so a source moves between the ears; front and back, up and down are not told apart (no pinna)."
+      }
+    },
+    "AudioResampler": {
+      "x-og-kind": "enum",
+      "x-og-module": "audio",
+      "description": "How the mixer resamples a voice whose pitch or sound rate differs from the output's.",
+      "type": "string",
+      "enum": [
+        "linear",
+        "sinc"
+      ],
+      "x-og-variants": {
+        "linear": "Linear interpolation: the engine's mix before round 4, cheaper, with duller highs (-3.4 dB at 15 kHz from 44.1 kHz) and images (-11.5 dB there).",
+        "sinc": "A Kaiser-windowed sinc (beta 7, 16 taps, 2048 phases; widened up to 64 taps for a voice pitched up to 4x): flat to the highs, images below -70 dB."
+      }
+    },
     "AudioSource": {
       "x-og-kind": "component",
       "x-og-module": "audio",
@@ -25937,6 +26494,50 @@
           "maximum": 30,
           "x-og-unit": "s",
           "x-og-tunable": true
+        },
+        "dopplerFactor": {
+          "type": "number",
+          "description": "Doppler: how much a spatial source's and the listener's motion along the line between them shifts its pitch, from their tick velocities (world positions down og.Parent): pitch times (c - DF * vListener) / (c - DF * vSource), c being Audio.speedOfSound and DF this times AudioListener.dopplerFactor (OpenAL's model). 1 is physical, 0 is off. A jump at or past the speed of sound in a tick is a teleport and shifts nothing; DF * v is held within c/2, so the shift stays within a factor of 3.",
+          "default": 1,
+          "minimum": 0,
+          "maximum": 10,
+          "x-og-tunable": true
+        },
+        "coneInnerAngle": {
+          "type": "number",
+          "description": "Directivity, as three.js PositionalAudio.setDirectionalCone and Web Audio's PannerNode: a spatial source plays at full volume while the listener is within this full angle about the source's +Z (its world transform's, three.js's PositionalAudio orientation); 360 with coneOuterAngle 360 is omnidirectional.",
+          "default": 360,
+          "minimum": 0,
+          "maximum": 360,
+          "x-og-unit": "deg",
+          "x-og-tunable": true
+        },
+        "coneOuterAngle": {
+          "type": "number",
+          "description": "Past this full angle about the source's +Z it plays at coneOuterGain; between coneInnerAngle and this the gain falls linearly with the angle.",
+          "default": 360,
+          "minimum": 0,
+          "maximum": 360,
+          "x-og-unit": "deg",
+          "x-og-tunable": true
+        },
+        "coneOuterGain": {
+          "type": "number",
+          "description": "The gain outside coneOuterAngle.",
+          "default": 0,
+          "minimum": 0,
+          "maximum": 1,
+          "x-og-tunable": true
+        },
+        "virtualize": {
+          "type": "boolean",
+          "description": "Past Audio.maxVoices it goes virtual instead of being culled: silent, its playhead running on (a one-shot still ends on its tick), and heard again from where it would be, fading in, once it stands within the cap. Without it the source is culled (SOUND_CULLED, playing false).",
+          "default": false
+        },
+        "retrigger": {
+          "type": "boolean",
+          "description": "Set true to start the sound again from the top (its startOffset, its startAt) this tick, playing or not, without a level change on `playing`: the voice playing ends (SOUND_RETRIGGERED) and a new one starts in the same tick. The engine sets it back to false and `playing` true.",
+          "default": false
         }
       },
       "additionalProperties": false
@@ -25954,6 +26555,19 @@
           "minimum": 0,
           "maximum": 4,
           "x-og-tunable": true
+        },
+        "dopplerFactor": {
+          "type": "number",
+          "description": "Scales every spatial source's Doppler shift (AudioSource.dopplerFactor); 0 turns Doppler off for this listener.",
+          "default": 1,
+          "minimum": 0,
+          "maximum": 10,
+          "x-og-tunable": true
+        },
+        "panningModel": {
+          "$ref": "#/$defs/PanningModel",
+          "description": "How spatial sources are placed between the ears: equalpower (speakers) or hrtf (headphones). Non-spatial sources keep their pan either way; the stereo path is unchanged while it is equalpower.",
+          "default": "equalpower"
         }
       },
       "additionalProperties": false
@@ -26045,6 +26659,20 @@
           "minimum": 0,
           "x-og-unit": "s",
           "readOnly": true
+        },
+        "speedOfSound": {
+          "type": "number",
+          "description": "The speed of sound Doppler shifts are computed against (AudioSource.dopplerFactor).",
+          "default": 343.3,
+          "minimum": 1,
+          "maximum": 10000,
+          "x-og-unit": "mps",
+          "x-og-tunable": true
+        },
+        "resampler": {
+          "$ref": "#/$defs/AudioResampler",
+          "description": "How voices are resampled: sinc (the default) or linear, the mix before round 4, for a game that relies on its exact output. A sound at the output's rate played at pitch 1 is its own samples either way.",
+          "default": "sinc"
         }
       },
       "additionalProperties": false
@@ -26402,7 +27030,7 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 4294967295,
-          "description": "Why: SOUND_FINISHED (0), SOUND_STOPPED (1), SOUND_REMOVED (2), SOUND_REPLACED (3) or SOUND_CULLED (4)."
+          "description": "Why: SOUND_FINISHED (0), SOUND_STOPPED (1), SOUND_REMOVED (2), SOUND_REPLACED (3), SOUND_CULLED (4) or SOUND_RETRIGGERED (5)."
         }
       },
       "required": [