@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/scene/NODE3D_STRUCT.d.ts

@@ -21,11 +21,11 @@ export const NODE3D_STRUCT: WebGPUStruct;
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *
- * The scene's transform record sits at index 0 — set up once during
- * {@link GPUSceneContext.build} from `scene.transform_local`. Any node
- * whose CPU-side `parent` is null (i.e. a top-level node) gets a GPU
- * `parent` field of `NODE3D_SCENE_ID`, so it inherits the scene's
- * world transform.
+ * The root's record sits at index 0 — identity, written once by
+ * `GPUSceneContext.build`, its first. An entity whose attachment names
+ * no entity with a row gets a GPU `parent` field of `NODE3D_SCENE_ID`
+ * and carries its world pose as its local one, so the composition is
+ * exact.
  *
  * The transform-hierarchy pass also treats `parent == NODE3D_SCENE_ID`
  * as the walk termination condition. That makes 0 — the natural value

package/src/shade/renderer/scene/NODE3D_STRUCT.js

@@ -69,11 +69,11 @@ export const NODE3D_STRUCT = WebGPUStruct.from({
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *
- * The scene's transform record sits at index 0 — set up once during
- * {@link GPUSceneContext.build} from `scene.transform_local`. Any node
- * whose CPU-side `parent` is null (i.e. a top-level node) gets a GPU
- * `parent` field of `NODE3D_SCENE_ID`, so it inherits the scene's
- * world transform.
+ * The root's record sits at index 0 — identity, written once by
+ * `GPUSceneContext.build`, its first. An entity whose attachment names
+ * no entity with a row gets a GPU `parent` field of `NODE3D_SCENE_ID`
+ * and carries its world pose as its local one, so the composition is
+ * exact.
  *
  * The transform-hierarchy pass also treats `parent == NODE3D_SCENE_ID`
  * as the walk termination condition. That makes 0 — the natural value

package/src/shade/renderer/scene/Node3D.d.ts

@@ -5,11 +5,9 @@
 export class Node3D {
     /**
      * Stable numeric id, unique across every Node3D instance (meshes,
-     * lights, scenes, anchors). Used as the key in
-     * `GPUSceneContext.id_mapping` to look up the node's row in the
-     * GPU `transforms` table — the binding survives table compaction
-     * or rebuild because it's tied to the JS object's identity, not
-     * its position in any array.
+     * lights, scenes, anchors) — tied to the JS object's identity, not
+     * its position in any array. A node in a scene is bound to its rows
+     * through the object itself (`GPUSceneContext.node_rows`).
      *
      * @type {number}
      * @readonly
@@ -37,13 +35,34 @@ export class Node3D {
      * @param {boolean} v
      */
     set needsUpdate(v: boolean);
+    /**
+     * Where this node reports that it has moved — set by the {@link GPUSceneContext} that gives it
+     * rows, cleared when it takes them back. Null for a node no context holds, which is every node
+     * before it is added to a scene and every node after it leaves one.
+     *
+     * A node reports to one list, not several. Two contexts holding the same node would need two,
+     * and nothing in the engine does that: a `SceneManager` keeps one context per scene, and
+     * {@link GPUSceneContext} asserts when a node arrives already reporting somewhere else rather
+     * than quietly taking the claim and leaving the other context deaf.
+     *
+     * @type {Node3DDirtyList|null}
+     */
+    transform_dirty_list: Node3DDirtyList | null;
+    /**
+     * Handing a row back to the CPU has to be *reported*, not waited for: while the GPU owned the
+     * row nothing bumped this node's version, so nothing else would ever mark it as needing a
+     * write and the CPU would go on not writing a row it now owns.
+     *
+     * @param {TransformAuthority} value
+     */
+    set transform_authority(value: number);
     /**
      * Who writes this node's TRS in the GPU `transforms` table. Declared, never inferred — see
      * {@link TransformAuthority} for what each side owns and why guessing does not work.
      *
-     * @type {TransformAuthority}
+     * @returns {TransformAuthority}
      */
-    transform_authority: TransformAuthority;
+    get transform_authority(): number;
     /**
      * World transform, **derived** — {@link updateMatrices} recomputes it from
      * {@link transform_local} and the parent chain, so writing it directly is undone the moment
@@ -134,7 +153,7 @@ export class Node3D {
     readonly isNode3D: boolean;
     #private;
 }
-import { TransformAuthority } from "./TransformAuthority.js";
+export type Node3DDirtyList = import("./Node3DDirtyList.js").Node3DDirtyList;
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 //# sourceMappingURL=Node3D.d.ts.map

package/src/shade/renderer/scene/Node3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Node3D.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Node3D.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IAEI;;;;;;;;;;OAUG;IACH,aAHU,MAAM,CAGE;IAElB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAOT;;;;;;;;;;;OAWG;IACH,sBAEC;IAED;;OAEG;IACH,4BAIC;IAED;;;;;OAKG;IACH,qBAFU,kBAAkB,CAEiB;IAE7C;;;;;;OAMG;IACH,kBAFU,WAAW,CAEgB;IAErC;;;;;OAKG;IACH,iBAFU,WAAW,CAEe;IAEpC,YAAc;IAEd;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEL;IAYb;;;;;;OAMG;IACH,wBAMC;IAvBD;;;;;OAKG;IACH,uBAEC;IAiBD;;;;;OAKG;IACH,qBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED,uBAKC;IAED,gBAmBC;IAED;;;;OAIG;IACH,0BAHoB,MAAM,+BASzB;IAED;;;;;;OAMG;IACH,uBA0BC;IAED;;;OAGG;IACH,sBAFW,MAAM,EAAE,QAOlB;IAED;;;OAGG;IACH,gBAFW,MAAM,QAchB;IAIL;;;;;;OAMG;IACH,mBAFU,OAAO,CAEQ;;CATxB;mCAzPkC,yBAAyB;4BADhC,8CAA8C;oBAHtD,+BAA+B"}
+{"version":3,"file":"Node3D.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Node3D.js"],"names":[],"mappings":"AAYA;;;GAGG;AACH;IAEI;;;;;;;;OAQG;IACH,aAHU,MAAM,CAGE;IAElB;;;OAGG;IACH,MAFU,MAAM,CAEP;IAOT;;;;;;;;;;;OAWG;IACH,sBAEC;IAED;;OAEG;IACH,4BAMC;IAED;;;;;;;;;;;OAWG;IACH,sBAFU,eAAe,GAAC,IAAI,CAEF;IA6C5B;;;;;;OAMG;IACH,uCAQC;IAzBD;;;;;OAKG;IACH,kCAEC;IAmBD;;;;;;OAMG;IACH,kBAFU,WAAW,CAEgB;IAErC;;;;;OAKG;IACH,iBAFU,WAAW,CAEe;IAEpC,YAAc;IAEd;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEL;IAYb;;;;;;OAMG;IACH,wBAMC;IAvBD;;;;;OAKG;IACH,uBAEC;IAiBD;;;;;OAKG;IACH,qBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED,uBAOC;IAED,gBAmBC;IAED;;;;OAIG;IACH,0BAHoB,MAAM,+BASzB;IAED;;;;;;OAMG;IACH,uBA4BC;IAED;;;OAGG;IACH,sBAFW,MAAM,EAAE,QAOlB;IAED;;;OAGG;IACH,gBAFW,MAAM,QAchB;IAIL;;;;;;OAMG;IACH,mBAFU,OAAO,CAEQ;;CATxB;8BAhUY,OAAO,sBAAsB,EAAE,eAAe;4BAJ/B,8CAA8C;oBAHtD,+BAA+B"}

package/src/shade/renderer/scene/Node3DDirtyList.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {import("./Node3D.js").Node3D} Node3D
+ */
+/**
+ * Nodes whose transform has been touched since the last drain — how a {@link GPUSceneContext}
+ * finds out what moved, instead of asking every node it holds.
+ *
+ * A scene-wide scan is proportional to the scene and not to the frame: a version comparison is
+ * cheap, several tens of thousands of them are not, and the scan runs once per view. Movement is
+ * reported at the one place it happens — {@link Node3D.updateMatrices}, and the two other things
+ * that bump a node's version — so the list is what actually changed and the frame costs what it
+ * moved.
+ *
+ * {@link generation} is the drain counter, and a node stamps itself with it when it joins. That is
+ * what makes a repeat within one frame free: `updateMatrices` recurses into children, so a
+ * character's root moving reaches every joint under it, and reaching a joint twice — through the
+ * recursion and again through a call of its own — must not queue it twice.
+ *
+ * A node on the list is a node that *may* have moved, never a promise that it did. The consumer
+ * still compares versions: the membership sweep writes an arriving node's row itself, and that
+ * node is on the list as well.
+ */
+export class Node3DDirtyList {
+    /**
+     * Bumped by {@link drain}. A node carries the value it last joined under; see the class note.
+     *
+     * @type {number}
+     */
+    generation: number;
+    /**
+     * @param {Node3D} node
+     */
+    add(node: Node3D): void;
+    /**
+     * How many nodes are waiting. For a spec, and for anything that wants to know whether a frame
+     * has anything to do before it starts doing it.
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Hand over everything queued and start a fresh batch.
+     *
+     * The returned array is valid until the next drain, which is also when it is recycled — so a
+     * caller reads it and lets go of it. Anything queued *while* it is being read lands in the new
+     * batch rather than being appended to the one under the reader's feet.
+     *
+     * @returns {Node3D[]}
+     */
+    drain(): Node3D[];
+    /**
+     * Forget everything queued without handing it anywhere. For a context being torn down, whose
+     * nodes may outlive it.
+     */
+    clear(): void;
+    #private;
+}
+export type Node3D = import("./Node3D.js").Node3D;
+//# sourceMappingURL=Node3DDirtyList.d.ts.map

package/src/shade/renderer/scene/Node3DDirtyList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Node3DDirtyList.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Node3DDirtyList.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;;OAIG;IACH,YAFU,MAAM,CAED;IAef;;OAEG;IACH,UAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAEC;IAED;;;;;;;;OAQG;IACH,SAFa,MAAM,EAAE,CAapB;IAED;;;OAGG;IACH,cAKC;;CACJ;qBA7FY,OAAO,aAAa,EAAE,MAAM"}

package/src/shade/renderer/scene/Scene.d.ts

@@ -1,35 +1,27 @@
 /**
- * Scene root. Acts as the implicit parent of every top-level node in
- * the GPU scene-graph: `GPUSceneContext.build` allocates row 0 of the
- * `transforms` table to the scene and sets every orphan node's GPU
- * `parent` field to {@link NODE3D_SCENE_ID} (= 0). The scene's own
- * `transform_local` defaults to identity, but the user can pose it
- * (e.g. world-shift the whole hierarchy) just like any other Node3D.
+ * @typedef {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+/**
+ * A scene: the dataset whose entities are what it draws and poses, and the three things that are
+ * not entities — its lights' collection, a light probe volume, volumetrics.
  *
- * Inheriting from {@link Node3D} keeps the CPU and GPU views aligned —
- * the scene has the same TRS-backed transform shape as every other
- * node, and animation tracks targeting node id 0 work without any
- * special case.
+ * Everything drawn is an entity of {@link dataset} holding a row of the scene's GPU database
+ * (`GPUSceneContext.rows`), at `entity + 1`. A game's systems take rows as components appear; a
+ * scene with no systems places a model with `prefab_place`, a primitive with `place_primitive`
+ * and a light with `place_light`. Nothing is added to the scene itself.
  */
-export class Scene extends Node3D {
-    instances: InstanceBatch;
-    /**
-     * Number of *renderable* mesh instances. Drives the rasterization
-     * pipeline's per-mesh dispatches.
-     *
-     * @return {number}
-     */
-    get instance_count(): number;
+export class Scene {
     /**
-     * Total GPU node-record count — meshes plus any non-mesh
-     * {@link Node3D}s in the batch (anchors, attachment points,
-     * future skeleton joints), *plus the scene itself* at row 0. Drives
-     * the GPU scene-graph propagation pass's iteration range.
+     * The dataset whose entities are this scene's rows. A scene is bound to one dataset; whoever
+     * owns both names it here, before anything asks the scene's GPU context for its rows. Null
+     * for a scene that draws nothing.
      *
-     * @return {number}
+     * @type {EntityComponentDataset|null}
      */
-    get node_count(): number;
+    dataset: EntityComponentDataset | null;
     /**
+     * Each light at an entity of {@link dataset} — `lights.add(light, entity)`, or `place_light`
+     * for a caller with no entity of its own.
      *
      * @type {LightCollection}
      */
@@ -44,47 +36,13 @@ export class Scene extends Node3D {
      * @type {SceneVolumetrics}
      */
     volumetrics: SceneVolumetrics;
-    hash(): number;
-    /**
-     *
-     * @param {Scene} other
-     */
-    equals(other: Scene): boolean;
-    /**
-     * Add a `Node3D` (or any of its subclasses — `Mesh`, `Light`, …) to
-     * the scene. Children of the node are traversed and added too. Pass
-     * an array to add several nodes at once.
-     *
-     * Routing rule:
-     *  - {@link isLight}-tagged nodes go to {@link lights} (their own
-     *    GPU pipeline) and are *not* tracked by the instance batch.
-     *  - Everything else — meshes, anchors, future skeleton joints —
-     *    goes into {@link instances}, the InstanceBatch. Meshes also
-     *    surface in `instances.instances` (the rendered subset);
-     *    non-mesh nodes are visible only as part of `instances.nodes`,
-     *    which is what the GPU scene-graph propagation pass iterates.
-     *
-     * @param {Node3D|Node3D[]} node
-     */
-    add(node: Node3D | Node3D[]): void;
-    /**
-     * Take a node back out, along with everything {@link add} brought in with it.
-     *
-     * Routing mirrors {@link add} exactly: lights leave {@link lights}, everything else leaves
-     * {@link instances}. A node is only ever in one of them, so the two are not both consulted.
-     *
-     * @param {Node3D|Node3D[]} node
-     * @returns {boolean} true if the node itself was found and dropped
-     */
-    remove(node: Node3D | Node3D[]): boolean;
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isScene: boolean;
 }
-import { Node3D } from "./Node3D.js";
-import { InstanceBatch } from "./InstanceBatch.js";
+export type EntityComponentDataset = import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset;
 import { LightCollection } from "../light/LightCollection.js";
 import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
 import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";

package/src/shade/renderer/scene/Scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Scene.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;IACI,yBAAgC;IAEhC;;;;;OAKG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,yBAEC;IAED;;;OAGG;IACH,QAFU,eAAe,CAEM;IAE/B;;;OAGG;IACH,oBAFU,gBAAgB,CAEkB;IAE5C;;;OAGG;IACH,aAFU,gBAAgB,CAEW;IAErC,eAEC;IAED;;;OAGG;IACH,cAFW,KAAK,WAIf;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAFW,MAAM,GAAC,MAAM,EAAE,QAkBzB;IAED;;;;;;;;OAQG;IACH,aAHW,MAAM,GAAC,MAAM,EAAE,GACb,OAAO,CAuBnB;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;uBAvIsB,aAAa;8BADN,oBAAoB;gCAFlB,6BAA6B;iCAD5B,gDAAgD;iCAEhD,oCAAoC"}
+{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Scene.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;;;;;GAQG;AACH;IACI;;;;;;OAMG;IACH,SAFU,sBAAsB,GAAC,IAAI,CAEtB;IAEf;;;;;OAKG;IACH,QAFU,eAAe,CAEM;IAE/B;;;OAGG;IACH,oBAFU,gBAAgB,CAEkB;IAE5C;;;OAGG;IACH,aAFU,gBAAgB,CAEW;IAGzC;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;qCAzCY,OAAO,+CAA+C,EAAE,sBAAsB;gCAJ3D,6BAA6B;iCAD5B,gDAAgD;iCAEhD,oCAAoC"}

package/src/shade/renderer/scene/Scene.js

@@ -1,146 +1,53 @@
-import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
-import { LightCollection } from "../light/LightCollection.js";
-import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";
-import { InstanceBatch } from "./InstanceBatch.js";
-import { Node3D } from "./Node3D.js";
-
-/**
- * Scene root. Acts as the implicit parent of every top-level node in
- * the GPU scene-graph: `GPUSceneContext.build` allocates row 0 of the
- * `transforms` table to the scene and sets every orphan node's GPU
- * `parent` field to {@link NODE3D_SCENE_ID} (= 0). The scene's own
- * `transform_local` defaults to identity, but the user can pose it
- * (e.g. world-shift the whole hierarchy) just like any other Node3D.
- *
- * Inheriting from {@link Node3D} keeps the CPU and GPU views aligned —
- * the scene has the same TRS-backed transform shape as every other
- * node, and animation tracks targeting node id 0 work without any
- * special case.
- */
-export class Scene extends Node3D {
-    instances = new InstanceBatch();
-
-    /**
-     * Number of *renderable* mesh instances. Drives the rasterization
-     * pipeline's per-mesh dispatches.
-     *
-     * @return {number}
-     */
-    get instance_count() {
-        return this.instances.instances.length;
-    }
-
-    /**
-     * Total GPU node-record count — meshes plus any non-mesh
-     * {@link Node3D}s in the batch (anchors, attachment points,
-     * future skeleton joints), *plus the scene itself* at row 0. Drives
-     * the GPU scene-graph propagation pass's iteration range.
-     *
-     * @return {number}
-     */
-    get node_count() {
-        return this.instances.nodes.length + 1;
-    }
-
-    /**
-     *
-     * @type {LightCollection}
-     */
-    lights = new LightCollection();
-
-    /**
-     *
-     * @type {LightProbeVolume}
-     */
-    light_probe_volume = new LightProbeVolume();
-
-    /**
-     *
-     * @type {SceneVolumetrics}
-     */
-    volumetrics = new SceneVolumetrics();
-
-    hash() {
-        return 0;
-    }
-
-    /**
-     *
-     * @param {Scene} other
-     */
-    equals(other) {
-        return this.instances.equals(other.instances);
-    }
-
-    /**
-     * Add a `Node3D` (or any of its subclasses — `Mesh`, `Light`, …) to
-     * the scene. Children of the node are traversed and added too. Pass
-     * an array to add several nodes at once.
-     *
-     * Routing rule:
-     *  - {@link isLight}-tagged nodes go to {@link lights} (their own
-     *    GPU pipeline) and are *not* tracked by the instance batch.
-     *  - Everything else — meshes, anchors, future skeleton joints —
-     *    goes into {@link instances}, the InstanceBatch. Meshes also
-     *    surface in `instances.instances` (the rendered subset);
-     *    non-mesh nodes are visible only as part of `instances.nodes`,
-     *    which is what the GPU scene-graph propagation pass iterates.
-     *
-     * @param {Node3D|Node3D[]} node
-     */
-    add(node) {
-        if (Array.isArray(node)) {
-            for (const n of node) this.add(n);
-            return;
-        }
-
-        if (node.isLight === true) {
-            this.lights.add(node);
-        } else {
-            this.instances.add(node);
-        }
-
-        const children = node.children;
-        for (let i = 0; i < children.length; i++) {
-            this.add(children[i]);
-        }
-    }
-
-    /**
-     * Take a node back out, along with everything {@link add} brought in with it.
-     *
-     * Routing mirrors {@link add} exactly: lights leave {@link lights}, everything else leaves
-     * {@link instances}. A node is only ever in one of them, so the two are not both consulted.
-     *
-     * @param {Node3D|Node3D[]} node
-     * @returns {boolean} true if the node itself was found and dropped
-     */
-    remove(node) {
-        if (Array.isArray(node)) {
-            let any = false;
-
-            for (const n of node) {
-                any = this.remove(n) || any;
-            }
-
-            return any;
-        }
-
-        const removed = node.isLight === true
-            ? this.lights.remove(node)
-            : this.instances.remove(node);
-
-        const children = node.children;
-        for (let i = 0; i < children.length; i++) {
-            this.remove(children[i]);
-        }
-
-        return removed;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-Scene.prototype.isScene = true;
+import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
+import { LightCollection } from "../light/LightCollection.js";
+import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";
+
+/**
+ * @typedef {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+
+/**
+ * A scene: the dataset whose entities are what it draws and poses, and the three things that are
+ * not entities — its lights' collection, a light probe volume, volumetrics.
+ *
+ * Everything drawn is an entity of {@link dataset} holding a row of the scene's GPU database
+ * (`GPUSceneContext.rows`), at `entity + 1`. A game's systems take rows as components appear; a
+ * scene with no systems places a model with `prefab_place`, a primitive with `place_primitive`
+ * and a light with `place_light`. Nothing is added to the scene itself.
+ */
+export class Scene {
+    /**
+     * The dataset whose entities are this scene's rows. A scene is bound to one dataset; whoever
+     * owns both names it here, before anything asks the scene's GPU context for its rows. Null
+     * for a scene that draws nothing.
+     *
+     * @type {EntityComponentDataset|null}
+     */
+    dataset = null;
+
+    /**
+     * Each light at an entity of {@link dataset} — `lights.add(light, entity)`, or `place_light`
+     * for a caller with no entity of its own.
+     *
+     * @type {LightCollection}
+     */
+    lights = new LightCollection();
+
+    /**
+     *
+     * @type {LightProbeVolume}
+     */
+    light_probe_volume = new LightProbeVolume();
+
+    /**
+     *
+     * @type {SceneVolumetrics}
+     */
+    volumetrics = new SceneVolumetrics();
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Scene.prototype.isScene = true;

package/src/shade/renderer/scene/SkinnedMesh.d.ts

@@ -1,110 +1,27 @@
 /**
- * @typedef {import("../animation/Skin.js").Skin} Skin
- */
-/**
- * A mesh whose vertices are deformed each frame by joint transforms.
- *
- * On the CPU side, a `SkinnedMesh` is just a {@link Mesh} that points at
- * the *unmodified* source {@link MeshletGeometry} — the same way every
- * other instance of that mesh would. Multiple `SkinnedMesh` instances
- * share the source geometry; no per-instance CPU clones happen.
- *
- * The GPU side makes the deformation possible by allocating a
- * per-instance vertex/metadata clone of the source geometry inside the
- * existing meshlet buffers (see
- * {@link GPUMeshletManager#clone_batch_allocation}). The clone is
- * registered as a separate geometry id (see
- * {@link GPUGeometryManager#add_clone}); the instance record this mesh
- * produces points at the clone, not at the source. Rasterization then
- * sees the clone like any other geometry.
- *
- * Per-frame, a skinning compute pass reads the source's vertex data and
- * the joint matrices and writes the deformed result into the clone's
- * vertex region — leaving every other instance pointed at the source
- * untouched. The skin matrices are computed per the glTF spec formula
- * `inverse(meshNode.worldMatrix) × jointNode.worldMatrix ×
- * inverseBindMatrix`, and the rasterizer re-applies
- * `mesh.transform_global` to the result — so the mesh node's own
- * transform cancels out of the rendered position exactly, which is what
- * the glTF spec asks for. The leftmost factor is taken live from the
- * mesh's own transforms row inside {@link shader_meshlet_apply_skinning};
- * see {@link chunk_skin_blend_mesh_local} for why it goes into each
- * matrix rather than onto the blended position.
+ * A loader's mark on a primitive that a skin deforms.
  *
- * **`transform_global` on a skinned mesh is the engine's, not the
- * asset's.** It cancels out of the rendered position, so glTF declares
- * it meaningless — and the one meaning it does have is the frame the
- * clone's vertices are written in, which the fold above requires to be
- * rigid against the skin. {@link GPUAnimationManager#register_skin}
- * therefore overwrites it, by way of
- * {@link skin_normalize_mesh_frame}, with the skin's own bind
- * transform. Whatever the file put there is discarded, and anything
- * reading this expecting the file's value is reading the wrong thing.
- * See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ * **A tag, not a renderable.** A skinned model is placed as a prefab — `prefab_compile` reads
+ * this class off the loader's tree to know which primitives deform against which skin, and
+ * `prefab_instantiate` spawns each as an entity whose mesh row draws a per-instance clone the
+ * skinning pass writes (`ShadedGeometryFlags.Skinned`). Adding one of these to a scene as a node
+ * is refused by the scene database: a node draws its source geometry rigidly, and there is no
+ * node-side skinning any more.
  *
- * The mesh's **skin id** — a row in a GPU table — lives in
- * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
- * {@link Skin} it was registered with is a different thing, pure data
- * that knows nothing about the GPU, and this mesh holds a reference to
- * it in {@link skin} so its bounds can be worked out without asking the
- * GPU anything. Bind the mesh to a skin via
- * `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
- * {@link GPUAnimationManager#register_skin} to do it for every entry
- * in `Skin.meshes` — which is also what populates {@link skin}. Until
- * bound, the clone routes through the rendering path but its vertices
- * stay at the source's bind-pose values — useful as an intermediate
- * verification state, and the state in which this mesh bounds itself
- * exactly like a regular {@link Mesh}.
- *
- * A note on which bounds to believe. {@link Mesh#bounding_box} here is
- * derived from whatever pose the *CPU* can see, and for a character
- * animated by the pose accumulator that is the rest pose — the joints
- * are {@link TransformAuthority.GPU} and their `transform_global` is
- * never advanced. It is the right size and in the right place, and it
- * is what seeds the scene database's `meshes` row. The deformed world
- * box, refreshed every frame from the vertices the skinning pass just
- * moved, is that row — read it from there when the silhouette is what
- * matters.
+ * What the class still says: the geometry, the material, and that this primitive's vertices are
+ * placed by joints rather than by its own transform — which is why glTF declares the node's own
+ * transform meaningless for it, and why the prefab moves the node onto the skin's bind frame.
  */
 export class SkinnedMesh extends Mesh {
-    /**
-     * The skin whose formula places this mesh's vertices, or `null` while none does.
-     *
-     * Not "is the deformation running" — {@link GPUMeshSkinningContext#unbind} can stop the
-     * skinning pass without this changing, and a mesh whose pass has stopped still holds vertices
-     * the skin put there. So {@link GPUAnimationManager#register_skin} writes it and nothing
-     * clears it: once a skin has taken a mesh over, its formula stays the right basis for
-     * {@link updateBoundsBasic} whether or not a pass runs this frame. Clear it by hand to hand
-     * the mesh back to {@link Mesh}'s composition.
-     *
-     * CPU data throughout (see {@link Skin}). The GPU-side skin *id* is a table row and lives in
-     * {@link GPUMeshSkinningContext}; this does not expose it.
-     *
-     * Nothing refreshes derived state on assignment — set this and the bounds go on describing
-     * the previous basis until {@link updateMatrices} or {@link updateBoundsBasic} runs.
-     *
-     * A clone shares the reference, exactly as {@link Skin#copy} shares its joint and mesh
-     * references: retargeting a cloned character means replacing this alongside the skin's own
-     * arrays, which {@link instantiate_scene_bundle} gets for free by re-registering the
-     * corresponded skin.
-     *
-     * @type {Skin|null}
-     */
-    skin: Skin | null;
     /**
      * @returns {SkinnedMesh}
      */
     clone(): SkinnedMesh;
-    /**
-     * @param {SkinnedMesh} other
-     */
-    copy(other: SkinnedMesh): void;
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isSkinnedMesh: boolean;
 }
-export type Skin = import("../animation/Skin.js").Skin;
 import { Mesh } from "./Mesh.js";
 //# sourceMappingURL=SkinnedMesh.d.ts.map

package/src/shade/renderer/scene/SkinnedMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,IAAI,GAAC,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;mBA/JY,OAAO,sBAAsB,EAAE,IAAI;qBAH3B,WAAW"}
+{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH;IAEI;;OAEG;IACH,SAFa,WAAW,CAMvB;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBA1BoB,WAAW"}