@woosh/meep-engine 3.40.0 → 3.42.0

package/src/engine/physics/ecs/ContactProbe.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Finds where a cast from a reference meets the world, and puts the entity it is on there.
+ *
+ * Every tick {@link ContactProbeSystem} casts a sphere of {@link radius} — a ray, at 0 — from the
+ * reference's world position plus {@link offset}, along {@link direction}, for {@link distance}, through
+ * the physics system's colliders. On a hit the entity is placed at the contact on the surface, turned
+ * as the reference is and tilted so the reference's up is the surface's normal. On a miss it is placed
+ * where the reference is. It knows nothing about who reads it: a foot reaching for the ground, a decal,
+ * an AI checking its footing.
+ *
+ * - The entity is placed through its own {@link TransformAttachment}, whose parent is up to the rig.
+ * - The character's own colliders are passed through: those whose lifetime ({@link ParentEntity})
+ *   leads to the same root as the probe's own.
+ * - The reference may be a bone a clip drives: its pose is evaluated exactly, as the GPU shows it. It
+ *   must not be a bone a CPU writer holds (IK, cloth), or the probe would read that writer's answer
+ *   and the writer would chase its own output.
+ *
+ * Entity ids are transient, so this is never saved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbe {
+    /**
+     * @param {{reference:number, offset:number[], direction:number[], distance:number, radius:number}} options
+     * every field required
+     * @returns {ContactProbe}
+     */
+    static from({ reference, offset, direction, distance, radius }: {
+        reference: number;
+        offset: number[];
+        direction: number[];
+        distance: number;
+        radius: number;
+    }): ContactProbe;
+    /**
+     * The entity the cast starts from.
+     * @type {number}
+     */
+    reference: number;
+    /**
+     * Where the cast starts, relative to the reference's world position, in world axes.
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly offset: Float64Array;
+    /**
+     * Which way the cast goes, in world, of unit length.
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly direction: Float64Array;
+    /**
+     * How far the cast reaches.
+     * @type {number}
+     */
+    distance: number;
+    /**
+     * The radius of the sphere cast; 0 casts a ray.
+     * @type {number}
+     */
+    radius: number;
+    /**
+     * Whether the last cast met anything. Written by {@link ContactProbeSystem}.
+     * @type {boolean}
+     */
+    hit: boolean;
+}
+export namespace ContactProbe {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=ContactProbe.d.ts.map

package/src/engine/physics/ecs/ContactProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContactProbe.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbe.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAuCI;;;;OAIG;IACH,gEAJW;QAAC,SAAS,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,EAAE,CAAC;QAAC,SAAS,EAAC,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAA;KAAC,GAErF,YAAY,CAuBxB;IAhED;;;OAGG;IACH,WAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,iBAFU,YAAY,CAEO;IAE7B;;;;OAIG;IACH,oBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,KAFU,OAAO,CAEL;CA6Bf;;kBAIS,MAAM;sBAMN,OAAO"}

package/src/engine/physics/ecs/ContactProbe.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Finds where a cast from a reference meets the world, and puts the entity it is on there.
+ *
+ * Every tick {@link ContactProbeSystem} casts a sphere of {@link radius} — a ray, at 0 — from the
+ * reference's world position plus {@link offset}, along {@link direction}, for {@link distance}, through
+ * the physics system's colliders. On a hit the entity is placed at the contact on the surface, turned
+ * as the reference is and tilted so the reference's up is the surface's normal. On a miss it is placed
+ * where the reference is. It knows nothing about who reads it: a foot reaching for the ground, a decal,
+ * an AI checking its footing.
+ *
+ * - The entity is placed through its own {@link TransformAttachment}, whose parent is up to the rig.
+ * - The character's own colliders are passed through: those whose lifetime ({@link ParentEntity})
+ *   leads to the same root as the probe's own.
+ * - The reference may be a bone a clip drives: its pose is evaluated exactly, as the GPU shows it. It
+ *   must not be a bone a CPU writer holds (IK, cloth), or the probe would read that writer's answer
+ *   and the writer would chase its own output.
+ *
+ * Entity ids are transient, so this is never saved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbe {
+    /**
+     * The entity the cast starts from.
+     * @type {number}
+     */
+    reference = -1;
+
+    /**
+     * Where the cast starts, relative to the reference's world position, in world axes.
+     * @readonly
+     * @type {Float64Array}
+     */
+    offset = new Float64Array(3);
+
+    /**
+     * Which way the cast goes, in world, of unit length.
+     * @readonly
+     * @type {Float64Array}
+     */
+    direction = Float64Array.of(0, -1, 0);
+
+    /**
+     * How far the cast reaches.
+     * @type {number}
+     */
+    distance = 0;
+
+    /**
+     * The radius of the sphere cast; 0 casts a ray.
+     * @type {number}
+     */
+    radius = 0;
+
+    /**
+     * Whether the last cast met anything. Written by {@link ContactProbeSystem}.
+     * @type {boolean}
+     */
+    hit = false;
+
+    /**
+     * @param {{reference:number, offset:number[], direction:number[], distance:number, radius:number}} options
+     * every field required
+     * @returns {ContactProbe}
+     */
+    static from({ reference, offset, direction, distance, radius }) {
+        assert.isNonNegativeInteger(reference, 'reference');
+        assert.equal(offset.length, 3, 'offset is [x, y, z]');
+        assert.equal(direction.length, 3, 'direction is [x, y, z]');
+        assert.ok(Math.abs(Math.hypot(direction[0], direction[1], direction[2]) - 1) < 1e-9, 'direction is of unit length');
+        assert.ok(distance > 0, 'distance is positive');
+        assert.ok(radius >= 0, 'radius is not negative');
+
+        const probe = new ContactProbe();
+
+        probe.reference = reference;
+        probe.offset[0] = offset[0];
+        probe.offset[1] = offset[1];
+        probe.offset[2] = offset[2];
+        probe.direction[0] = direction[0];
+        probe.direction[1] = direction[1];
+        probe.direction[2] = direction[2];
+        probe.distance = distance;
+        probe.radius = radius;
+
+        return probe;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+ContactProbe.typeName = "ContactProbe";
+
+/**
+ * Entity ids are transient: serialization is not applicable.
+ * @type {boolean}
+ */
+ContactProbe.serializable = false;

package/src/engine/physics/ecs/ContactProbeSystem.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Casts each {@link ContactProbe} and places its entity at what the cast meets.
+ *
+ * Runs in `update`, where the clips' times for the tick are set: a reference a clip drives is
+ * evaluated exactly (`T64WorldCache`), as the GPU draws it.
+ *
+ * **Register it before a system that reads where it puts its entities** and that writes
+ * `TransformAttachment` too, IK's among them. Both read and write `TransformAttachment`, so the
+ * order declared access derives leaves the two a cycle, and between them the scheduler keeps the
+ * order they were registered in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbeSystem extends System<any> {
+    constructor();
+    dependencies: (typeof TransformAttachment | typeof ContactProbe)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof AnimationGraphController> | ResourceAccessSpecification<typeof Animation> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof ContactProbe>)[];
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    link(probe: ContactProbe, attachment: TransformAttachment, entity: number): void;
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    unlink(probe: ContactProbe, attachment: TransformAttachment, entity: number): void;
+    update(time_delta_seconds: any): void;
+    #private;
+}
+import { System } from "../../ecs/System.js";
+import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
+import { ContactProbe } from "./ContactProbe.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { Collider } from "./Collider.js";
+import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { Animation } from "../../ecs/animation/Animation.js";
+import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+//# sourceMappingURL=ContactProbeSystem.d.ts.map

package/src/engine/physics/ecs/ContactProbeSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContactProbeSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbeSystem.js"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;GAaG;AACH;;IAEI,mEAAmD;IAEnD,2bASE;IAyCF;;;;OAIG;IACH,YAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAUhB;IAED;;;;OAIG;IACH,cAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAWhB;IAED,sCA2BC;;CAiKJ;uBA1VsB,qBAAqB;oCAER,uDAAuD;6BAY9D,mBAAmB;4BALzC,oCAAoC;4CAbC,oDAAoD;yBAiBvE,eAAe;yCAHC,uDAAuD;0BAbtE,kCAAkC;kCAC1B,oCAAoC;6BACzC,kCAAkC"}

package/src/engine/physics/ecs/ContactProbeSystem.js

@@ -0,0 +1,397 @@
+import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { quat3_shortest_arc } from "../../../core/geom/3d/quaternion/quat3_shortest_arc.js";
+import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
+import { SphereShape3D } from "../../../core/geom/3d/shape/SphereShape3D.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { Animation } from "../../ecs/animation/Animation.js";
+import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+import { System } from "../../ecs/System.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
+import { T64WorldCache } from "../../ecs/transform/T64WorldCache.js";
+import {
+    Transform64,
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../ecs/transform/Transform64.js";
+import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { collect_entity_playbacks } from "../../graphics3/pose/collect_entity_playbacks.js";
+import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
+import { Collider } from "./Collider.js";
+import { ContactProbe } from "./ContactProbe.js";
+import { PhysicsSystem } from "./PhysicsSystem.js";
+
+/**
+ * One linked probe and what its casts need.
+ */
+class ProbeRecord {
+    /**
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {ContactProbe|null}
+     */
+    probe = null;
+
+    /**
+     * @type {TransformAttachment|null}
+     */
+    attachment = null;
+
+    /**
+     * The sphere a non-zero radius casts.
+     * @type {SphereShape3D}
+     */
+    sphere = SphereShape3D.from(1);
+}
+
+const ray = new Ray3();
+const surface = new PhysicsSurfacePoint();
+
+const reference_world = new Transform64();
+const parent_world = new Transform64();
+
+const scratch_q = new Float64Array(4);
+const scratch_arc = new Float64Array(4);
+const scratch_v = new Float64Array(3);
+
+/**
+ * The cast's sphere turns with nothing: its orientation is the identity.
+ * @type {Float64Array}
+ */
+const NO_TURN = Float64Array.of(0, 0, 0, 1);
+
+/**
+ * Casts each {@link ContactProbe} and places its entity at what the cast meets.
+ *
+ * Runs in `update`, where the clips' times for the tick are set: a reference a clip drives is
+ * evaluated exactly (`T64WorldCache`), as the GPU draws it.
+ *
+ * **Register it before a system that reads where it puts its entities** and that writes
+ * `TransformAttachment` too, IK's among them. Both read and write `TransformAttachment`, so the
+ * order declared access derives leaves the two a cycle, and between them the scheduler keeps the
+ * order they were registered in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbeSystem extends System {
+
+    dependencies = [ContactProbe, TransformAttachment];
+
+    components_used = [
+        ResourceAccessSpecification.from(ContactProbe, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(GPUStateAuthority, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ParentEntity, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Animation, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(AnimationGraphController, ResourceAccessKind.Read),
+    ];
+
+    /**
+     * @type {ProbeRecord[]}
+     */
+    #records = [];
+
+    /**
+     * The root of the probe being cast: colliders whose lifetime leads to it are passed through.
+     * @type {number}
+     */
+    #owner = -1;
+
+    /**
+     * {@link #accept}, bound once.
+     * @type {function(number, Collider):boolean}
+     */
+    #filter = (entity, collider) => this.#accept(entity);
+
+    /**
+     * Exact worlds per model, for one tick.
+     * @type {Map<number, T64WorldCache>}
+     */
+    #caches = new Map();
+
+    /**
+     * @type {T64WorldCache[]}
+     */
+    #cache_list = [];
+
+    /**
+     * @type {Map<number, PosePlayback[]>}
+     */
+    #playbacks = new Map();
+
+    /**
+     * Which models' playbacks were collected this tick.
+     * @type {Set<number>}
+     */
+    #collected = new Set();
+
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    link(probe, attachment, entity) {
+        const record = new ProbeRecord();
+
+        record.entity = entity;
+        record.probe = probe;
+        record.attachment = attachment;
+
+        this.#records.push(record);
+    }
+
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    unlink(probe, attachment, entity) {
+        const records = this.#records;
+
+        for (let i = 0; i < records.length; i++) {
+            if (records[i].entity === entity) {
+                records.splice(i, 1);
+                return;
+            }
+        }
+    }
+
+    update(time_delta_seconds) {
+        const em = this.entityManager;
+        const dataset = em.dataset;
+
+        if (dataset === null || dataset === undefined) {
+            return;
+        }
+
+        const physics = em.getSystem(PhysicsSystem);
+
+        if (physics === null) {
+            return;
+        }
+
+        const caches = this.#cache_list;
+
+        for (let i = 0; i < caches.length; i++) {
+            caches[i].invalidate();
+        }
+
+        this.#collected.clear();
+
+        const records = this.#records;
+
+        for (let i = 0; i < records.length; i++) {
+            this.#cast(records[i], physics, dataset);
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {boolean} whether the cast may stop at this body
+     */
+    #accept(entity) {
+        return root_of(this.entityManager.dataset, entity) !== this.#owner;
+    }
+
+    /**
+     * @param {ProbeRecord} record
+     * @param {PhysicsSystem} physics
+     * @param {EntityComponentDataset} dataset
+     */
+    #cast(record, physics, dataset) {
+        const probe = record.probe;
+        const reference = probe.reference;
+
+        if (!dataset.entityExists(reference)) {
+            probe.hit = false;
+            return;
+        }
+
+        this.#world_of(reference_world, reference);
+
+        const ox = reference_world[TRANSFORM64_TRANSLATION_OFFSET] + probe.offset[0];
+        const oy = reference_world[TRANSFORM64_TRANSLATION_OFFSET + 1] + probe.offset[1];
+        const oz = reference_world[TRANSFORM64_TRANSLATION_OFFSET + 2] + probe.offset[2];
+
+        const dx = probe.direction[0], dy = probe.direction[1], dz = probe.direction[2];
+
+        ray.setOrigin(ox, oy, oz);
+        ray.setDirection(dx, dy, dz);
+        ray.tMax = probe.distance;
+
+        this.#owner = root_of(dataset, record.entity);
+
+        let hit;
+
+        if (probe.radius === 0) {
+            hit = physics.raycast(ray, surface, this.#filter);
+        } else {
+            record.sphere.radius = probe.radius;
+
+            hit = physics.shapeCast(ray, record.sphere, NO_TURN, surface, this.#filter);
+        }
+
+        probe.hit = hit;
+
+        // where the entity goes, and how it is turned, in world
+        let px, py, pz;
+
+        const rx = reference_world[TRANSFORM64_ROTATION_OFFSET];
+        const ry = reference_world[TRANSFORM64_ROTATION_OFFSET + 1];
+        const rz = reference_world[TRANSFORM64_ROTATION_OFFSET + 2];
+        const rw = reference_world[TRANSFORM64_ROTATION_OFFSET + 3];
+
+        if (hit) {
+            const nx = surface.normal[0], ny = surface.normal[1], nz = surface.normal[2];
+
+            // a sphere's centre stands off the surface by its radius
+            px = surface.position[0] - nx * probe.radius;
+            py = surface.position[1] - ny * probe.radius;
+            pz = surface.position[2] - nz * probe.radius;
+
+            // the reference, tilted so that its up is the surface's
+            quat3_shortest_arc(scratch_arc, 0, 0, 1, 0, nx, ny, nz);
+            quat3_multiply(scratch_q, 0, scratch_arc[0], scratch_arc[1], scratch_arc[2], scratch_arc[3], rx, ry, rz, rw);
+        } else {
+            px = reference_world[TRANSFORM64_TRANSLATION_OFFSET];
+            py = reference_world[TRANSFORM64_TRANSLATION_OFFSET + 1];
+            pz = reference_world[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+            scratch_q[0] = rx;
+            scratch_q[1] = ry;
+            scratch_q[2] = rz;
+            scratch_q[3] = rw;
+        }
+
+        this.#place(record, px, py, pz, dataset);
+    }
+
+    /**
+     * Write the entity's offset so its world pose is `p` turned by `scratch_q`.
+     *
+     * @param {ProbeRecord} record
+     * @param {number} px
+     * @param {number} py
+     * @param {number} pz
+     * @param {EntityComponentDataset} dataset
+     */
+    #place(record, px, py, pz, dataset) {
+        const parent = record.attachment.parent;
+
+        this.#world_of(parent_world, parent);
+
+        // conj(R_p)
+        const cx = -parent_world[TRANSFORM64_ROTATION_OFFSET];
+        const cy = -parent_world[TRANSFORM64_ROTATION_OFFSET + 1];
+        const cz = -parent_world[TRANSFORM64_ROTATION_OFFSET + 2];
+        const cw = parent_world[TRANSFORM64_ROTATION_OFFSET + 3];
+
+        // uniform scale, as TransformAttachment composes
+        const inverse_scale = 1 / parent_world[TRANSFORM64_SCALE_OFFSET];
+
+        v3_quaternion_apply(
+            scratch_v, 0,
+            (px - parent_world[TRANSFORM64_TRANSLATION_OFFSET]) * inverse_scale,
+            (py - parent_world[TRANSFORM64_TRANSLATION_OFFSET + 1]) * inverse_scale,
+            (pz - parent_world[TRANSFORM64_TRANSLATION_OFFSET + 2]) * inverse_scale,
+            cx, cy, cz, cw
+        );
+
+        quat3_multiply(scratch_arc, 0, cx, cy, cz, cw, scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);
+
+        const local = record.attachment.transform;
+
+        local.setTranslation(scratch_v[0], scratch_v[1], scratch_v[2]);
+        local.setRotation(scratch_arc[0], scratch_arc[1], scratch_arc[2], scratch_arc[3]);
+        local.updateMatrix();
+
+        dataset.sendEvent(record.entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+    }
+
+    /**
+     * The entity's world pose this tick, exactly, under its own model's clips.
+     *
+     * @param {Transform64} result
+     * @param {number} entity
+     */
+    #world_of(result, entity) {
+        const dataset = this.entityManager.dataset;
+
+        const model = model_of(dataset, entity);
+
+        let cache = this.#caches.get(model);
+
+        if (cache === undefined) {
+            cache = new T64WorldCache();
+            this.#caches.set(model, cache);
+            this.#cache_list.push(cache);
+        }
+
+        let playbacks = this.#playbacks.get(model);
+
+        if (playbacks === undefined) {
+            playbacks = [];
+            this.#playbacks.set(model, playbacks);
+        }
+
+        if (!this.#collected.has(model)) {
+            this.#collected.add(model);
+
+            playbacks.length = 0;
+
+            collect_entity_playbacks(playbacks, this.entityManager, model);
+        }
+
+        cache.evaluate(result, dataset, entity, playbacks);
+    }
+}
+
+/**
+ * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number}
+ */
+function model_of(dataset, entity) {
+    const owner = dataset.getComponent(entity, ParentEntity);
+
+    if (owner === undefined || owner === null) {
+        return entity;
+    }
+
+    return owner.entity;
+}
+
+/**
+ * The top of the lifetime chain an entity belongs to.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number}
+ */
+function root_of(dataset, entity) {
+    let e = entity;
+
+    for (let guard = 0; guard < 1024; guard++) {
+        const owner = dataset.getComponent(e, ParentEntity);
+
+        if (owner === undefined || owner === null || owner.entity < 0) {
+            return e;
+        }
+
+        e = owner.entity;
+    }
+
+    return e;
+}

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts

@@ -20,7 +20,7 @@
  * origin} becomes system-managed in this case.
  *
  * NOTE on layout: sibling physics ECS code lives under `engine/ecs/*` (see
- * `engine/ecs/ik/InverseKinematicsSystem.js`). This component is placed inside the
+ * `engine/ecs/ik/IKGoalSystem.js`). This component is placed inside the
  * fluid package because edits to the ECS folder were out-of-scope when it was first
  * written. Moving it under `engine/ecs/fluid/` later is a pure relocation.
  */

package/src/engine/physics/fluid/ecs/FluidComponent.js

@@ -24,7 +24,7 @@ import { FluidField } from "../FluidField.js";
  * origin} becomes system-managed in this case.
  *
  * NOTE on layout: sibling physics ECS code lives under `engine/ecs/*` (see
- * `engine/ecs/ik/InverseKinematicsSystem.js`). This component is placed inside the
+ * `engine/ecs/ik/IKGoalSystem.js`). This component is placed inside the
  * fluid package because edits to the ECS folder were out-of-scope when it was first
  * written. Moving it under `engine/ecs/fluid/` later is a pure relocation.
  */

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#423@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#429@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#423@#clear_field"(fluid: FluidComponent): void;
+    static "__#429@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#423@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#429@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#423@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#429@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAgHpB"}
+{"version":3,"file":"v3_grid_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAbW,YAAY,EAAE,WACd,YAAY,EAAE,aACd,YAAY,aACZ,YAAY,aACZ,YAAY,mBACZ,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QAuHpB"}