@woosh/meep-engine 3.40.0 → 3.42.0

package/src/engine/ecs/ik/PLAN.md

@@ -0,0 +1,179 @@
+# IK — trees, goals on bones, joints and contacts from physics
+
+> Revision 5, 2026-10-06. **S1–S4 are implemented** (2026-10-06); S5 is later. What implementing
+> it measured or decided beyond this text is in §9. The solver (§2) was accepted at revision 2. Revisions 3–5 settle the components, limits, contacts and clip-driven bones. Each
+> revision went through an adversarial review. Numbers come from one-off probes outside the repo,
+> and every stage re-pins what it relies on with a failing spec first.
+
+## 1. Where it stands (master `c01c0ebbd`)
+
+- `physics/inverse_kinematics/fabrik/` solves one chain, and nothing calls it.
+- The ECS IK (`2BIK`, `1BSA`) reads name-keyed `IKConstraint` lists on an `InverseKinematics`
+  component, and probes `Terrain` directly.
+- **Holds** (`gpu_authority_hold`): a CPU writer takes a joint's `TransformAttachment`. The
+  animation manager mutes every clip binding that names the joint, and `t64_evaluate_world` /
+  `T64WorldCache` read the held offset. Cloth uses this.
+- `two_joint_ik` takes the knee's hinge. The CPU pose twin matches the GPU resolve.
+
+## 2. Solver: frame FABRIK over a tree
+
+**Unchanged.**
+- Every solved joint is a frame: rigid offsets to its children, with its rotation fitted inward
+  (from its old position) and outward. With one child this is the paper's pull.
+- Fits start from the carried rotation, so nothing drifts.
+- A goal's path runs from its effector to its `chain_root`. A link carries the weight of the goals
+  whose path holds both ends, and a `chain_root` takes rotation, never position.
+- The target is `lerp(carried, goal, w)`. Weight 0 gives the same pose as no goal, and the result is
+  continuous in `w`.
+- Two-bone paths use `two_joint_ik`. Twist is held from the animated pose, and the effector's
+  rotation is slerped toward the goal after the solve.
+- Worst error at 16 iterations is 0.005–1.34 mm across the probe cases. The paper's point branches
+  miss by 8–49 mm once written back.
+
+## 3. Components: on the bones, limits from physics
+
+Data lives on the entity it describes, and the tree is the `TransformAttachment` hierarchy. Meep's
+own rig setup puts these components on the bones when the instance is created.
+
+**`IKGoal`, on the effector bone.**
+
+| field | meaning |
+|---|---|
+| `target` | entity id. Its world pose is the goal. |
+| `chain_root` | entity id, an ancestor-or-self of the effector: the highest bone this goal rotates |
+| `position_weight`, `rotation_weight` | 0..1 |
+
+- References are fixed while attached.
+- The goal removes itself when its target or any joint on its path is destroyed, as
+  `TransformAttachment` does when its parent dies.
+- A rejected goal holds nothing. Rejection is a real branch plus an assert, because asserts are
+  stripped in production. A goal is rejected for:
+  - a `chain_root` that is not an ancestor-or-self of the effector;
+  - a target hanging below its own path;
+  - a two-bone path whose knee has no bend side.
+- A target hanging below *another* goal's joints in the same tree (a grip on a weapon held by the
+  other hand) is read from the solver's current frames on every iteration. Convergence is measured
+  in S4.
+- Across groups, dependencies order the solves, and a cycle rejects both groups.
+
+**Joint limits are the physics `Joint` on the bone.** Physics already has this as a 6-DOF
+description (PhysX D6): per-axis `DofMode`, limits, `localBasisA/B`, and two entity ids.
+- On a bone, `entityA` is the parent bone and `entityB` is the bone itself.
+- Asserted at link:
+  - `entityA` equals `TransformAttachment.parent`;
+  - `localBasisA = rest_local · localBasisB`;
+  - `swingTwist` is on. Without it, physics measures angles as 2 sin(θ/2), so limits above 114.6°
+    never engage and physics and IK would disagree.
+- **Hinge** (`asHinge`) gives the knee's `mid_axis`. Its bend side comes from asymmetric limits.
+- **Cone-twist** gives twist on X and separate Y/Z swing, and IK clamps to the same box physics
+  allows.
+- IK ignores anchors, linear DOFs, SPRING and MOTOR.
+- **Shared maths.** `swing_twist_error*` moves from `physics/constraint/solve_constraints.js` to
+  `core/geom/3d/quaternion/`; the clamp is new.
+- **Contract.** Physics simulates a `Joint` only when both sides have a body (or `JOINT_WORLD`).
+  Otherwise it is a kinematic limit. Nothing observes `Joint` today.
+
+**Solver settings** (`max_iterations`, `tolerance`) belong to the system.
+
+## 4. Contacts come from physics
+
+A foot is a joint, the ground is a collider, and contact points are physics' job. IK probes
+nothing: today's terrain prober goes, and nothing here touches `Terrain` or `ClingToTerrain`.
+
+- **A goal that should touch a surface** gets its target from a physics query: a ray or shape cast
+  (`PhysicsSystem.raycast`, `shapeCast`) from a reference the rig provides, returning a
+  `PhysicsSurfacePoint` (position, normal, entity).
+- **The component lives in the physics package.** It is a generic contact-probe component that
+  places its entity at the hit and aligns it to the normal. It knows nothing about IK or feet, so
+  footsteps, decals and AI can use it too. Physics has no query component today;
+  `PhysicsSurfacePoint` was written with "a ground sensor" in mind.
+- **Its contract:**
+  - it exact-evaluates a GPU-composed reference through `T64WorldCache`;
+  - it writes its own attachment offset;
+  - it skips the character's own colliders (same `ParentEntity` root);
+  - it runs in `update`, before IK;
+  - its reference must not be held by IK, or the target would chase IK's output (asserted by the
+    IK side, §3).
+- Pelvis lowering comes later.
+
+## 5. Bones a clip drives: IK holds them
+
+Downstream code (`t64_evaluate_world`, `T64WorldCache`, sockets, cloth anchors, the GPU hierarchy)
+reads the held offset exactly as it reads cloth's, and never learns that IK exists.
+
+- **Link:** hold `TransformAttachment` on every joint of the path, capture the offsets, and write the
+  evaluated base pose at once, so no frame shows the bind pose.
+- **Every tick:** write each held joint's full local: translation, rotation and scale, since a hold
+  mutes every channel. The base comes from `pose_evaluate_local`, never from a held offset.
+- **Unlink:** write the captured offset back, then unhold, guarded by `entityExists`.
+- **One holder per joint:** IK on a cloth-held joint trips the existing assert.
+- **Cost:** 37 / 127 / 531 µs per character per tick at 2 / 8 / 30 registered clips (34 levels),
+  because every level scans every channel of every clip.
+- **Ordering:** IK declares what it reads, `Animation` and `AnimationGraphController`. The drivers
+  declare that they write them. With the scheduler fixed (below), IK then runs after the drivers.
+  Cloth needs no order against IK: it runs in `fixedUpdate` on the previous update's consistent
+  state.
+
+## 6. Prerequisites (separate tasks)
+
+1. **Holds: LANDED** (`84f2f7267`, `c01c0ebbd`). A clip that binds during a hold takes the rest the holder
+   leaves when the hold ends, and that offset reaches the row.
+2. **Pose evaluator:** index channels by target (the cost row above). Sockets and cloth gain too.
+3. **Scheduler:** a system that reads X and writes Y sorts before the writer of X. Measured with
+   synthetic components: Producer (X) and Consumer (X → Y) order as `Consumer > Producer` in both
+   registration orders. `system_execution_order.spec.js` covers only a pure reader. The fix stays
+   inside derived ordering.
+
+## 7. Stages
+
+Each stage is red-then-green.
+
+1. **S1 Frame FABRIK:** a pure solver over typed arrays.
+2. **S2 Two-bone paths:** `two_joint_ik` with the hinge read from the `Joint`.
+3. **S3 Limits:** the shared swing-twist maths, the clamp, and `Joint` frames inside the passes.
+4. **S4 ECS, landing together:**
+   - `IKGoal` and its system (groups, holds, base evaluation, target reads, declarations);
+   - the physics contact-probe component;
+   - in the same change, `InverseKinematics`, `IKConstraint`, `2BIK`, `1BSA`, the terrain prober
+     and the adapter go (hard break).
+5. **S5 Later:** pelvis lowering, twist distribution, goal priority, pole goals.
+
+## 8. Sources
+
+- [A] Aristidou, Chrysanthou, Lasenby, *Extending FABRIK with model constraints*, CAVW 2016
+- [C] Aristidou, Lasenby, *FABRIK*, Graphical Models 73, 2011
+- [D] Baerlocher, Boulic, *Parametrization and range of motion of the ball-and-socket joint*, 2001
+- [G] UE 5.4 source: `Plugins/Experimental/FullBodyIK/Source/PBIK/`, `AnimNode_FootPlacement`
+- [N] ozz-animation `ik_two_bone_job.h`, `samples/foot_ik/sample_foot_ik.cc`
+
+## 9. After implementation (2026-10-06)
+
+Measured while implementing S1–S4, and decided with the owner where it changed anything.
+
+- **The fit** is 8 steps of power iteration warm-started from the carried rotation: 110–130 ns a fit
+  against 610–790 ns for the exact Jacobi fit, which also turns the chest about its shoulder line
+  from rounding (a 40–175° bend at the chest joint, converged, where the warm start bends 0–54°).
+- **The 0/0** of this mechanism is a target on the effector's parent, at any bone lengths: the parent
+  is fitted toward a child sitting on its old position. A target at a limb's top with equal bones is
+  finite and reached. A straight arm turned only at the shoulder, its target exactly on the elbow,
+  has no side to fold to and stays (finite); 1e-12 m off, it reaches.
+- **An effector inside another goal's path** (a goal on the elbow under a goal on the hand) is one
+  more proposal in its joint's mean, weighted by its goal's weight (owner's decision; pinning it at
+  its target moved the pose 161 mm at weight 0). Weight 0 is no goal, 0.001 moves it 0.05 mm, and two
+  equal goals that disagree meet half way.
+- **`FrameFabrikProblem` takes `base_local_rotation`**: a goal's root is limited against its
+  parent's fixed frame, which world rotations alone do not give.
+- **A hinge alone on a longer path can lock**: the arc fits never twist the shoulder to bring an
+  elbow's hinge plane round, so a target off it left the arm straight, 350 / 334 mm short; a
+  cone-twist on the shoulder unlocks it (1.4 mm at 16 iterations, 0 at 64). Hinges also slow a grip
+  pair down: 65 / 220 mm at 16 iterations, 0 at 64. Two-bone paths are analytic and unaffected.
+  Stated, not fixed.
+- **"Below its own path"** means the deepest posed bone the target hangs from is a bone of the goal's
+  own path. A grip on a weapon in the other hand hangs below the gripping hand's own chest too, but
+  the other arm's bones carry it, so it is read from the solver's frames. Known only with every goal,
+  so it is found when the groups are formed; a target below the effector itself is refused at link.
+- **The contact probe** casts a sphere of `radius`, a ray at 0. It and IK both read and write
+  `TransformAttachment`, so declared access leaves them a cycle and the scheduler keeps their
+  registration order: the probe is registered first (owner's decision). That its reference must not
+  be held by a CPU writer is documented on `ContactProbe`, not asserted (owner's decision): IK cannot
+  check it without knowing the probe's component.

package/src/engine/ecs/parent/EntityNode.js

@@ -311,12 +311,12 @@ export class EntityNode {
             // wrote `parent` onto a detached instance. The node kept lifetime parentage with no
             // transform attachment, so it rendered at its raw Transform64 in world space.
             if (attachment === null) {
-                attachment = this.__safe_get_attachment();
-            } else {
-                this_entity.add(attachment);
+                attachment = new TransformAttachment();
+                attachment.setFlag(TransformAttachmentFlags.Immediate);
             }
 
             attachment.parent = parent_entity_id;
+            this_entity.add(attachment);
         }
     }
 

package/src/engine/ecs/speaker/VoiceSystem.d.ts

@@ -9,7 +9,7 @@ export class VoiceSystem extends AbstractContextSystem<any> {
         font_size: number;
     });
     dependencies: (typeof Voice)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof GUIElement> | ResourceAccessSpecification<typeof ViewportPosition> | ResourceAccessSpecification<typeof HeadsUpDisplay> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof SerializationMetadata> | ResourceAccessSpecification<typeof BehaviorComponent>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof GUIElement> | ResourceAccessSpecification<typeof ViewportPosition> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof HeadsUpDisplay> | ResourceAccessSpecification<typeof SerializationMetadata> | ResourceAccessSpecification<typeof BehaviorComponent>)[];
     /**
      *
      * @type {Localization}
@@ -105,8 +105,8 @@ import { Transform64 } from "../transform/Transform64.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import GUIElement from "../gui/GUIElement.js";
 import ViewportPosition from "../gui/position/ViewportPosition.js";
-import HeadsUpDisplay from "../gui/hud/HeadsUpDisplay.js";
 import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
+import HeadsUpDisplay from "../gui/hud/HeadsUpDisplay.js";
 import { SerializationMetadata } from "../components/SerializationMetadata.js";
 import { BehaviorComponent } from "../../intelligence/behavior/ecs/BehaviorComponent.js";
 //# sourceMappingURL=VoiceSystem.d.ts.map

package/src/engine/ecs/speaker/VoiceSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VoiceSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/speaker/VoiceSystem.js"],"names":[],"mappings":"AA0KA;IA2CI;;;;OAIG;IACH;;;OA8CC;IA7FD,+BAAuB;IACvB,gZAQE;IAEF;;;OAGG;IACH,0BAAmB;IAEnB;;;OAGG;IACH,eAAW;IAEX;;;OAGG;IACH,4BAAa;IAEb;;;OAGG;IACH,8BAAY;IAEZ;;;;OAIG;IACH,iCAAqC;IAajC;;;OAGG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAkC;IAGlC;;;;OAIG;IACH,eAAkB;IAElB;;;;OAIG;IACH,oBAAgC;IAEhC;;;OAGG;IACH,oBAAqC;IAErC;;;;OAIG;IACH,gBAAoB;IAGxB;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAEF,2CAqBE;IAED;;;;;OAKG;IACH,uBAJW,MAAM,UACN,MAAM,SACN,KAAK,QAsBf;IAED;;;;;;OAMG;IACH,wBAoBC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,WACN,MAAM,SACN,KAAK,QAiIf;CACJ;sCA5cqC,oCAAoC;sBAKpD,YAAY;4BAFN,6BAA6B;4CAxBb,oDAAoD;uBAkBzE,sBAAsB;6BAEhB,qCAAqC;2BADvC,8BAA8B;oCAIrB,gDAAgD;sCAR9C,wCAAwC;kCAP5C,sDAAsD"}
+{"version":3,"file":"VoiceSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/speaker/VoiceSystem.js"],"names":[],"mappings":"AA0KA;IA2CI;;;;OAIG;IACH;;;OA8CC;IA7FD,+BAAuB;IACvB,gZAQE;IAEF;;;OAGG;IACH,0BAAmB;IAEnB;;;OAGG;IACH,eAAW;IAEX;;;OAGG;IACH,4BAAa;IAEb;;;OAGG;IACH,8BAAY;IAEZ;;;;OAIG;IACH,iCAAqC;IAajC;;;OAGG;IACH,eAAoB;IAEpB;;;;OAIG;IACH,kBAAkC;IAGlC;;;;OAIG;IACH,eAAkB;IAElB;;;;OAIG;IACH,oBAAgC;IAEhC;;;OAGG;IACH,oBAAqC;IAErC;;;;OAIG;IACH,gBAAoB;IAGxB;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAEF,2CAqBE;IAED;;;;;OAKG;IACH,uBAJW,MAAM,UACN,MAAM,SACN,KAAK,QA0Bf;IAED;;;;;;OAMG;IACH,wBAoBC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,WACN,MAAM,SACN,KAAK,QAiIf;CACJ;sCAhdqC,oCAAoC;sBAKpD,YAAY;4BAFN,6BAA6B;4CAxBb,oDAAoD;uBAkBzE,sBAAsB;6BAEhB,qCAAqC;oCAG9B,gDAAgD;2BAJzD,8BAA8B;sCAJnB,wCAAwC;kCAP5C,sDAAsD"}

package/src/engine/ecs/speaker/VoiceSystem.js

@@ -320,6 +320,10 @@ export class VoiceSystem extends AbstractContextSystem {
 
         const selected_line = weightedRandomFromArray(temp_lines, Math.random, this.__weigher.compute, this.__weigher, collected_count);
 
+        if (selected_line === undefined) {
+            return;
+        }
+
         this.sayLine(entity, selected_line.id, voice);
     }
 

package/src/engine/ecs/storage/BinaryBufferDeSerializer.js

@@ -113,11 +113,6 @@ function deserializeTask(
     function cycleFunction() {
         while (collectionDeSerializer.getElementIndex() >= collectionDeSerializer.getElementCount()) {
 
-            //finished current type
-            if (typesLeft === 0) {
-                return TaskSignal.EndSuccess;
-            }
-
             const previousClass = collectionDeSerializer.getElementClass();
 
             if (typesDecoded > 0) {
@@ -126,6 +121,11 @@ function deserializeTask(
                 collectionDeSerializer.finalize();
             }
 
+            //finished current type
+            if (typesLeft === 0) {
+                return TaskSignal.EndSuccess;
+            }
+
             typesDecoded++;
 
             //start next type

package/src/engine/ecs/storage/BinaryBufferSerializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryBufferSerializer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/BinaryBufferSerializer.js"],"names":[],"mappings":";AAmDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,sCAAgB;IAEhB;;;OAGG;IACH,QAFU,GAAG,GAAC,IAAI,CAEJ;IAEd;;;;OAIG;IACH,qEAmIC;CACJ"}
+{"version":3,"file":"BinaryBufferSerializer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/BinaryBufferSerializer.js"],"names":[],"mappings":";AAkDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,sCAAgB;IAEhB;;;OAGG;IACH,QAFU,GAAG,GAAC,IAAI,CAEJ;IAEd;;;;OAIG;IACH,qEAmIC;CACJ"}

package/src/engine/ecs/storage/BinaryBufferSerializer.js

@@ -24,15 +24,14 @@ function isComponentClassSerializable(componentClass) {
  * @returns {boolean}
  */
 function isEntityTransient(entity, dataset, smComponentIndex, componentInstance) {
-    if (smComponentIndex === -1) {
-        return false;
-    }
-
-    //check component instance flag
+    //check component instance flag, it does not depend on SerializationMetadata
     if (componentInstance[COMPONENT_SERIALIZATION_TRANSIENT_FIELD] === true) {
         return true;
     }
 
+    if (smComponentIndex === -1) {
+        return false;
+    }
 
     /**
      *

package/src/engine/ecs/storage/binary/BinarySerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinarySerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/storage/binary/BinarySerializationRegistry.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;GAKG;AACH;IAEI;;;;OAIG;IACH,2BAAsB;IACtB;;;;OAIG;IACH,6BAAwB;IAWxB;;;OAGG;IACH,2BAFW,qFAAiC,QAM3C;IAED;;;;;;OAMG;IACH,0HAJW,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,sFAAgC,SAAS,CA2BrD;IAED;;;;;;;OAOG;IACH,+BAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,sFAAgC,SAAS,CAMrD;IAED;;;;;OAKG;IACH,4BAJW,MAAM,YACN,mBAAmB,GACjB,OAAO,CA6CnB;IAED;;;;;;OAMG;IACH,6BALW,MAAM,gBACN,MAAM,eACN,MAAM,GACJ,mBAAmB,EAAE,GAAC,IAAI,CA0DtC;IAIL;;;OAGG;IACH,wCAFU,OAAO,CAEkD;;CANlE;;kCArQY,OAAO,0BAA0B,EAAE,mBAAmB"}
+{"version":3,"file":"BinarySerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/storage/binary/BinarySerializationRegistry.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;GAKG;AACH;IAEI;;;;OAIG;IACH,2BAAsB;IACtB;;;;OAIG;IACH,6BAAwB;IAWxB;;;OAGG;IACH,2BAFW,qFAAiC,QAM3C;IAED;;;;;;OAMG;IACH,0HAJW,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,sFAAgC,SAAS,CA2BrD;IAED;;;;;;;OAOG;IACH,+BAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,sFAAgC,SAAS,CAMrD;IAED;;;;;OAKG;IACH,4BAJW,MAAM,YACN,mBAAmB,GACjB,OAAO,CA6CnB;IAED;;;;;;OAMG;IACH,6BALW,MAAM,gBACN,MAAM,eACN,MAAM,GACJ,mBAAmB,EAAE,GAAC,IAAI,CA0DtC;IAIL;;;OAGG;IACH,wCAFU,OAAO,CAEkD;;CANlE;;kCArQY,OAAO,0BAA0B,EAAE,mBAAmB"}

package/src/engine/ecs/storage/binary/BinarySerializationRegistry.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { EdgeDirectionType } from "../../../../core/graph/Edge.js";
 import { Graph } from "../../../../core/graph/v2/Graph.js";
 
 /**
@@ -190,9 +191,9 @@ export class BinarySerializationRegistry {
             }
 
             if (u.getStartVersion() === upgrader.getTargetVersion()) {
-                classUpgraders.createEdge(u, upgrader);
+                classUpgraders.createEdge(upgrader, u, EdgeDirectionType.Forward);
             } else if (u.getTargetVersion() === upgrader.getStartVersion()) {
-                classUpgraders.createEdge(upgrader, u);
+                classUpgraders.createEdge(u, upgrader, EdgeDirectionType.Forward);
             }
         });
 

package/src/engine/ecs/storage/binary/SERIALIZATION_COVERAGE.md

@@ -57,8 +57,8 @@ threw, no save containing these behaviours can exist, so there is no data to sta
 
 ## Adapters still without a spec
 
-29 files, of which `BinaryClassSerializationAdapter.js` (the base class) and
-`ObjectBasedClassSerializationAdapter.js` (a helper) are not adapters — so **27 real ones**. Every entry is an
+28 files, of which `BinaryClassSerializationAdapter.js` (the base class) and
+`ObjectBasedClassSerializationAdapter.js` (a helper) are not adapters — so **26 real ones**. Every entry is an
 adapter nothing currently verifies.
 
 Sixteen of these are the ones whose `serialize` threw under the old harness. That is not a coincidence and it
@@ -71,7 +71,6 @@ fixture rather than a default instance. `FogOfWar` needs correctly-sized height
 | `Animation` | `engine/ecs/animation/AnimationSerializationAdapter.js` |
 | `FogOfWar` | `engine/ecs/fow/serialization/FogOfWarSerializationAdapter.js` |
 | `GUIElement` | `engine/ecs/gui/GUIElementSerializationAdapter.js` |
-| `InverseKinematics` | `engine/ecs/ik/InverseKinematicsSerializationAdapter.js` |
 | `Book` | `engine/ecs/storage/binary/BinaryClassSerializationAdapter.js` |
 | `?` | `engine/ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js` |
 | `Terrain` | `engine/ecs/terrain/serialization/TerrainSerializationAdapter.js` |
@@ -106,6 +105,11 @@ The per-upgrader spec should assert **the restored field values**, not the byte
 asserted. The byte count was a proxy it used because it had no idea what the values ought to be; a spec that
 names one upgrader does know, and should say so.
 
+Upgraders added since carry that spec from the start. The first was IK's, which wrote a version 0 constraint
+field by field, ran it through the chain the engine registry hands a load, and asserted every restored field;
+it went with the component it upgraded (2026-10-06, a hard break: IK's goals live on bones, which are never
+saved).
+
 ### Goldens to port
 
 ```js

package/src/engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js

@@ -413,7 +413,7 @@ export class BinaryObjectSerializationAdapter2 {
             // reference to the schema else-where
             const schema_address = buffer.readUintVar();
 
-            record = this.#schema_table.getRecord(schema_address);
+            record = this.#schema_table.getSchemaAt(schema_address);
         }
 
         const typeName = record.typeName;

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryObjectDeSerializer.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;GAYG;AACH;IA4BI;;;OAGG;IACH,6EAGC;IAED;;OAEG;IACH,yDAKC;IAED;;OAEG;IACH,kDAEC;IAED;;;;;;OAMG;IACH,uBAHW,YAAY,KAwCtB;IA0BD;;;;;;OAMG;IACH,uBAHW,YAAY,OAgDtB;IAoFL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;;CAN5D;;;;;;;cAvRa,MAAM;;;;aACN,MAAM;;;;aACN,kCAAgC,SAAS;;;;WACzC,WAAS,SAAS;;;;eAClB,qBAAqB,GAAC,IAAI;;;;uBAC1B,OAAO;;6BAjCQ,4CAA4C"}
+{"version":3,"file":"BinaryObjectDeSerializer.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;GAYG;AACH;IA4BI;;;OAGG;IACH,6EAGC;IAED;;OAEG;IACH,yDAKC;IAED;;OAEG;IACH,kDAEC;IAED;;;;;;OAMG;IACH,uBAHW,YAAY,KAwCtB;IA0BD;;;;;;OAMG;IACH,uBAHW,YAAY,OAgDtB;IA2FL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;;CAN5D;;;;;;;cA9Ra,MAAM;;;;aACN,MAAM;;;;aACN,kCAAgC,SAAS;;;;WACzC,WAAS,SAAS;;;;eAClB,qBAAqB,GAAC,IAAI;;;;uBAC1B,OAAO;;6BAjCQ,4CAA4C"}

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js

@@ -258,7 +258,14 @@ export class BinaryObjectDeSerializer {
         const names = this.#shapes[shapeIdx];
 
         for (let i = 0; i < names.length; i++) {
-            target[names[i]] = this.readValue(buffer);
+            const name = names[i];
+            const value = this.readValue(buffer);
+            if (name === "__proto__") {
+                // This wire-format field is own data, not a prototype setter.
+                Object.defineProperty(target, name, { value, writable: true, enumerable: true, configurable: true });
+            } else {
+                target[name] = value;
+            }
         }
 
         return target;

package/src/engine/ecs/storage/populateEngineSerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAoLA;;;;;;;;GAQG;AACH,iGA8GC"}
+{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAwLA;;;;;;;;GAQG;AACH,iGAiHC"}

package/src/engine/ecs/storage/populateEngineSerializationRegistry.js

@@ -17,7 +17,6 @@ import { HeadsUpDisplaySerializationAdapter } from "../gui/hud/HeadsUpDisplaySer
 import {
     ViewportPositionSerializationAdapter
 } from "../gui/position/ViewportPositionSerializationAdapter.js";
-import { InverseKinematicsSerializationAdapter } from "../ik/InverseKinematicsSerializationAdapter.js";
 import { NameSerializationAdapter } from "../name/NameSerializationAdapter.js";
 import { TeamSerializationAdapter } from "../team/TeamSerializationAdapter.js";
 import ClingToTerrain from "../terrain/ecs/cling/ClingToTerrain.js";
@@ -81,6 +80,8 @@ import {
     HighlightSerializationUpgrader_0_1
 } from "../../graphics/ecs/highlight/HighlightSerializationUpgrader_0_1.js";
 import { LightSerializationAdapter } from "../../graphics/ecs/light/LightSerializationAdapter.js";
+import { Light } from "../../graphics/ecs/light/Light.js";
+import { LightSerializationUpgrader_0_1 } from "../../graphics/ecs/light/LightSerializationUpgrader_0_1.js";
 import {
     SGMeshSerializationAdapter
 } from "../../graphics/ecs/mesh-v2/aggregate/serialization/SGMeshSerializationAdapter.js";
@@ -90,8 +91,11 @@ import { WaterSerializationUpgrader_0_1 } from "../../graphics/ecs/water/WaterSe
 import { WaterSerializationUpgrader_1_2 } from "../../graphics/ecs/water/WaterSerializationUpgrader_1_2.js";
 import { WaterSerializationUpgrader_2_3 } from "../../graphics/ecs/water/WaterSerializationUpgrader_2_3.js";
 import { WaterSerializationUpgrader_3_4 } from "../../graphics/ecs/water/WaterSerializationUpgrader_3_4.js";
+import { WaterSerializationUpgrader_4_5 } from "../../graphics/ecs/water/WaterSerializationUpgrader_4_5.js";
 import { MeshletGeometrySerializationAdapter } from "../../../shade/renderer/geometry/MeshletGeometrySerializationAdapter.js";
 import { WaterWavesSerializationAdapter } from "../../graphics/ecs/water/WaterWavesSerializationAdapter.js";
+import { WaterWavesSerializationUpgrader_0_1 } from "../../graphics/ecs/water/WaterWavesSerializationUpgrader_0_1.js";
+import WaterWaves from "../../graphics/ecs/water/WaterWaves.js";
 import { GridPosition2Transform } from "../../grid/grid2transform/GridPosition2Transform.js";
 import {
     GridPosition2TransformSerializationAdapter
@@ -237,7 +241,6 @@ export function populateEngineSerializationRegistry(registry) {
         new GUIElementSerializationAdapter(),
         new HeadsUpDisplaySerializationAdapter(),
         new BehaviorComponentSerializationAdapter(),
-        new InverseKinematicsSerializationAdapter(),
         new TooltipComponentSerializationAdapter(),
         new DecalSerializationAdapter(),
         new PickableSerializationAdapter(),
@@ -273,6 +276,7 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(FogOfWar.typeName, new FogOfWarSerializationUpdater_0_1());
 
     registry.registerUpgrader(Camera.typeName, new CameraSerializationUpgrader_0_1());
+    registry.registerUpgrader(Light.typeName, new LightSerializationUpgrader_0_1());
 
     registry.registerUpgrader(Path.typeName, new PathSerializationUpgrader_0_1());
     registry.registerUpgrader(Path.typeName, new PathSerializationUpgrader_1_2());
@@ -290,6 +294,8 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(Water.typeName, new WaterSerializationUpgrader_1_2());
     registry.registerUpgrader(Water.typeName, new WaterSerializationUpgrader_2_3());
     registry.registerUpgrader(Water.typeName, new WaterSerializationUpgrader_3_4());
+    registry.registerUpgrader(Water.typeName, new WaterSerializationUpgrader_4_5());
+    registry.registerUpgrader(WaterWaves.typeName, new WaterWavesSerializationUpgrader_0_1());
 
     registry.registerUpgrader(SoundEmitter.typeName, new SoundEmitterSerializationUpgrader_0_1());
     registry.registerUpgrader(SoundEmitter.typeName, new SoundEmitterSerializationUpgrader_1_2());
@@ -297,4 +303,5 @@ export function populateEngineSerializationRegistry(registry) {
     registry.registerUpgrader(TopDownCameraController.typeName, new TopDownCameraControllerSerializationUpgrader_0_1());
 
     registry.registerUpgrader(ClingToTerrain.typeName, new ClingToTerrainSerializationUpgrader_0_1());
+
 }

package/src/engine/ecs/system/orderSystemsByDeclaredAccess.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Orders systems by what they declare they touch: a system that writes (or creates) a component
+ * runs before every other system that reads it, when the two run in the same pass.
+ *
+ * A pass is `fixedUpdate` or `update`. Every fixed step runs before the update pass whatever this
+ * order says, so a write in one pass and a read in the other orders nothing, and is not counted —
+ * counting it could only close a cycle out of edges that are each real. One order serves both
+ * passes, so a system in both carries its edges into both.
+ *
+ * Without a cycle the result is a topological order of those edges. Where they leave a choice, the
+ * system with the higher priority runs first, and of equal priorities the one earlier in `systems`.
+ *
+ * A cycle — two systems that both read and write one component is the common one — has no order
+ * that respects every edge. So the rule is stated over cycles: the next system to run is the
+ * highest priority (then earliest) of those that wait on nothing but their own cycle, and a system
+ * on no cycle that waits on nothing qualifies as its own. Running a member of a cycle drops its
+ * edges from the rest of that cycle and nothing else. A system that waits on a cycle from outside
+ * it never qualifies before the cycle has run, so the only edges dropped are edges on a cycle.
+ *
+ * A cycle and a system that waits on nothing compete on those same terms, so a cycle runs where
+ * its best member's priority puts it, never held back behind systems no edge relates to it. Where
+ * sorting by priority alone already respects every edge, the result is that sort; and the result
+ * depends on nothing but the declarations, the passes, the priorities and the order of `systems`.
+ *
+ * O(n²) per system placed, O(n³) in all; it runs when the set of running systems changes.
+ *
+ * @param {System[]} systems sorted in place, the first `system_count` of them
+ * @param {number} system_count
+ * @param {Float64Array|number[]} priorities one per system, in the order `systems` arrives in; higher runs earlier
+ */
+export function orderSystemsByDeclaredAccess(systems: import("../System.js").System<any>[], system_count: number, priorities: Float64Array | number[]): void;
+export type System = import("../System.js").System<any>;
+//# sourceMappingURL=orderSystemsByDeclaredAccess.d.ts.map

package/src/engine/ecs/system/orderSystemsByDeclaredAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderSystemsByDeclaredAccess.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/system/orderSystemsByDeclaredAccess.js"],"names":[],"mappings":"AA8JA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,sDAJW,oCAAQ,gBACR,MAAM,cACN,YAAY,GAAC,MAAM,EAAE,QA+F/B"}