@woosh/meep-engine 3.43.0 → 3.44.0

package/src/engine/graphics3/RowChains.js

@@ -0,0 +1,347 @@
+import { assert } from "../../core/assert.js";
+import { EntityObserver } from "../ecs/EntityObserver.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../ecs/transform-attachment/TransformAttachment.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+
+/**
+ * @typedef {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../shade/renderer/scene/rows/GPUSceneRows.js").GPUSceneRows} GPUSceneRows
+ */
+
+/**
+ * What {@link RowChains} records for an entity with no attachment: the top of its chain.
+ *
+ * @type {number}
+ */
+const NO_PARENT = -1;
+
+/**
+ * The rows one system holds, each with the rows of everything it hangs from, kept where the
+ * entities say.
+ *
+ * **Why a chain and not a row.** A row whose attachment parent holds no row is written with its CPU
+ * world under the scene root. That is exact until something above it is driven on the GPU — a clip
+ * keying a joint takes the joint's whole subtree off the CPU, and its worlds there stop moving. So a
+ * primitive under an animated node, or a joint under another, composes correctly only when every
+ * entity above it holds a row too, and the GPU composes the chain from the top. A clip also binds
+ * only once every node it keys holds a row, so a chain is what lets it play at all.
+ *
+ * **Held per system.** One system's holds are its own: two primitives under one parent count twice
+ * here and hold the parent's row once. Two systems holding the same entity each hold its row — the
+ * rows count holders — and each follow it; across a model that overlap is the placing entity and a
+ * node or two.
+ *
+ * **Following is the dataset's events, as a placing system's always was.** An entity with an
+ * attachment holds its offset and its parent's row, so what moves it is a new offset, announced as
+ * `TRANSFORM_ATTACHMENT_EVENT_CHANGE`; its world follows on the GPU. The top of a chain holds its
+ * world, announced as `TRANSFORM64_EVENT_CHANGE`. One listener an entity, the same method for all of
+ * them, with the dataset passing the entity in.
+ *
+ * **A reparent is the attachment taken off and put back**, which no change event announces, so one
+ * observer on `TransformAttachment` watches for it and moves a held entity's hold onto its new chain.
+ *
+ * **Rows come and go with the device.** Until {@link bind} is given a scene's rows, holds and
+ * following are recorded and nothing is acquired; binding the rows of a new context after a restart
+ * acquires every held entity again, and no listener changes.
+ */
+export class RowChains {
+    /**
+     * @type {EntityComponentDataset}
+     */
+    #dataset;
+
+    /**
+     * @type {GPUSceneRows|null}
+     */
+    #rows = null;
+
+    /**
+     * How many times each entity is held here — by the system, and by every held entity hanging
+     * from it.
+     *
+     * @type {Map<number, number>}
+     */
+    #holds = new Map();
+
+    /**
+     * The entity each held entity holds through, or {@link NO_PARENT} at the top of a chain. What
+     * its attachment named when it was held, kept so the hold can be given back to the same parent
+     * after the attachment has gone.
+     *
+     * @type {Map<number, number>}
+     */
+    #parent = new Map();
+
+    /**
+     * @type {EntityObserver}
+     */
+    #observer;
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     */
+    constructor(dataset) {
+        assert.defined(dataset, 'dataset');
+        assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+
+        this.#dataset = dataset;
+
+        // a scene with no attachment in it still has chains, each one entity long
+        dataset.registerComponentType(TransformAttachment);
+
+        this.#observer = new EntityObserver([TransformAttachment], this.#attached, this.#detached, this);
+
+        dataset.addObserver(this.#observer, false);
+    }
+
+    /**
+     * The rows the chains are held in, or null while there is no device.
+     *
+     * @returns {GPUSceneRows|null}
+     */
+    get rows() {
+        return this.#rows;
+    }
+
+    /**
+     * Hold the chains in these rows from now on. Rows replaced by a restart took what they held
+     * with them, so nothing is given back to them; every held entity is acquired in the new ones.
+     *
+     * @param {GPUSceneRows|null} rows
+     */
+    bind(rows) {
+        if (rows === this.#rows) {
+            return;
+        }
+
+        this.#rows = rows;
+
+        if (rows === null) {
+            return;
+        }
+
+        for (const entity of this.#holds.keys()) {
+            rows.acquire(entity);
+        }
+    }
+
+    /**
+     * Whether this holds the entity, for itself or for something hanging from it.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    holds(entity) {
+        return this.#holds.has(entity);
+    }
+
+    /**
+     * Hold the entity's row and the rows of everything it hangs from. Every hold is matched by a
+     * {@link release}.
+     *
+     * @param {number} entity
+     */
+    hold(entity) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        const count = this.#holds.get(entity);
+
+        if (count !== undefined) {
+            this.#holds.set(entity, count + 1);
+
+            return;
+        }
+
+        assert.ok(this.#dataset.entityExists(entity), `entity ${entity} does not exist`);
+
+        const parent = this.#parent_named(entity);
+
+        this.#holds.set(entity, 1);
+        this.#parent.set(entity, parent);
+
+        this.#follow(entity, parent);
+
+        if (this.#rows !== null) {
+            this.#rows.acquire(entity);
+        }
+
+        if (parent !== NO_PARENT) {
+            this.hold(parent);
+        }
+    }
+
+    /**
+     * Let go of one hold. The last lets go of the entity's row and of the hold it had on its parent.
+     *
+     * @param {number} entity
+     */
+    release(entity) {
+        const count = this.#holds.get(entity);
+
+        assert.defined(count, `entity ${entity} is not held`);
+
+        if (count > 1) {
+            this.#holds.set(entity, count - 1);
+
+            return;
+        }
+
+        const parent = this.#parent.get(entity);
+
+        this.#holds.delete(entity);
+        this.#parent.delete(entity);
+
+        this.#unfollow(entity, parent);
+
+        if (this.#rows !== null) {
+            this.#rows.release(entity);
+        }
+
+        if (parent !== NO_PARENT) {
+            this.release(parent);
+        }
+    }
+
+    /**
+     * Let go of everything and stop watching the dataset.
+     */
+    destroy() {
+        const rows = this.#rows;
+
+        for (const [entity, parent] of this.#parent) {
+            this.#unfollow(entity, parent);
+
+            if (rows !== null) {
+                rows.release(entity);
+            }
+        }
+
+        this.#holds.clear();
+        this.#parent.clear();
+
+        this.#rows = null;
+
+        this.#dataset.removeObserver(this.#observer, false);
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {number} the entity its attachment names, or {@link NO_PARENT}
+     */
+    #parent_named(entity) {
+        const attachment = this.#dataset.getComponent(entity, TransformAttachment);
+
+        return attachment === undefined ? NO_PARENT : attachment.parent;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} parent
+     */
+    #follow(entity, parent) {
+        if (parent === NO_PARENT) {
+            this.#dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, this.#world_moved, this);
+        } else {
+            this.#dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, this.#offset_moved, this);
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} parent
+     */
+    #unfollow(entity, parent) {
+        if (!this.#dataset.entityExists(entity)) {
+            // its listeners went with it
+            return;
+        }
+
+        if (parent === NO_PARENT) {
+            this.#dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, this.#world_moved, this);
+        } else {
+            this.#dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, this.#offset_moved, this);
+        }
+    }
+
+    /**
+     * @param {*} event
+     * @param {number} entity
+     */
+    #offset_moved(event, entity) {
+        if (this.#rows !== null) {
+            this.#rows.mark_local(entity);
+        }
+    }
+
+    /**
+     * @param {*} event
+     * @param {number} entity
+     */
+    #world_moved(event, entity) {
+        if (this.#rows !== null) {
+            this.#rows.mark_world(entity);
+        }
+    }
+
+    /**
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    #attached(attachment, entity) {
+        if (!this.#holds.has(entity)) {
+            return;
+        }
+
+        const previous = this.#parent.get(entity);
+
+        if (previous !== attachment.parent) {
+            this.#move(entity, previous, attachment.parent);
+        }
+    }
+
+    /**
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    #detached(attachment, entity) {
+        if (!this.#holds.has(entity)) {
+            return;
+        }
+
+        const previous = this.#parent.get(entity);
+
+        if (previous !== NO_PARENT) {
+            this.#move(entity, previous, NO_PARENT);
+        }
+    }
+
+    /**
+     * The entity hangs from another parent, or from none. The new chain is held before the old one
+     * is let go, so an ancestor the two share keeps its row throughout.
+     *
+     * @param {number} entity
+     * @param {number} previous
+     * @param {number} next
+     */
+    #move(entity, previous, next) {
+        this.#unfollow(entity, previous);
+
+        this.#parent.set(entity, next);
+
+        this.#follow(entity, next);
+
+        if (next !== NO_PARENT) {
+            this.hold(next);
+        }
+
+        if (previous !== NO_PARENT) {
+            this.release(previous);
+        }
+
+        if (this.#rows !== null) {
+            // its row is written against the new parent, or as a world of its own
+            this.#rows.mark_local(entity);
+        }
+    }
+}

package/src/engine/graphics3/ShadedGeometrySystem.d.ts

@@ -16,6 +16,12 @@
  * on its component ({@link ShadedGeometryFlags.Skinned}) and draws a per-instance clone the
  * skinning pass writes; the skin itself is the model's business.
  *
+ * **A primitive holds the rows of everything it hangs from** ({@link RowChains}). Under a parent
+ * with no row it would carry its CPU world under the scene root, which stops moving the moment a
+ * clip drives a node above it — a rigid head under an animated tag is the common case. Holding the
+ * chain lets the GPU compose it from the top, and holds the tag's row, without which the clip never
+ * binds.
+ *
  * **Rows need a device.** A primitive linked before the renderer has started, or after it has been
  * replaced, waits: {@link update} notices the scene's GPU context arriving or changing and attaches
  * everything it holds to it. Nothing about the entity is lost meanwhile — the component and the

package/src/engine/graphics3/ShadedGeometrySystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometrySystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ShadedGeometrySystem.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAgCI;;;OAGG;IACH,sBAHW,cAAc,SACd,KAAK,EAYf;IADG,6DAAiD;IAGrD;;OAEG;IACH,iEAEC;IAED,2CAaC;IAED,4CAOC;IAuCD;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAqDhB;IAED;;;;OAIG;IACH,iBAJW,cAAc,aACd,WAAW,UACX,MAAM,QAOhB;;CAqDJ;8BA1SY,OAAO,+CAA+C,EAAE,eAAe;6BACvE,OAAO,qBAAqB,EAAE,cAAc;oBAC5C,OAAO,qCAAqC,EAAE,KAAK;uBAXzC,kBAAkB;4BACb,iCAAiC;+BAI9B,2CAA2C"}
+{"version":3,"file":"ShadedGeometrySystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ShadedGeometrySystem.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAwCI;;;OAGG;IACH,sBAHW,cAAc,SACd,KAAK,EAYf;IADG,6DAAiD;IAGrD;;OAEG;IACH,iEAEC;IAED,2CAeC;IAED,4CAUC;IA4CD;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAgDhB;IAED;;;;OAIG;IACH,iBAJW,cAAc,aACd,WAAW,UACX,MAAM,QAOhB;;CAsDJ;8BA9TY,OAAO,+CAA+C,EAAE,eAAe;6BACvE,OAAO,qBAAqB,EAAE,cAAc;oBAC5C,OAAO,qCAAqC,EAAE,KAAK;uBAXzC,kBAAkB;4BACb,iCAAiC;+BAG9B,2CAA2C"}