@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/ecs/transform/T64WorldCache.js

@@ -0,0 +1,139 @@
+import { assert } from "../../../core/assert.js";
+import { pose_evaluate_local } from "../../../shade/renderer/animation/pose/pose_evaluate_local.js";
+import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
+import { Transform64 } from "./Transform64.js";
+
+/**
+ * @typedef {import("../EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/animation/pose/PosePlayback.js").PosePlayback} PosePlayback
+ */
+
+/**
+ * {@link t64_evaluate_world}, memoised per entity for the length of a tick.
+ *
+ * An exact evaluation walks the chain to the root and evaluates every level's clips; a socket on a
+ * hand is fourteen levels deep on a character, and the sockets a game asks about share most of
+ * that chain. Within a tick the inputs — the hierarchy, the clip set, the times, the weights — do
+ * not move, so each entity's world is evaluated once and every query below it composes onto the
+ * stored answer. Measured on a 70-joint skeleton with two clips: 764 µs to evaluate every joint
+ * one query at a time, 160 µs through the cache.
+ *
+ * **One cache per tick, per model.** The answer for an entity depends on the playbacks it was
+ * evaluated under, and the cache does not check them: a caller that changes what a model plays
+ * between queries calls {@link invalidate} in between, and calls it once per tick regardless.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class T64WorldCache {
+    /**
+     * Evaluated worlds by entity, valid until {@link invalidate}.
+     *
+     * @type {Map<number, Transform64>}
+     */
+    #worlds = new Map();
+
+    /**
+     * Transforms handed back by {@link invalidate}, for the next tick's entries.
+     *
+     * @type {Transform64[]}
+     */
+    #pool = [];
+
+    /**
+     * Scratch for one level's animated local pose.
+     *
+     * @type {Transform64}
+     */
+    #local = new Transform64();
+
+    /**
+     * How many entities hold an evaluated world right now.
+     *
+     * @returns {number}
+     */
+    get size() {
+        return this.#worlds.size;
+    }
+
+    /**
+     * Forget every evaluated world. Once per tick, and again whenever a model's playbacks change
+     * within one.
+     */
+    invalidate() {
+        const pool = this.#pool;
+
+        for (const world of this.#worlds.values()) {
+            pool.push(world);
+        }
+
+        this.#worlds.clear();
+    }
+
+    /**
+     * The entity's world pose under the playbacks, exactly — the same answer as
+     * {@link t64_evaluate_world}, from the cache where it has it.
+     *
+     * @param {Transform64} result
+     * @param {EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {PosePlayback[]} playbacks
+     * @returns {Transform64} `result`
+     */
+    evaluate(result, dataset, entity, playbacks) {
+        assert.defined(result, 'result');
+        assert.defined(dataset, 'dataset');
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.isArray(playbacks, 'playbacks');
+
+        result.copy(this.#world_of(dataset, entity, playbacks));
+
+        return result;
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {PosePlayback[]} playbacks
+     * @returns {Transform64} the cache's own copy; not to be kept
+     */
+    #world_of(dataset, entity, playbacks) {
+        const cached = this.#worlds.get(entity);
+
+        if (cached !== undefined) {
+            return cached;
+        }
+
+        assert.ok(dataset.entityExists(entity), `entity ${entity} does not exist`);
+
+        const attachment = dataset.getComponent(entity, TransformAttachment);
+
+        const world = this.#pool.pop() ?? new Transform64();
+        const local = this.#local;
+
+        if (attachment === undefined || attachment === null || !dataset.entityExists(attachment.parent)) {
+            // the root of the chain, whose world pose is its own; a link whose parent has gone is
+            // a root until the attachment system detaches it, and answers from where it was
+            const rest = dataset.getComponent(entity, Transform64);
+
+            assert.defined(rest, `entity ${entity} carries no Transform64 and no attachment`);
+
+            pose_evaluate_local(local, entity, rest, playbacks);
+            local.updateMatrix();
+
+            world.copy(local);
+        } else {
+            // the parent first, so its answer is in the cache before this level's scratch is used
+            const parent = this.#world_of(dataset, attachment.parent, playbacks);
+
+            pose_evaluate_local(local, entity, attachment.transform, playbacks);
+            local.updateMatrix();
+
+            world.multiplyTransforms(parent, local);
+        }
+
+        this.#worlds.set(entity, world);
+
+        return world;
+    }
+}

package/src/engine/ecs/transform/t64_evaluate_world.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Evaluate an entity's **world** pose under a set of playing clips, exactly, from its own chain.
+ *
+ * This is the question gameplay asks of an animated model and the only way the simulation may
+ * ask it: where is the muzzle, where does this effect attach, where does the projectile leave
+ * from. It walks the entity's `TransformAttachment` parents to the root, evaluates each level's
+ * animated local pose from the clips ({@link pose_evaluate_local}, with the attachment's offset —
+ * or the root's `Transform64` — as the rest pose), and composes down in double precision. Nothing
+ * is read back from the GPU, nothing is a frame late, and nothing on the CPU has to have been
+ * composed first: the answer is a pure function of (hierarchy, clip set, time, weights), which is
+ * what keeps it deterministic on a peer with no device at all.
+ *
+ * An entity the GPU owns the transform of — see `GPUStateAuthority` — is answered the same way;
+ * that is the point. A row the GPU composes and a chain this evaluates agree to float precision.
+ *
+ * Each level costs a scan of every channel of every playing clip, so a query is a few
+ * microseconds at a character's depth and a whole skeleton one query at a time is most of a
+ * millisecond; a caller asking about several entities of one model within a tick goes through
+ * {@link T64WorldCache}, which evaluates each entity once and composes the rest onto it.
+ *
+ * @param {Transform64} result written with the evaluated world TRS and matrix
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {PosePlayback[]} playbacks every clip playing on the model, with its time and weight
+ * @returns {Transform64} `result`
+ */
+export function t64_evaluate_world(result: Transform64, dataset: EntityComponentDataset, entity: number, playbacks: PosePlayback[]): Transform64;
+export type EntityComponentDataset = import("../EntityComponentDataset.js").EntityComponentDataset;
+export type PosePlayback = import("../../../shade/renderer/animation/pose/PosePlayback.js").PosePlayback;
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=t64_evaluate_world.d.ts.map

package/src/engine/ecs/transform/t64_evaluate_world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_evaluate_world.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_evaluate_world.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CANW,WAAW,WACX,sBAAsB,UACtB,MAAM,aACN,YAAY,EAAE,GACZ,WAAW,CA2DvB;qCAvHY,OAAO,8BAA8B,EAAE,sBAAsB;2BAC7D,OAAO,wDAAwD,EAAE,YAAY;4BAJ9D,kBAAkB"}

package/src/engine/ecs/transform/t64_evaluate_world.js

@@ -0,0 +1,126 @@
+import { assert } from "../../../core/assert.js";
+import { pose_evaluate_local } from "../../../shade/renderer/animation/pose/pose_evaluate_local.js";
+import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
+import { Transform64 } from "./Transform64.js";
+
+/**
+ * @typedef {import("../EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/animation/pose/PosePlayback.js").PosePlayback} PosePlayback
+ */
+
+/**
+ * Scratch for one level of the parent walk. Depth is bounded by the hierarchy, and reusing a
+ * small stack keeps the query allocation-free.
+ *
+ * @type {Transform64[]}
+ */
+const SCRATCH = [];
+
+/**
+ * The chain from the entity up to its root, and each level's rest pose.
+ *
+ * @type {number[]}
+ */
+const CHAIN = [];
+
+/**
+ * @type {Transform64[]}
+ */
+const RESTS = [];
+
+/**
+ * @param {number} depth
+ * @returns {Transform64}
+ */
+function scratch_at(depth) {
+    while (SCRATCH.length <= depth) {
+        SCRATCH.push(new Transform64());
+    }
+
+    return SCRATCH[depth];
+}
+
+/**
+ * Evaluate an entity's **world** pose under a set of playing clips, exactly, from its own chain.
+ *
+ * This is the question gameplay asks of an animated model and the only way the simulation may
+ * ask it: where is the muzzle, where does this effect attach, where does the projectile leave
+ * from. It walks the entity's `TransformAttachment` parents to the root, evaluates each level's
+ * animated local pose from the clips ({@link pose_evaluate_local}, with the attachment's offset —
+ * or the root's `Transform64` — as the rest pose), and composes down in double precision. Nothing
+ * is read back from the GPU, nothing is a frame late, and nothing on the CPU has to have been
+ * composed first: the answer is a pure function of (hierarchy, clip set, time, weights), which is
+ * what keeps it deterministic on a peer with no device at all.
+ *
+ * An entity the GPU owns the transform of — see `GPUStateAuthority` — is answered the same way;
+ * that is the point. A row the GPU composes and a chain this evaluates agree to float precision.
+ *
+ * Each level costs a scan of every channel of every playing clip, so a query is a few
+ * microseconds at a character's depth and a whole skeleton one query at a time is most of a
+ * millisecond; a caller asking about several entities of one model within a tick goes through
+ * {@link T64WorldCache}, which evaluates each entity once and composes the rest onto it.
+ *
+ * @param {Transform64} result written with the evaluated world TRS and matrix
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {PosePlayback[]} playbacks every clip playing on the model, with its time and weight
+ * @returns {Transform64} `result`
+ */
+export function t64_evaluate_world(result, dataset, entity, playbacks) {
+    assert.defined(result, 'result');
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isArray(playbacks, 'playbacks');
+
+    CHAIN.length = 0;
+    RESTS.length = 0;
+
+    let cursor = entity;
+
+    while (cursor !== -1) {
+        assert.ok(dataset.entityExists(cursor), `entity ${cursor} in the chain above ${entity} does not exist`);
+
+        const attachment = dataset.getComponent(cursor, TransformAttachment);
+
+        CHAIN.push(cursor);
+
+        if (attachment === undefined || attachment === null || !dataset.entityExists(attachment.parent)) {
+            // the root of the chain, whose world pose is its own; a link whose parent has gone is
+            // a root until the attachment system detaches it, and answers from where it was
+            const world = dataset.getComponent(cursor, Transform64);
+
+            assert.defined(world, `entity ${cursor} carries no Transform64 and no attachment`);
+
+            RESTS.push(world);
+
+            break;
+        }
+
+        RESTS.push(attachment.transform);
+
+        cursor = attachment.parent;
+    }
+
+    // root first, so each step composes onto what is already accumulated
+    let depth = 0;
+
+    for (let i = CHAIN.length - 1; i >= 0; i--) {
+        const local = scratch_at(depth);
+
+        pose_evaluate_local(local, CHAIN[i], RESTS[i], playbacks);
+        local.updateMatrix();
+
+        if (i === CHAIN.length - 1) {
+            result.copy(local);
+        } else {
+            result.multiplyTransforms(result, local);
+        }
+
+        depth++;
+    }
+
+    CHAIN.length = 0;
+    RESTS.length = 0;
+
+    return result;
+}

package/src/engine/ecs/transform-attachment/TransformAttachmentSystem.d.ts

@@ -23,6 +23,14 @@
  * The index rests on {@link TransformAttachment.parent} being immutable while the component is
  * attached: `link` and `unlink` are then the only transitions a parent reference can undergo.
  *
+ * **What the GPU owns is not composed here.** An entity whose `GPUStateAuthority` gives the GPU its
+ * {@link Transform64} — a joint a clip drives, and everything under it — is skipped: nothing is
+ * written and nothing announced, so its subtree stays as the CPU last composed it. Nothing on the
+ * simulation side reads such an entity, by the rule that puts the bit there; what asks evaluates the
+ * chain exactly (`t64_evaluate_world`). An entity linked under a GPU-composed parent is declared and
+ * flagged at link, and the animation manager hands a subtree back with one announcement, which
+ * recomposes it here from the offsets it seeded.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */

package/src/engine/ecs/transform-attachment/TransformAttachmentSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransformAttachmentSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform-attachment/TransformAttachmentSystem.js"],"names":[],"mappings":"AAyLA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;IAEI;;;;OAIG;IACH,mBAAgB;IAEhB;;;;;OAKG;IACH,mBAAoC;IAEpC;;;;OAIG;IACH,gBAAa;IACb,qBAAiB;IACjB,uBAAmB;IAEnB,kEAAkD;IAClD,+HAGE;IAEF;;;;OAIG;IACH,wBASC;IAED;;;;OAIG;IACH,kBAEC;IAED;;;;;OAKG;IACH,yBAYC;IAED;;;;;;;;OAQG;IACH,uBALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iBAJW,mBAAmB,aACnB,WAAW,UACX,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,mBAJW,mBAAmB,aACnB,WAAW,UACX,MAAM,QAkBhB;IAED,6BAoBC;CACJ;uBA9XsB,cAAc;4BAET,6BAA6B;oCAEK,0BAA0B;4CAP5C,oDAAoD"}
+{"version":3,"file":"TransformAttachmentSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform-attachment/TransformAttachmentSystem.js"],"names":[],"mappings":"AAiMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;;IAEI;;;;OAIG;IACH,mBAAgB;IAEhB;;;;;OAKG;IACH,mBAAoC;IAEpC;;;;OAIG;IACH,gBAAa;IACb,qBAAiB;IACjB,uBAAmB;IAEnB,kEAAkD;IAClD,+HAGE;IAEF;;;;OAIG;IACH,wBAsBC;IAED;;;;OAIG;IACH,kBAEC;IAED;;;;;OAKG;IACH,yBAYC;IAED;;;;;;;;OAQG;IACH,uBALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,iBAJW,mBAAmB,aACnB,WAAW,UACX,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,mBAJW,mBAAmB,aACnB,WAAW,UACX,MAAM,QAkBhB;IAED,6BAoBC;CACJ;uBAvZsB,cAAc;4BAET,6BAA6B;oCAEK,0BAA0B;4CAX5C,oDAAoD"}

package/src/engine/ecs/transform-attachment/TransformAttachmentSystem.js

@@ -2,6 +2,10 @@ import { min2 } from "../../../core/math/min2.js";
 import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { EventType } from "../EventType.js";
+import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_declare } from "../gpu/gpu_authority_declare.js";
+import { gpu_authority_grant } from "../gpu/gpu_authority_grant.js";
+import { gpu_authority_has } from "../gpu/gpu_authority_has.js";
 import { EntityChildIndex } from "../hierarchy/EntityChildIndex.js";
 import { System } from "../System.js";
 import { TRANSFORM64_EVENT_CHANGE } from "../transform/TRANSFORM64_EVENT_CHANGE.js";
@@ -63,6 +67,17 @@ class UpdateContext {
     }
 
     update() {
+        if (gpu_authority_has(this.ecd, this.entity, GPUStateAuthorityFlags.Transform64)) {
+            /*
+             The GPU composes this entity's world from its row and its parent's, and everything
+             below it with it. Nothing is written here and nothing is announced, so the subtree
+             stays as the CPU last composed it — which nothing on the simulation side reads, by the
+             rule that put the bit there: an entity is flagged only when no simulation system
+             reads its world, and what does ask evaluates the chain exactly.
+            */
+            return;
+        }
+
         this.transform.multiplyTransforms(
             this.parent_transform,
             this.attachment.transform
@@ -113,32 +128,27 @@ class UpdateContext {
         this.ecd.removeComponentFromEntity(this.entity, TransformAttachment);
     }
 
-    /** @type {function(*)|null} */
-    #on_parent_changed = null;
-
-    /** @type {function(*)|null} */
-    #on_self_changed = null;
-
     link() {
         // Neither transform carries signals any more, so both announcements come through the
         // dataset, on the channel belonging to the thing that moved. The parent's pose arrives as
         // TRANSFORM64_EVENT_CHANGE on the parent - whether it is a root somebody moved or a link
         // whose own composition just ran; the offset arrives as TRANSFORM_ATTACHMENT_EVENT_CHANGE
         // on this entity, from whoever wrote the attachment.
-        this.#on_parent_changed = () => this.update();
-
-        this.#on_self_changed = () => this.update();
-
+        //
+        // The method itself, with this context as the receiver, rather than a closure per
+        // channel: a model is sixty of these, and a level is hundreds of models.
         this.ecd.addEntityEventListener(
             this.attachment.parent,
             TRANSFORM64_EVENT_CHANGE,
-            this.#on_parent_changed
+            this.update,
+            this
         );
 
         this.ecd.addEntityEventListener(
             this.entity,
             TRANSFORM_ATTACHMENT_EVENT_CHANGE,
-            this.#on_self_changed
+            this.update,
+            this
         );
 
         this.ecd.addEntityEventListener(
@@ -152,27 +162,25 @@ class UpdateContext {
     }
 
     unlink() {
-        this.#linked = false;
-
-        if (this.#on_parent_changed !== null) {
-            this.ecd.removeEntityEventListener(
-                this.attachment.parent,
-                TRANSFORM64_EVENT_CHANGE,
-                this.#on_parent_changed
-            );
-
-            this.#on_parent_changed = null;
+        if (!this.#linked) {
+            return;
         }
 
-        if (this.#on_self_changed !== null) {
-            this.ecd.removeEntityEventListener(
-                this.entity,
-                TRANSFORM_ATTACHMENT_EVENT_CHANGE,
-                this.#on_self_changed
-            );
+        this.#linked = false;
 
-            this.#on_self_changed = null;
-        }
+        this.ecd.removeEntityEventListener(
+            this.attachment.parent,
+            TRANSFORM64_EVENT_CHANGE,
+            this.update,
+            this
+        );
+
+        this.ecd.removeEntityEventListener(
+            this.entity,
+            TRANSFORM_ATTACHMENT_EVENT_CHANGE,
+            this.update,
+            this
+        );
 
         this.ecd.removeEntityEventListener(
             this.attachment.parent,
@@ -208,6 +216,14 @@ class UpdateContext {
  * The index rests on {@link TransformAttachment.parent} being immutable while the component is
  * attached: `link` and `unlink` are then the only transitions a parent reference can undergo.
  *
+ * **What the GPU owns is not composed here.** An entity whose `GPUStateAuthority` gives the GPU its
+ * {@link Transform64} — a joint a clip drives, and everything under it — is skipped: nothing is
+ * written and nothing announced, so its subtree stays as the CPU last composed it. Nothing on the
+ * simulation side reads such an entity, by the rule that puts the bit there; what asks evaluates the
+ * chain exactly (`t64_evaluate_world`). An entity linked under a GPU-composed parent is declared and
+ * flagged at link, and the animation manager hands a subtree back with one announcement, which
+ * recomposes it here from the offsets it seeded.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -249,6 +265,19 @@ export class TransformAttachmentSystem extends System {
      * @private
      */
     __finalize_link(ctx) {
+        const ecd = ctx.ecd;
+
+        if (gpu_authority_has(ecd, ctx.attachment.parent, GPUStateAuthorityFlags.Transform64)) {
+            /*
+             A link under a GPU-composed parent is GPU-composed: there is no current parent pose
+             on this side to compose it against, and its row is composed under the parent's row
+             regardless. Stated on the entity, here, at the one structural moment there is —
+             the animation manager flags the subtree it takes as it takes it, and this is the
+             entity that arrived after.
+            */
+            gpu_authority_declare(ecd, ctx.entity);
+            gpu_authority_grant(ecd, ctx.entity, GPUStateAuthorityFlags.Transform64);
+        }
 
         ctx.link();
 

package/src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometryHighlightSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAiBI;;OAEG;IACH,6CAMC;IAzBD,2DAA2C;IA2B3C,2CAEC;IAED,4CAWC;IAED;;;;OAIG;IACH,gBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAgBhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAYhB;;CACJ;uBA3GsB,2BAA2B;+BAEnB,iCAAiC;sBAD1C,iBAAiB"}
+{"version":3,"file":"ShadedGeometryHighlightSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAiBI;;OAEG;IACH,6CAMC;IAzBD,2DAA2C;IA2B3C,2CAEC;IAED,4CAWC;IAED;;;;OAIG;IACH,gBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAYhB;;CACJ;uBApGsB,2BAA2B;+BAGnB,iCAAiC;sBAF1C,iBAAiB"}

package/src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../../../core/assert.js";
 import { System } from "../../../../ecs/System.js";
 import Highlight from "../Highlight.js";
+import { row_of_entity } from "../../../../../shade/renderer/scene/rows/GPUSceneRows.js";
 import { ShadedGeometry } from "../../mesh-v2/ShadedGeometry.js";
 
 /**
@@ -75,17 +76,9 @@ export class ShadedGeometryHighlightSystem extends System {
      * @param {number} entity
      */
     link(highlight, geometry, entity) {
-        const entry = this.#outline.add_entry(entity, highlight, visitor => {
-            const node = geometry.node;
-
-            if (node === null || node === undefined) {
-                // not in the scene: either `ShadedGeometrySystem` has not linked it yet, or it is
-                // not running at all, and neither is this system's to complain about
-                return;
-            }
-
-            visitor(node);
-        });
+        // the primitive's row is its entity's; a row nothing has written yet is a row no pixel
+        // names, so a primitive the scene has not placed marks nothing
+        const entry = this.#outline.add_entry(entity, highlight, visitor => visitor(row_of_entity(entity)));
 
         this.#entries.set(entity, entry);
     }

package/src/engine/graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sent on an entity whose {@link ShadedGeometry} was changed in place — a material swapped, a
+ * geometry replaced, a flag set — so that the system holding its row rewrites the row.
+ *
+ * A component says nothing when it is written, the same as a `Transform64`; the announcement is
+ * what carries the change. Replacing the component instead — remove, then add a new one — also
+ * works and costs a row: the system detaches the row and attaches a new one, and a skinned
+ * primitive's clone goes back and is taken again with it. Announcing keeps the row, and the clone.
+ *
+ * @see shaded_geometry_announce_change
+ * @type {string}
+ */
+export const SHADED_GEOMETRY_EVENT_CHANGE: string;
+//# sourceMappingURL=SHADED_GEOMETRY_EVENT_CHANGE.d.ts.map

package/src/engine/graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SHADED_GEOMETRY_EVENT_CHANGE.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,2CAFU,MAAM,CAEsD"}

package/src/engine/graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.js

@@ -0,0 +1,13 @@
+/**
+ * Sent on an entity whose {@link ShadedGeometry} was changed in place — a material swapped, a
+ * geometry replaced, a flag set — so that the system holding its row rewrites the row.
+ *
+ * A component says nothing when it is written, the same as a `Transform64`; the announcement is
+ * what carries the change. Replacing the component instead — remove, then add a new one — also
+ * works and costs a row: the system detaches the row and attaches a new one, and a skinned
+ * primitive's clone goes back and is taken again with it. Announcing keeps the row, and the clone.
+ *
+ * @see shaded_geometry_announce_change
+ * @type {string}
+ */
+export const SHADED_GEOMETRY_EVENT_CHANGE = "@shaded-geometry/change";

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.d.ts

@@ -40,18 +40,6 @@ export class ShadedGeometry {
      * @private
      */
     private __c_transform;
-    /**
-     * The row a renderer put this primitive in, or `null` while it is in none.
-     *
-     * **Written by whichever system placed it, and read by whoever needs to know where it ended
-     * up** — `MeshSystem` combining the bounds of an expanded model, for one. Same arrangement v1
-     * made with `Mesh.mesh`: a component that carries the renderer's own geometry may as well carry
-     * the renderer's own handle to it, and one renderer runs at a time.
-     *
-     * @transient
-     * @type {Mesh|null}
-     */
-    node: Mesh | null;
     /**
      *
      * @type {DrawMode|number}
@@ -168,8 +156,8 @@ export class ShadedGeometry {
      * Raycast this primitive's own triangles on the CPU.
      *
      * **Requires a {@link Geometry}** — the vertex arrays themselves. A `MeshletGeometry` keeps its
-     * triangles quantized inside meshlet pages, so a `ShadedGeometry` placed by
-     * `shade_node_to_entity_composition` cannot be asked this; `geometry_build_from_meshlet_geometry`
+     * triangles quantized inside meshlet pages, so a `ShadedGeometry` a prefab spawned cannot be
+     * asked this; `geometry_build_from_meshlet_geometry`
      * decodes one, and holding that decode is the caller's business rather than this method's.
      * Picking a whole scene goes through the renderer's own `pick` instead (I-9) — this answers with
      * a surface point on one primitive.

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"],"names":[],"mappings":"AAwCA;;;GAGG;AACH;IAmRI;;;;;;OAMG;IACH,sBALW,gCAA8B,YAC9B,wBAAsB,cACtB,QAAQ,GACP,cAAc,CAQzB;IA/QD;;;;OAIG;IACH,UAFU,8CAAwC,IAAI,CAEtC;IAEhB;;;OAGG;IACH,UAFU,2BAAuB,IAAI,CAErB;IAEhB;;;OAGG;IACH,gBAFU,2BAAuB,IAAI,CAEf;IAEtB,sBAA6B;IAE7B;;;;OAIG;IACH,iBAAc;IAEd;;;;OAIG;IACH,sBAAqB;IAErB;;;;;;;;;;OAUG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;;OAGG;IACH,MAFU,QAAQ,GAAC,MAAM,CAEC;IAE1B;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,SAC1B,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,OAAO,CAInB;IAED;;;OAGG;IACH,QAFY,MAAM,CASjB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAUnB;IAED;;;OAGG;IACH,YAFW,cAAc,QASxB;IAED;;;OAGG;IACH,SAFa,cAAc,CAQ1B;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;OAKG;IACH,6CAFa,IAAI,CAMhB;IAED;;;;;OAKG;IACH,qBAFa,IAAI,CAKhB;IAED;;;;;;OAMG;IACH,6BAFa,OAAO,CAcnB;IAED;;;OAGG;IACH,4BAFW,KAAK,QAsBf;IAED;;;;;OAKG;IACH,eAJW,gCAA8B,YAC9B,wBAAsB,cACtB,QAAQ,QAMlB;IAiBD;;;;OAIG;IACH,mBAFa,IAAI,CAgBhB;IAED,sBAeC;IAED;;;;;;;;;;;;;;OAcG;IACH,mDAJW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,qBACvC,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GACrC,OAAO,CA4BnB;;CACJ;;kBAIS,MAAM;sBAON,OAAO;;0BAtaS,yCAAyC;yBAK1C,eAAe;oCACJ,0BAA0B;sBALxC,wCAAwC"}
+{"version":3,"file":"ShadedGeometry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"],"names":[],"mappings":"AAwCA;;;GAGG;AACH;IAyQI;;;;;;OAMG;IACH,sBALW,gCAA8B,YAC9B,wBAAsB,cACtB,QAAQ,GACP,cAAc,CAQzB;IArQD;;;;OAIG;IACH,UAFU,8CAAwC,IAAI,CAEtC;IAEhB;;;OAGG;IACH,UAFU,2BAAuB,IAAI,CAErB;IAEhB;;;OAGG;IACH,gBAFU,2BAAuB,IAAI,CAEf;IAEtB,sBAA6B;IAE7B;;;;OAIG;IACH,iBAAc;IAEd;;;;OAIG;IACH,sBAAqB;IAErB;;;OAGG;IACH,MAFU,QAAQ,GAAC,MAAM,CAEC;IAE1B;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,GACxB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,mBAAmB,SAC1B,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,mBAAmB,GACxB,OAAO,CAInB;IAED;;;OAGG;IACH,QAFY,MAAM,CASjB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAUnB;IAED;;;OAGG;IACH,YAFW,cAAc,QASxB;IAED;;;OAGG;IACH,SAFa,cAAc,CAQ1B;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;OAKG;IACH,6CAFa,IAAI,CAMhB;IAED;;;;;OAKG;IACH,qBAFa,IAAI,CAKhB;IAED;;;;;;OAMG;IACH,6BAFa,OAAO,CAcnB;IAED;;;OAGG;IACH,4BAFW,KAAK,QAyBf;IAED;;;;;OAKG;IACH,eAJW,gCAA8B,YAC9B,wBAAsB,cACtB,QAAQ,QAMlB;IAiBD;;;;OAIG;IACH,mBAFa,IAAI,CAgBhB;IAED,sBAeC;IAED;;;;;;;;;;;;;;OAcG;IACH,mDAJW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,qBACvC,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GACrC,OAAO,CA4BnB;;CACJ;;kBAIS,MAAM;sBAON,OAAO;;0BA5ZS,yCAAyC;yBAK1C,eAAe;oCACJ,0BAA0B;sBALxC,wCAAwC"}

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js

@@ -94,19 +94,6 @@ export class ShadedGeometry {
      */
     __c_transform = null;
 
-    /**
-     * The row a renderer put this primitive in, or `null` while it is in none.
-     *
-     * **Written by whichever system placed it, and read by whoever needs to know where it ended
-     * up** — `MeshSystem` combining the bounds of an expanded model, for one. Same arrangement v1
-     * made with `Mesh.mesh`: a component that carries the renderer's own geometry may as well carry
-     * the renderer's own handle to it, and one renderer runs at a time.
-     *
-     * @transient
-     * @type {Mesh|null}
-     */
-    node = null;
-
     /**
      *
      * @type {DrawMode|number}
@@ -284,15 +271,18 @@ export class ShadedGeometry {
      * @param {AABB3} destination
      */
     getBoundingBox(destination) {
-        const node = this.node;
+        const geometry = this.geometry;
 
-        if (node !== null) {
+        if (geometry !== null && geometry.isMeshletGeometry === true) {
             /*
-             Placed in a renderer that keeps a world box per row and refreshes it as part of placing
-             it. Reading that is not an optimization — the deferred path below computes its box from
-             the geometry's own, and only a three `BufferGeometry` has one of those.
+             A meshlet geometry carries its box from the build, and the entity's own transform is
+             its world — the ECS composes every chain on the CPU. The box the renderer draws by is
+             derived on the GPU from the same two and is not read back here: this answers where the
+             primitive is under what the simulation knows, which is what a pick or a framing wants.
             */
-            destination.readFromArray(node.bounding_box);
+            aabb3_matrix4_project(scratch_aabb3_array, geometry.bounding_box, this.transform);
+
+            destination.readFromArray(scratch_aabb3_array);
 
             return;
         }
@@ -374,8 +364,8 @@ export class ShadedGeometry {
      * Raycast this primitive's own triangles on the CPU.
      *
      * **Requires a {@link Geometry}** — the vertex arrays themselves. A `MeshletGeometry` keeps its
-     * triangles quantized inside meshlet pages, so a `ShadedGeometry` placed by
-     * `shade_node_to_entity_composition` cannot be asked this; `geometry_build_from_meshlet_geometry`
+     * triangles quantized inside meshlet pages, so a `ShadedGeometry` a prefab spawned cannot be
+     * asked this; `geometry_build_from_meshlet_geometry`
      * decodes one, and holding that decode is the caller's business rather than this method's.
      * Picking a whole scene goes through the renderer's own `pick` instead (I-9) — this answers with
      * a surface point on one primitive.

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.d.ts

@@ -6,5 +6,6 @@ export namespace ShadedGeometryFlags {
     let DrawMethodLocked: number;
     let Visible: number;
     let DeferredBoundsUpdate: number;
+    let Skinned: number;
 }
 //# sourceMappingURL=ShadedGeometryFlags.d.ts.map

package/src/engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js

@@ -42,4 +42,11 @@ export const ShadedGeometryFlags = {
      * @see ShadedGeometryDeferredBounds.bench.spec.js
      */
     DeferredBoundsUpdate: 32,
+
+    /**
+     * The geometry is deformed by a skin the entity's model registers. The renderer draws a
+     * per-instance clone of it, written by the skinning pass, rather than the shared source.
+     * Set by the prefab that spawned the primitive; a primitive built by hand is rigid.
+     */
+    Skinned: 64,
 };