@woosh/meep-engine 3.27.0 → 3.29.0

package/src/engine/graphics3/prefab/prefab_instantiate.js

@@ -1,230 +1,230 @@
-import { assert } from "../../../core/assert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { ShadeAnimationChannel } from "../../../shade/renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../../../shade/renderer/animation/ShadeAnimationClip.js";
-import { Skin } from "../../../shade/renderer/animation/Skin.js";
-import { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
-import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
-import { Name } from "../../ecs/name/Name.js";
-import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
-import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
-import { Transform64 } from "../../ecs/transform/Transform64.js";
-import { DrawMode } from "../../graphics/ecs/mesh-v2/DrawMode.js";
-import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
-import { PrefabInstance } from "./PrefabInstance.js";
-
-/**
- * @typedef {import("./Prefab.js").Prefab} Prefab
- * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
- */
-
-/**
- * Every component type an instance may attach. Registered once per dataset, before the first
- * entity is built, because registering a type rebuilds the dataset's occupancy and a spawn of
- * thousands of entities must not do that per component.
- *
- * @type {Function[]}
- */
-const COMPONENT_TYPES = [
-    Transform64,
-    TransformAttachment,
-    Name,
-    ShadedGeometry,
-    GPUStateAuthority,
-    ParentEntity,
-    SerializationMetadata,
-];
-
-/**
- * Spawn a prefab as entities under `root`, in bulk.
- *
- * **What a model is in an ECS.** Each node of the prefab becomes an entity: named, attached to
- * its parent's entity by a `TransformAttachment` carrying the node's rest pose, holding a world
- * `Transform64` composed from the root's, drawing through a `ShadedGeometry` where the node
- * carries geometry, and declaring `GPUStateAuthority` — with a zero flags word — where a clip or a
- * skin may later hand the node to the GPU, so that the hand-over is a bit write and never a
- * component add. Node 0 is `root` itself, the caller's entity, whose `Transform64` is the
- * placement.
- *
- * **Parents before children, and the transform last.** Entities are built in the prefab's node
- * order, which puts every parent's entity there before its children's, so
- * `TransformAttachmentSystem` binds each one on the spot rather than parking it. The `Transform64`
- * is the last component added to each entity, so every system whose dependencies include it —
- * and they all do — links once, seeing the entity complete.
- *
- * Every entity is the root's for its lifetime (`ParentEntity`) and, unless told otherwise,
- * transient to serialization: a save holds the model's placement, not sixty joints of derived
- * state.
- *
- * @param {Prefab} prefab
- * @param {EntityComponentDataset} dataset
- * @param {number} root an entity carrying a `Transform64`
- * @param {object} [options]
- * @param {boolean} [options.transient] whether the spawned entities are skipped by serialization;
- * true unless said otherwise
- * @returns {PrefabInstance}
- */
-export function prefab_instantiate(prefab, dataset, root, { transient = true } = {}) {
-    assert.defined(prefab, 'prefab');
-    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
-    assert.defined(dataset, 'dataset');
-    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
-    assert.isNonNegativeInteger(root, 'root');
-    assert.ok(dataset.entityExists(root), `root entity ${root} does not exist`);
-
-    dataset.registerManyComponentTypes(COMPONENT_TYPES);
-
-    // Component indices resolved once: an add by index skips the class lookup and the guard that
-    // formats a component into an error message, and there are six or seven adds per entity.
-    const TRANSFORM = dataset.computeComponentTypeIndex(Transform64);
-    const ATTACHMENT = dataset.computeComponentTypeIndex(TransformAttachment);
-    const NAME = dataset.computeComponentTypeIndex(Name);
-    const GEOMETRY = dataset.computeComponentTypeIndex(ShadedGeometry);
-    const AUTHORITY = dataset.computeComponentTypeIndex(GPUStateAuthority);
-    const PARENT = dataset.computeComponentTypeIndex(ParentEntity);
-    const METADATA = dataset.computeComponentTypeIndex(SerializationMetadata);
-
-    const root_transform = dataset.getComponent(root, Transform64);
-
-    assert.defined(root_transform, `root entity ${root} carries no Transform64 to place the model by`);
-
-    const node_count = prefab.node_count;
-
-    const entities = new Int32Array(node_count);
-
-    entities[0] = root;
-
-    // Ids from the dataset's own occupancy, walking forward: `createEntity` scans from bit zero
-    // every time, which is quadratic over a spawn of this size.
-    const occupancy = dataset.entityOccupancy;
-
-    let cursor = 0;
-
-    for (let i = 1; i < node_count; i++) {
-        const entity = occupancy.nextClearBit(cursor);
-
-        dataset.createEntitySpecific(entity);
-
-        entities[i] = entity;
-        cursor = entity + 1;
-    }
-
-    const parent = prefab.parent;
-    const names = prefab.name;
-    const locals = prefab.local;
-    const worlds = prefab.world;
-    const animated = prefab.animated;
-
-    /**
-     * @type {Map<number, import("./Prefab.js").PrefabPrimitive>}
-     */
-    const primitive_of = new Map();
-
-    for (const primitive of prefab.primitives) {
-        primitive_of.set(primitive.node, primitive);
-    }
-
-    // One lifetime component for the whole instance: it names the root and nothing else, it is
-    // immutable while attached, and sixty copies of one number are sixty allocations for nothing.
-    const owner = ParentEntity.from(root);
-
-    for (let i = 1; i < node_count; i++) {
-        const entity = entities[i];
-
-        if (transient) {
-            dataset.addComponentToEntityByIndex(entity, METADATA, SerializationMetadata.Transient);
-        }
-
-        dataset.addComponentToEntityByIndex(entity, PARENT, owner);
-
-        const name = names[i];
-
-        if (name !== "") {
-            dataset.addComponentToEntityByIndex(entity, NAME, new Name(name));
-        }
-
-        if (animated[i] !== 0) {
-            dataset.addComponentToEntityByIndex(entity, AUTHORITY, new GPUStateAuthority());
-        }
-
-        const primitive = primitive_of.get(i);
-
-        if (primitive !== undefined) {
-            const geometry = ShadedGeometry.from(primitive.geometry, primitive.material, DrawMode.Triangles);
-
-            if (primitive.skin !== -1) {
-                geometry.setFlag(ShadedGeometryFlags.Skinned);
-            }
-
-            dataset.addComponentToEntityByIndex(entity, GEOMETRY, geometry);
-        }
-
-        const attachment = new TransformAttachment();
-
-        attachment.parent = entities[parent[i]];
-        attachment.transform.copy(locals[i]);
-
-        // The world is composed below, from the same chain the attachment system would compose
-        // it from, so the system is told not to compose it again at link: a decomposition per
-        // entity, and an announcement nothing is listening for yet. It still follows every move
-        // of the parent from then on.
-        attachment.immediate = false;
-
-        dataset.addComponentToEntityByIndex(entity, ATTACHMENT, attachment);
-
-        // Composed here rather than left to the attachment system, so that a dataset with no
-        // systems — a preview, a spec — holds every world too.
-        const world = new Transform64();
-
-        m4_multiply(world, root_transform, worlds[i]);
-        world.updateComponents();
-
-        dataset.addComponentToEntityByIndex(entity, TRANSFORM, world);
-    }
-
-    const instance = new PrefabInstance();
-
-    instance.prefab = prefab;
-    instance.root = root;
-    instance.entities = entities;
-    instance.mesh_entities = Int32Array.from(prefab.primitives, primitive => entities[primitive.node]);
-
-    instance.skins = prefab.skins.map(skin => Skin.from({
-        name: skin.name,
-        joints: Array.from(skin.joints, joint => entities[joint]),
-        inverse_bind_matrices: skin.inverse_bind_matrices,
-        meshes: Array.from(skin.meshes, mesh => entities[mesh]),
-    }));
-
-    instance.clips = prefab.clips.map(clip => ShadeAnimationClip.from({
-        name: clip.name,
-        channels: clip.channels.map(channel => ShadeAnimationChannel.from({
-            target: entities[channel.target],
-            property: channel.property,
-            curves: channel.curves,
-        })),
-    }));
-
-    return instance;
-}
-
-/**
- * Remove every entity an instance spawned. The root is the caller's and stays.
- *
- * Children before parents, so that no parent's removal has to reach down and detach a child
- * that is about to go anyway.
- *
- * @param {EntityComponentDataset} dataset
- * @param {PrefabInstance} instance
- */
-export function prefab_instance_destroy(dataset, instance) {
-    assert.defined(dataset, 'dataset');
-    assert.defined(instance, 'instance');
-
-    const entities = instance.entities;
-
-    for (let i = entities.length - 1; i >= 1; i--) {
-        dataset.removeEntity(entities[i]);
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { ShadeAnimationChannel } from "../../../shade/renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../../../shade/renderer/animation/ShadeAnimationClip.js";
+import { Skin } from "../../../shade/renderer/animation/Skin.js";
+import { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
+import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
+import { Name } from "../../ecs/name/Name.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { DrawMode } from "../../graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { PrefabInstance } from "./PrefabInstance.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+
+/**
+ * Every component type an instance may attach. Registered once per dataset, before the first
+ * entity is built, because registering a type rebuilds the dataset's occupancy and a spawn of
+ * thousands of entities must not do that per component.
+ *
+ * @type {Function[]}
+ */
+const COMPONENT_TYPES = [
+    Transform64,
+    TransformAttachment,
+    Name,
+    ShadedGeometry,
+    GPUStateAuthority,
+    ParentEntity,
+    SerializationMetadata,
+];
+
+/**
+ * Spawn a prefab as entities under `root`, in bulk.
+ *
+ * **What a model is in an ECS.** Each node of the prefab becomes an entity: named, attached to
+ * its parent's entity by a `TransformAttachment` carrying the node's rest pose, holding a world
+ * `Transform64` composed from the root's, drawing through a `ShadedGeometry` where the node
+ * carries geometry, and declaring `GPUStateAuthority` — with a zero flags word — where a clip or a
+ * skin may later hand the node to the GPU, so that the hand-over is a bit write and never a
+ * component add. Node 0 is `root` itself, the caller's entity, whose `Transform64` is the
+ * placement.
+ *
+ * **Parents before children, and the transform last.** Entities are built in the prefab's node
+ * order, which puts every parent's entity there before its children's, so
+ * `TransformAttachmentSystem` binds each one on the spot rather than parking it. The `Transform64`
+ * is the last component added to each entity, so every system whose dependencies include it —
+ * and they all do — links once, seeing the entity complete.
+ *
+ * Every entity is the root's for its lifetime (`ParentEntity`) and, unless told otherwise,
+ * transient to serialization: a save holds the model's placement, not sixty joints of derived
+ * state.
+ *
+ * @param {Prefab} prefab
+ * @param {EntityComponentDataset} dataset
+ * @param {number} root an entity carrying a `Transform64`
+ * @param {object} [options]
+ * @param {boolean} [options.transient] whether the spawned entities are skipped by serialization;
+ * true unless said otherwise
+ * @returns {PrefabInstance}
+ */
+export function prefab_instantiate(prefab, dataset, root, { transient = true } = {}) {
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+    assert.defined(dataset, 'dataset');
+    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+    assert.isNonNegativeInteger(root, 'root');
+    assert.ok(dataset.entityExists(root), `root entity ${root} does not exist`);
+
+    dataset.registerManyComponentTypes(COMPONENT_TYPES);
+
+    // Component indices resolved once: an add by index skips the class lookup and the guard that
+    // formats a component into an error message, and there are six or seven adds per entity.
+    const TRANSFORM = dataset.computeComponentTypeIndex(Transform64);
+    const ATTACHMENT = dataset.computeComponentTypeIndex(TransformAttachment);
+    const NAME = dataset.computeComponentTypeIndex(Name);
+    const GEOMETRY = dataset.computeComponentTypeIndex(ShadedGeometry);
+    const AUTHORITY = dataset.computeComponentTypeIndex(GPUStateAuthority);
+    const PARENT = dataset.computeComponentTypeIndex(ParentEntity);
+    const METADATA = dataset.computeComponentTypeIndex(SerializationMetadata);
+
+    const root_transform = dataset.getComponent(root, Transform64);
+
+    assert.defined(root_transform, `root entity ${root} carries no Transform64 to place the model by`);
+
+    const node_count = prefab.node_count;
+
+    const entities = new Int32Array(node_count);
+
+    entities[0] = root;
+
+    // Ids from the dataset's own occupancy, walking forward: `createEntity` scans from bit zero
+    // every time, which is quadratic over a spawn of this size.
+    const occupancy = dataset.entityOccupancy;
+
+    let cursor = 0;
+
+    for (let i = 1; i < node_count; i++) {
+        const entity = occupancy.nextClearBit(cursor);
+
+        dataset.createEntitySpecific(entity);
+
+        entities[i] = entity;
+        cursor = entity + 1;
+    }
+
+    const parent = prefab.parent;
+    const names = prefab.name;
+    const locals = prefab.local;
+    const worlds = prefab.world;
+    const animated = prefab.animated;
+
+    /**
+     * @type {Map<number, import("./Prefab.js").PrefabPrimitive>}
+     */
+    const primitive_of = new Map();
+
+    for (const primitive of prefab.primitives) {
+        primitive_of.set(primitive.node, primitive);
+    }
+
+    // One lifetime component for the whole instance: it names the root and nothing else, it is
+    // immutable while attached, and sixty copies of one number are sixty allocations for nothing.
+    const owner = ParentEntity.from(root);
+
+    for (let i = 1; i < node_count; i++) {
+        const entity = entities[i];
+
+        if (transient) {
+            dataset.addComponentToEntityByIndex(entity, METADATA, SerializationMetadata.Transient);
+        }
+
+        dataset.addComponentToEntityByIndex(entity, PARENT, owner);
+
+        const name = names[i];
+
+        if (name !== "") {
+            dataset.addComponentToEntityByIndex(entity, NAME, new Name(name));
+        }
+
+        if (animated[i] !== 0) {
+            dataset.addComponentToEntityByIndex(entity, AUTHORITY, new GPUStateAuthority());
+        }
+
+        const primitive = primitive_of.get(i);
+
+        if (primitive !== undefined) {
+            const geometry = ShadedGeometry.from(primitive.geometry, primitive.material, DrawMode.Triangles);
+
+            if (primitive.skin !== -1) {
+                geometry.setFlag(ShadedGeometryFlags.Skinned);
+            }
+
+            dataset.addComponentToEntityByIndex(entity, GEOMETRY, geometry);
+        }
+
+        const attachment = new TransformAttachment();
+
+        attachment.parent = entities[parent[i]];
+        attachment.transform.copy(locals[i]);
+
+        // The world is composed below, from the same chain the attachment system would compose
+        // it from, so the system is told not to compose it again at link: a decomposition per
+        // entity, and an announcement nothing is listening for yet. It still follows every move
+        // of the parent from then on.
+        attachment.immediate = false;
+
+        dataset.addComponentToEntityByIndex(entity, ATTACHMENT, attachment);
+
+        // Composed here rather than left to the attachment system, so that a dataset with no
+        // systems — a preview, a spec — holds every world too.
+        const world = new Transform64();
+
+        m4_multiply(world, root_transform, worlds[i]);
+        world.updateComponents();
+
+        dataset.addComponentToEntityByIndex(entity, TRANSFORM, world);
+    }
+
+    const instance = new PrefabInstance();
+
+    instance.prefab = prefab;
+    instance.root = root;
+    instance.entities = entities;
+    instance.mesh_entities = Int32Array.from(prefab.primitives, primitive => entities[primitive.node]);
+
+    instance.skins = prefab.skins.map(skin => Skin.from({
+        name: skin.name,
+        joints: Array.from(skin.joints, joint => entities[joint]),
+        inverse_bind_matrices: skin.inverse_bind_matrices,
+        meshes: Array.from(skin.meshes, mesh => entities[mesh]),
+    }));
+
+    instance.clips = prefab.clips.map(clip => ShadeAnimationClip.from({
+        name: clip.name,
+        channels: clip.channels.map(channel => ShadeAnimationChannel.from({
+            target: entities[channel.target],
+            property: channel.property,
+            curves: channel.curves,
+        })),
+    }));
+
+    return instance;
+}
+
+/**
+ * Remove every entity an instance spawned. The root is the caller's and stays.
+ *
+ * Children before parents, so that no parent's removal has to reach down and detach a child
+ * that is about to go anyway.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {PrefabInstance} instance
+ */
+export function prefab_instance_destroy(dataset, instance) {
+    assert.defined(dataset, 'dataset');
+    assert.defined(instance, 'instance');
+
+    const entities = instance.entities;
+
+    for (let i = entities.length - 1; i >= 1; i--) {
+        dataset.removeEntity(entities[i]);
+    }
+}

package/src/shade/RENDERER_CONTRACT.md

@@ -277,16 +277,25 @@ change every frame, you are on the wrong path — see §8.
 
 `ShadeMaterial` is the base: `transparency_mode`, `draw_mode` and `draw_side`.
 
-**`draw_side` is part of the rasterization bucket key, and it changes what is drawn.** `Front` (the
-default) culls back faces, `Back` culls front faces, and `Double` culls neither — the three map
-straight onto the pipeline's cull mode, so a bucket exists per side that any material in the scene
-asks for. A face seen from behind is shaded with its normal flipped, so `Double` is a working
-double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and stays that
-way; the loader's fix-up pass only rewrites `Back` to `Front`, by flipping the geometry.
-
-Shadow passes invert the mapping — `Front` culls *front* faces there — so a one-sided surface casts
-from its back face and does not shadow-acne against its own lit side. `Double` has no opposite and
-stays unculled in both.
+**`draw_side` changes what is drawn.** `Front` (the default) draws the front face, `Back` the back
+face, `Double` both. A face seen from behind is shaded with its normal flipped, so `Double` is a
+working double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and
+stays that way; glTF cannot ask for `Back`, which comes from authoring.
+
+**Only `Double` costs a pipeline of its own.** It culls nothing, and no amount of winding expresses
+that. `Front` and `Back` differ by winding alone, and the vertex shader reverses winding per
+instance, so the two share a rasterization bucket and draw in one pass — which matters because a
+bucket is not a pipeline here but a whole chain: extract, expand to meshlets, select a
+virtual-geometry cut, one render pass.
+
+**That is also why a mirrored instance works.** Place a mesh under a negative scale, or under a
+parent that reflects, and it draws right way out, with the handedness of its tangent frame flipped
+to match — the reflection and the material's side are the same one bit, combined before a corner is
+chosen. glTF makes this the rule rather than an extra: the determinant of a node's world transform
+decides its winding, and a conformant renderer has to read it.
+
+Shadow passes cull the other face — so a one-sided surface casts from its back face and does not
+shadow-acne against its own lit side. `Double` has no opposite and stays unculled in both.
 
 `StandardShadeMaterial` is the PBR one everything uses:
 
@@ -474,16 +483,21 @@ Order is **declared**, never emergent:
 ```js
 class DecalExtension extends RenderExtension {
     phase = FramePhase.AfterGBuffer;
-    after = [TerrainSplatExtension];   // classes, not instances
-    before = [];
+    relative_order = 1;   // a decal composites over surfaces already written
 }
 ```
 
-Constraints name classes, so you do not need a reference to another system's object to state an
-order, and a class nobody registered is simply not a constraint. Two extensions on one phase with no
-path between them record in **ascending `name` order** — reproducible rather than correct, and chosen
-precisely so that adding an `await` to a system's startup cannot change the picture. A cycle is
-reported with the names on it.
+`relative_order` defaults to `0`; lower records first, and any finite number will do — negative to
+pull forward, positive to push back. Two extensions on one phase with the same value record in
+**ascending `name` order**, which is reproducible rather than correct and is chosen precisely so
+that adding an `await` to a system's startup cannot change the picture.
+
+**It names nothing.** An extension states where it belongs from what it does — a fog conceals, so it
+is late; a debug overlay must not be concealed, so it is later still — and needs no import of, or
+reference to, whatever else is on the phase. That is deliberately less precise than a dependency
+would be: it cannot say "immediately after that one", and there is no cycle to report because there
+is no graph. An effect that genuinely needs one particular extension's result should read a record
+that extension published, which is a real dependency rather than a positional one.
 
 ### What keeps your work alive
 

package/src/shade/device/timing/GPU_PROFILER_PROPOSAL_2026_08_28.md

@@ -693,7 +693,7 @@ what they are looking at is the observer.
 ## 7. The inspector
 
 `packages/gpu-inspector-tool/`. A static site: drop a `.sgpt` on it, or pass `?file=` for a
-bookmarkable view — the affordance the `vgeo_viewer` playground already establishes in this codebase.
+bookmarkable view — the affordance the `.vgeo` playgrounds already establish in this codebase.
 
 ### 7.1 Technology