@woosh/meep-engine 3.40.0 → 3.41.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/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,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;oCAG9B,gDAAgD;2BAJzD,8BAA8B;sCAJnB,wCAAwC;kCAP5C,sDAAsD"}

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/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/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":"AAmLA;;;;;;;;GAQG;AACH,iGA8GC"}

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";
@@ -237,7 +236,6 @@ export function populateEngineSerializationRegistry(registry) {
         new GUIElementSerializationAdapter(),
         new HeadsUpDisplaySerializationAdapter(),
         new BehaviorComponentSerializationAdapter(),
-        new InverseKinematicsSerializationAdapter(),
         new TooltipComponentSerializationAdapter(),
         new DecalSerializationAdapter(),
         new PickableSerializationAdapter(),
@@ -297,4 +295,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"}

package/src/engine/ecs/system/orderSystemsByDeclaredAccess.js

@@ -0,0 +1,282 @@
+import { noop } from "../../../core/function/noop.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+
+/**
+ * @typedef {import("../System.js").System} System
+ */
+
+const PASS_FIXED_UPDATE = 1;
+const PASS_UPDATE = 2;
+
+const WRITES = ResourceAccessKind.Write | ResourceAccessKind.Create;
+
+/**
+ * Which of the two passes over the execution order a system takes part in. `openFixedStep` and
+ * `closeFixedStep` are not counted: they frame a step rather than simulate in it, and run outside
+ * the derived order on purpose (see {@link System#openFixedStep}).
+ *
+ * @param {System} system
+ * @returns {number} bitmask of PASS_* flags
+ */
+function system_passes(system) {
+    let result = 0;
+
+    if (system.fixedUpdate !== noop) {
+        result |= PASS_FIXED_UPDATE;
+    }
+
+    if (system.update !== noop) {
+        result |= PASS_UPDATE;
+    }
+
+    return result;
+}
+
+/**
+ * @param {Map<Function, number[]>} map
+ * @param {Function} component
+ * @param {number} system_index
+ */
+function map_push(map, component, system_index) {
+    const list = map.get(component);
+
+    if (list === undefined) {
+        map.set(component, [system_index]);
+    } else {
+        list.push(system_index);
+    }
+}
+
+/**
+ * Groups the unplaced systems into their strongly connected components — a cycle, or one system on
+ * no cycle — and marks each component that an unplaced system outside it still feeds. A component
+ * nothing outside it feeds holds systems that wait on nothing but each other, if on anything.
+ *
+ * Kosaraju's: a post-order over the edges, then trees over the reversed edges in reverse post-order,
+ * one component per tree. Iterative, O(n²) over the adjacency matrix.
+ *
+ * @param {number} system_count
+ * @param {Uint8Array} edges `edges[a * system_count + b] !== 0`: `a` runs before `b`
+ * @param {Uint8Array} placed
+ * @param {Int32Array} component output: component id per unplaced system
+ * @param {Uint8Array} fed output: per component id, 1 when something outside it feeds it
+ * @param {Uint8Array} visited scratch
+ * @param {Int32Array} post_order scratch
+ * @param {Int32Array} frame_system scratch, the depth-first stack
+ * @param {Int32Array} frame_next scratch, per stack frame the next system to look at
+ */
+function label_components(
+    system_count, edges, placed,
+    component, fed,
+    visited, post_order, frame_system, frame_next
+) {
+    visited.fill(0);
+
+    let finished = 0;
+
+    for (let root = 0; root < system_count; root++) {
+        if (placed[root] !== 0 || visited[root] !== 0) {
+            continue;
+        }
+
+        visited[root] = 1;
+
+        let depth = 0;
+        frame_system[0] = root;
+        frame_next[0] = 0;
+
+        while (depth >= 0) {
+            const a = frame_system[depth];
+            let b = frame_next[depth];
+
+            while (b < system_count && (placed[b] !== 0 || visited[b] !== 0 || edges[a * system_count + b] === 0)) {
+                b++;
+            }
+
+            if (b < system_count) {
+                frame_next[depth] = b + 1;
+
+                visited[b] = 1;
+
+                depth++;
+                frame_system[depth] = b;
+                frame_next[depth] = 0;
+            } else {
+                post_order[finished++] = a;
+                depth--;
+            }
+        }
+    }
+
+    component.fill(-1);
+
+    let component_count = 0;
+
+    for (let k = finished - 1; k >= 0; k--) {
+        const root = post_order[k];
+
+        if (component[root] !== -1) {
+            continue;
+        }
+
+        component[root] = component_count;
+
+        // `frame_system` is free again, and serves as a plain stack
+        let top = 0;
+        frame_system[top++] = root;
+
+        while (top > 0) {
+            const b = frame_system[--top];
+
+            for (let a = 0; a < system_count; a++) {
+                if (placed[a] !== 0 || component[a] !== -1 || edges[a * system_count + b] === 0) {
+                    continue;
+                }
+
+                component[a] = component_count;
+                frame_system[top++] = a;
+            }
+        }
+
+        component_count++;
+    }
+
+    fed.fill(0, 0, component_count);
+
+    for (let a = 0; a < system_count; a++) {
+        if (placed[a] !== 0) {
+            continue;
+        }
+
+        for (let b = 0; b < system_count; b++) {
+            if (placed[b] === 0 && edges[a * system_count + b] !== 0 && component[a] !== component[b]) {
+                fed[component[b]] = 1;
+            }
+        }
+    }
+}
+
+/**
+ * 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, system_count, priorities) {
+    const passes = new Uint8Array(system_count);
+
+    /** @type {Map<Function, number[]>} */
+    const writers = new Map();
+    /** @type {Map<Function, number[]>} */
+    const readers = new Map();
+
+    for (let i = 0; i < system_count; i++) {
+        const system = systems[i];
+
+        passes[i] = system_passes(system);
+
+        const components = system.referenced_components;
+        const component_count = components.length;
+
+        for (let j = 0; j < component_count; j++) {
+            const component = components[j];
+
+            const access = system.getAccessForComponent(component);
+
+            if ((access & WRITES) !== 0) {
+                map_push(writers, component, i);
+            }
+
+            if ((access & ResourceAccessKind.Read) !== 0) {
+                map_push(readers, component, i);
+            }
+        }
+    }
+
+    // edges[a * system_count + b] !== 0: a runs before b
+    const edges = new Uint8Array(system_count * system_count);
+
+    for (const [component, component_writers] of writers) {
+        const component_readers = readers.get(component);
+
+        if (component_readers === undefined) {
+            continue;
+        }
+
+        for (let i = 0; i < component_writers.length; i++) {
+            const writer = component_writers[i];
+
+            for (let j = 0; j < component_readers.length; j++) {
+                const reader = component_readers[j];
+
+                if (writer === reader || (passes[writer] & passes[reader]) === 0) {
+                    continue;
+                }
+
+                edges[writer * system_count + reader] = 1;
+            }
+        }
+    }
+
+    const placed = new Uint8Array(system_count);
+    const sorted = new Array(system_count);
+
+    const component = new Int32Array(system_count);
+    const fed = new Uint8Array(system_count);
+    const visited = new Uint8Array(system_count);
+    const post_order = new Int32Array(system_count);
+    const frame_system = new Int32Array(system_count);
+    const frame_next = new Int32Array(system_count);
+
+    for (let k = 0; k < system_count; k++) {
+        label_components(
+            system_count, edges, placed,
+            component, fed,
+            visited, post_order, frame_system, frame_next
+        );
+
+        // the components form an acyclic graph, so at least one of them is fed by nothing
+        let next = -1;
+
+        for (let i = 0; i < system_count; i++) {
+            if (placed[i] !== 0 || fed[component[i]] !== 0) {
+                continue;
+            }
+
+            if (next === -1 || priorities[i] > priorities[next]) {
+                next = i;
+            }
+        }
+
+        placed[next] = 1;
+        sorted[k] = systems[next];
+    }
+
+    for (let k = 0; k < system_count; k++) {
+        systems[k] = sorted[k];
+    }
+}