@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/light/shader_refresh_light_poses.js

@@ -0,0 +1,154 @@
+import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_scene_database_access } from "../scene/chunk_scene_database_access.js";
+import { LIGHT_DATABASE_SPEC } from "./LIGHT_DATABASE_SPEC.js";
+
+export const REFRESH_LIGHT_POSES_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+/**
+ * Which light table a workgroup along `y` of the dispatch walks.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const REFRESH_LIGHT_POSES_TABLE = Object.freeze({
+    POINT: 0,
+    SPOT: 1,
+    DIRECTIONAL: 2,
+});
+
+/** The dispatch is three tables wide. */
+export const REFRESH_LIGHT_POSES_TABLE_COUNT = 3;
+
+const POINT = LIGHT_DATABASE_SPEC.get('light_point');
+const SPOT = LIGHT_DATABASE_SPEC.get('light_spot');
+const DIRECTIONAL = LIGHT_DATABASE_SPEC.get('light_directional');
+
+const WG = REFRESH_LIGHT_POSES_WORKGROUP_SIZE;
+
+// read-write iterators over the light tables' pages: the pass writes the pose back into the
+// database it reads the row from, and WGSL will not coerce a `read_write` pointer down to `read`
+const PG_POINT = POINT.page_iterator_symbol_prefix(WG, true);
+const PG_SPOT = SPOT.page_iterator_symbol_prefix(WG, true);
+const PG_DIRECTIONAL = DIRECTIONAL.page_iterator_symbol_prefix(WG, true);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), true);
+
+/**
+ * Write every light record's pose from the `transforms` row it names — after the hierarchy pass
+ * has composed that row's `global`.
+ *
+ * **This is what makes a light's pose the GPU's.** A light is an entity, and its record's `node`
+ * is that entity's row. The row's `global` is composed on the GPU from its TRS and its parent
+ * chain, and once an ancestor can be GPU-driven — a torch in an animated hand — nothing on the
+ * CPU holds the world transform the record would need. So the pose is taken where the transform
+ * is: a point light's `position` is the row's translation, a directional light's `direction` is
+ * the row's +Z, a spot light's both; once per light per frame, over each table's pages rather
+ * than over `[0, count)`, because rows are addresses and a live one can sit above any number of
+ * holes.
+ *
+ * The CPU still writes the same fields when it builds a record, from the entity's own transform
+ * — exact for an entity the CPU composes, and what a pass that runs before this one in a frame
+ * reads. This pass is what makes them right for the entity the CPU does not compose, and it runs
+ * every frame because the hierarchy pass does.
+ *
+ * Runs after the hierarchy pass and before anything reads a light. The dispatch is
+ * {@link REFRESH_LIGHT_POSES_TABLE_COUNT} workgroups wide along `y`, one table each, and along
+ * `x` as many as the widest table's {@link GPUTypedTable#dispatch_group_count} at
+ * {@link REFRESH_LIGHT_POSES_WORKGROUP_SIZE}; a workgroup past a table's pages bails at setup.
+ */
+export const shader_refresh_light_poses = ComputeShader.from({
+    label: "Light/RefreshPoses",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+fn light_row_position(node: u32) -> vec3<f32> {
+    let xf = scene_read_node(&scene_database, node).global;
+
+    return (xf * vec4<f32>(0.0, 0.0, 0.0, 1.0)).xyz;
+}
+
+// the engine's convention: a light shines along its +Z
+fn light_row_direction(node: u32) -> vec3<f32> {
+    let xf = scene_read_node(&scene_database, node).global;
+
+    return normalize((xf * vec4<f32>(0.0, 0.0, 1.0, 0.0)).xyz);
+}
+
+@compute @workgroup_size(${WG},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    // wg_id is uniform across the workgroup, and so is every branch below
+    if wg_id.y == ${REFRESH_LIGHT_POSES_TABLE.POINT}u {
+        if !${PG_POINT}_setup(&light_database, wg_id.x, local_id) {
+            return;
+        }
+
+        let slot = ${PG_POINT}_slot_in_page(local_id);
+
+        if slot >= ${PG_POINT}_ELEMENTS_PER_PAGE || !${PG_POINT}_is_occupied(slot) {
+            return;
+        }
+
+        let index = ${PG_POINT}_slot_to_index(slot);
+        let light = ${POINT.marshalling_method_read_rw}(&light_database, index);
+
+        ${POINT.marshalling_method_write_field('position')}(&light_database, index, light_row_position(light.node));
+    } else if wg_id.y == ${REFRESH_LIGHT_POSES_TABLE.SPOT}u {
+        if !${PG_SPOT}_setup(&light_database, wg_id.x, local_id) {
+            return;
+        }
+
+        let slot = ${PG_SPOT}_slot_in_page(local_id);
+
+        if slot >= ${PG_SPOT}_ELEMENTS_PER_PAGE || !${PG_SPOT}_is_occupied(slot) {
+            return;
+        }
+
+        let index = ${PG_SPOT}_slot_to_index(slot);
+        let light = ${SPOT.marshalling_method_read_rw}(&light_database, index);
+
+        ${SPOT.marshalling_method_write_field('position')}(&light_database, index, light_row_position(light.node));
+        ${SPOT.marshalling_method_write_field('direction')}(&light_database, index, light_row_direction(light.node));
+    } else {
+        if !${PG_DIRECTIONAL}_setup(&light_database, wg_id.x, local_id) {
+            return;
+        }
+
+        let slot = ${PG_DIRECTIONAL}_slot_in_page(local_id);
+
+        if slot >= ${PG_DIRECTIONAL}_ELEMENTS_PER_PAGE || !${PG_DIRECTIONAL}_is_occupied(slot) {
+            return;
+        }
+
+        let index = ${PG_DIRECTIONAL}_slot_to_index(slot);
+        let light = ${DIRECTIONAL.marshalling_method_read_rw}(&light_database, index);
+
+        ${DIRECTIONAL.marshalling_method_write_field('direction')}(&light_database, index, light_row_direction(light.node));
+    }
+}
+`, [
+            chunk_scene_database_access,
+            POINT.chunk_iterate(WG, true),
+            SPOT.chunk_iterate(WG, true),
+            DIRECTIONAL.chunk_iterate(WG, true),
+            POINT.chunk_read_rw,
+            SPOT.chunk_read_rw,
+            DIRECTIONAL.chunk_read_rw,
+            POINT.wgsl_gen_write_field_code('position'),
+            SPOT.wgsl_gen_write_field_code('position'),
+            SPOT.wgsl_gen_write_field_code('direction'),
+            DIRECTIONAL.wgsl_gen_write_field_code('direction'),
+        ]),
+    resources,
+});

package/src/shade/renderer/lightmap/GPULightMap.js

@@ -139,7 +139,7 @@ export class GPULightMap {
         const r_materials = graphics.materials_resident;
 
 
-        r_materials.ensure_scene_materials(scene_ctx.scene);
+        r_materials.ensure_scene_materials(scene_ctx);
         r_materials.update();
 
         const viz_buffer = graph_import_texture(graph, this.texture_viz);

package/src/shade/renderer/lightmap/bake/raster/graph_draw_lightmap_viz_buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_draw_lightmap_viz_buffer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/lightmap/bake/raster/graph_draw_lightmap_viz_buffer.js"],"names":[],"mappings":"AA8CA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACT,MAAM,EAAtB,MAAM;IACmB,KAAK;IACZ,KAAK,GAAvB,OAAO;IACL,MAAM,CAsLlB"}
+{"version":3,"file":"graph_draw_lightmap_viz_buffer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/lightmap/bake/raster/graph_draw_lightmap_viz_buffer.js"],"names":[],"mappings":"AA+CA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACT,MAAM,EAAtB,MAAM;IACmB,KAAK;IACZ,KAAK,GAAvB,OAAO;IACL,MAAM,CAmLlB"}

package/src/shade/renderer/lightmap/bake/raster/graph_draw_lightmap_viz_buffer.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../../core/assert.js";
+import { row_of_entity } from "../../../scene/rows/GPUSceneRows.js";
 import { vec2f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import {
     VIZ_BUFFER_INVALID_MESH_VALUE
@@ -74,9 +75,15 @@ export function graph_draw_lightmap_viz_buffer({
      */
     function execute(data, resources, context) {
 
-        const meshes = scene.scene.instances.instances;
+        // every mesh row, with the row it is — what the viz buffer carries per pixel, and what the
+        // bake's shaders read the record by
+        const drawn = [];
 
-        const mesh_count = meshes.length;
+        scene.rows.for_each_mesh((entity, geometry) => {
+            drawn.push({ row: row_of_entity(entity), geometry });
+        });
+
+        const mesh_count = drawn.length;
 
         if (mesh_count <= 0) {
             // nothing to do
@@ -128,10 +135,7 @@ export function graph_draw_lightmap_viz_buffer({
             });
 
             for (let i = 0; i < mesh_count; i++) {
-                const mesh = meshes[i];
-                const geometry = mesh.geometry;
-
-                const mesh_id = i;
+                const { row: mesh_id, geometry } = drawn[i];
 
                 pass.draw(
                     geometry.getVertexCount(),
@@ -166,10 +170,7 @@ export function graph_draw_lightmap_viz_buffer({
             });
 
             for (let i = 0; i < mesh_count; i++) {
-                const mesh = meshes[i];
-                const geometry = mesh.geometry;
-
-                const mesh_id = i;
+                const { row: mesh_id, geometry } = drawn[i];
 
                 // line-list: 3 edges x 2 vertices per triangle = 6 per triangle, i.e. 2x the
                 // index count — with only getIndexCount() vertices half the triangles got no edges
@@ -206,10 +207,7 @@ export function graph_draw_lightmap_viz_buffer({
             });
 
             for (let i = 0; i < mesh_count; i++) {
-                const mesh = meshes[i];
-                const geometry = mesh.geometry;
-
-                const mesh_id = i;
+                const { row: mesh_id, geometry } = drawn[i];
 
                 pass.draw(
                     geometry.getIndexCount(),

package/src/shade/renderer/loader/SceneBundle.d.ts

@@ -1,53 +1,78 @@
 /**
- * Loader-stage container: a scene's root Node3Ds plus any companion
- * data extracted from the same source asset that isn't carried on
- * those nodes directly. Returned from {@link load_gltf} (and any
- * future loader that produces the same kind of output).
- *
- * Not GLTF-specific by design — the bundle describes "what came out
- * of a loader", not "what was in a GLTF". Skins and clips are pure
- * CPU data classes from `src/webgpu/renderer/animation/`; the bundle just
- * groups them with the matching scene roots so callers can pass them
- * to {@link GPUAnimationManager#register_skin} and
- * {@link GPUAnimationManager#register_clip} after adding the scene
- * roots to the scene and letting `scene.build` populate `id_mapping`.
+ * @typedef {import("./SceneNode.js").SceneNode} SceneNode
+ * @typedef {import("../animation/Skin.js").Skin} Skin
+ * @typedef {import("../animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../light/model/Light.js").Light} Light
+ */
+/**
+ * What came out of a loader: a model as a flat list of {@link SceneNode}s in pre-order, with the
+ * skins, clips and lights the same file carried, each addressing nodes by index.
  *
- * Pure data — no behavior, no lifecycle. Discardable after
- * registration; the manager retains GPU-side copies of everything
- * it consumed.
+ * Not glTF-specific by design — the bundle describes "what a loader produced", not "what was in
+ * a file", and every loader ({@link load_gltf}, {@link load_usd}, {@link deserialize_scene})
+ * produces one. It is pure data with no lifecycle: a model compiles from it once into a
+ * {@link Prefab} (`prefab_compile`), and a prefab is what gets placed — as entities, each holding
+ * a row — however many times the model appears. The bundle is read by that compile and never
+ * written, so one bundle is shared by every placement, which is what the asset manager hands out.
  *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
+ * Pre-order is the one structural promise: a node's parent has a lower index. {@link add_node}
+ * refuses anything else, so a reader composes world transforms in a single forward pass.
  */
 export class SceneBundle {
     /**
-     * Root Node3D for each top-level scene in the source asset.
-     * Typical assets have exactly one, but multi-scene files (and
-     * the glTF format in particular) allow multiple.
+     * Every node of the model, parents before children.
      *
-     * @type {Node3D[]}
+     * @type {SceneNode[]}
      */
-    scenes: Node3D[];
+    nodes: SceneNode[];
     /**
-     * Skins extracted from the asset. Each skin's `meshes` field
-     * lists the {@link SkinnedMesh}es under {@link scenes} that
-     * deform against it. Empty if the asset has no skinned meshes.
+     * Skins extracted from the asset. A skin's `joints` and `meshes` are indices into
+     * {@link nodes}. Empty if the asset has no skinned meshes.
      *
      * @type {Skin[]}
      */
     skins: Skin[];
     /**
-     * Animation clips extracted from the asset. Each clip's
-     * channels target Node3D instances under {@link scenes}.
-     * Empty if the asset has no animations.
+     * Animation clips extracted from the asset. Each channel's `target` is an index into
+     * {@link nodes}. Empty if the asset has no animations.
      *
      * @type {ShadeAnimationClip[]}
      */
     clips: ShadeAnimationClip[];
+    /**
+     * Punctual lights extracted from the asset, each with the index of the node it sits on. A
+     * light is not a node and has no place of its own; the node's transform is where it is,
+     * already turned to shine along the engine's +Z. Empty if the asset has no lights.
+     *
+     * @type {{light: Light, node: number}[]}
+     */
+    lights: {
+        light: Light;
+        node: number;
+    }[];
+    /**
+     * Append a node. Its parent, if it has one, must already be in the bundle — which is what
+     * keeps the list in pre-order.
+     *
+     * @param {SceneNode} node
+     * @returns {number} the node's index, what a child, a skin, a clip or a light names it by
+     */
+    add_node(node: SceneNode): number;
+    /**
+     * The world matrix of every node, composed root-first in double precision — what a reader
+     * that wants where things are in the model's own space asks for, once.
+     *
+     * @returns {Float64Array[]} one 4x4 per node, column-major
+     */
+    compute_world_matrices(): Float64Array[];
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isSceneBundle: boolean;
 }
+export type SceneNode = import("./SceneNode.js").SceneNode;
+export type Skin = import("../animation/Skin.js").Skin;
+export type ShadeAnimationClip = import("../animation/ShadeAnimationClip.js").ShadeAnimationClip;
+export type Light = import("../light/model/Light.js").Light;
 //# sourceMappingURL=SceneBundle.d.ts.map

package/src/shade/renderer/loader/SceneBundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SceneBundle.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/loader/SceneBundle.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;;;;OAMG;IACH,QAFU,QAAQ,CAEN;IAEZ;;;;;;OAMG;IACH,OAFU,MAAM,CAEL;IAEX;;;;;;OAMG;IACH,OAFU,oBAAoB,CAEnB;IAGf;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC"}
+{"version":3,"file":"SceneBundle.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/loader/SceneBundle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH;IACI;;;;OAIG;IACH,OAFU,SAAS,EAAE,CAEV;IAEX;;;;;OAKG;IACH,OAFU,IAAI,EAAE,CAEL;IAEX;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAEX;;;;;;OAMG;IACH,QAFU;QAAC,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAE5B;IAEZ;;;;;;OAMG;IACH,eAHW,SAAS,GACP,MAAM,CAalB;IAED;;;;;OAKG;IACH,0BAFa,YAAY,EAAE,CAsB1B;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;wBApGY,OAAO,gBAAgB,EAAE,SAAS;mBAClC,OAAO,sBAAsB,EAAE,IAAI;iCACnC,OAAO,oCAAoC,EAAE,kBAAkB;oBAC/D,OAAO,yBAAyB,EAAE,KAAK"}

package/src/shade/renderer/loader/SceneBundle.js

@@ -1,56 +1,111 @@
-/**
- * Loader-stage container: a scene's root Node3Ds plus any companion
- * data extracted from the same source asset that isn't carried on
- * those nodes directly. Returned from {@link load_gltf} (and any
- * future loader that produces the same kind of output).
- *
- * Not GLTF-specific by design — the bundle describes "what came out
- * of a loader", not "what was in a GLTF". Skins and clips are pure
- * CPU data classes from `src/webgpu/renderer/animation/`; the bundle just
- * groups them with the matching scene roots so callers can pass them
- * to {@link GPUAnimationManager#register_skin} and
- * {@link GPUAnimationManager#register_clip} after adding the scene
- * roots to the scene and letting `scene.build` populate `id_mapping`.
- *
- * Pure data — no behavior, no lifecycle. Discardable after
- * registration; the manager retains GPU-side copies of everything
- * it consumed.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class SceneBundle {
-
-    /**
-     * Root Node3D for each top-level scene in the source asset.
-     * Typical assets have exactly one, but multi-scene files (and
-     * the glTF format in particular) allow multiple.
-     *
-     * @type {Node3D[]}
-     */
-    scenes = [];
-
-    /**
-     * Skins extracted from the asset. Each skin's `meshes` field
-     * lists the {@link SkinnedMesh}es under {@link scenes} that
-     * deform against it. Empty if the asset has no skinned meshes.
-     *
-     * @type {Skin[]}
-     */
-    skins = [];
-
-    /**
-     * Animation clips extracted from the asset. Each clip's
-     * channels target Node3D instances under {@link scenes}.
-     * Empty if the asset has no animations.
-     *
-     * @type {ShadeAnimationClip[]}
-     */
-    clips = [];
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-SceneBundle.prototype.isSceneBundle = true;
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+
+/**
+ * @typedef {import("./SceneNode.js").SceneNode} SceneNode
+ * @typedef {import("../animation/Skin.js").Skin} Skin
+ * @typedef {import("../animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../light/model/Light.js").Light} Light
+ */
+
+/**
+ * What came out of a loader: a model as a flat list of {@link SceneNode}s in pre-order, with the
+ * skins, clips and lights the same file carried, each addressing nodes by index.
+ *
+ * Not glTF-specific by design — the bundle describes "what a loader produced", not "what was in
+ * a file", and every loader ({@link load_gltf}, {@link load_usd}, {@link deserialize_scene})
+ * produces one. It is pure data with no lifecycle: a model compiles from it once into a
+ * {@link Prefab} (`prefab_compile`), and a prefab is what gets placed — as entities, each holding
+ * a row — however many times the model appears. The bundle is read by that compile and never
+ * written, so one bundle is shared by every placement, which is what the asset manager hands out.
+ *
+ * Pre-order is the one structural promise: a node's parent has a lower index. {@link add_node}
+ * refuses anything else, so a reader composes world transforms in a single forward pass.
+ */
+export class SceneBundle {
+    /**
+     * Every node of the model, parents before children.
+     *
+     * @type {SceneNode[]}
+     */
+    nodes = [];
+
+    /**
+     * Skins extracted from the asset. A skin's `joints` and `meshes` are indices into
+     * {@link nodes}. Empty if the asset has no skinned meshes.
+     *
+     * @type {Skin[]}
+     */
+    skins = [];
+
+    /**
+     * Animation clips extracted from the asset. Each channel's `target` is an index into
+     * {@link nodes}. Empty if the asset has no animations.
+     *
+     * @type {ShadeAnimationClip[]}
+     */
+    clips = [];
+
+    /**
+     * Punctual lights extracted from the asset, each with the index of the node it sits on. A
+     * light is not a node and has no place of its own; the node's transform is where it is,
+     * already turned to shine along the engine's +Z. Empty if the asset has no lights.
+     *
+     * @type {{light: Light, node: number}[]}
+     */
+    lights = [];
+
+    /**
+     * Append a node. Its parent, if it has one, must already be in the bundle — which is what
+     * keeps the list in pre-order.
+     *
+     * @param {SceneNode} node
+     * @returns {number} the node's index, what a child, a skin, a clip or a light names it by
+     */
+    add_node(node) {
+        assert.defined(node, 'node');
+        assert.equal(node.isSceneNode, true, 'node.isSceneNode !== true');
+
+        const index = this.nodes.length;
+
+        assert.lessThan(node.parent, index, `node ${index} (${node.name}) names parent ${node.parent}, which is not in the bundle yet — add parents before children`);
+
+        this.nodes.push(node);
+
+        return index;
+    }
+
+    /**
+     * The world matrix of every node, composed root-first in double precision — what a reader
+     * that wants where things are in the model's own space asks for, once.
+     *
+     * @returns {Float64Array[]} one 4x4 per node, column-major
+     */
+    compute_world_matrices() {
+        const nodes = this.nodes;
+        const count = nodes.length;
+        const worlds = new Array(count);
+
+        for (let i = 0; i < count; i++) {
+            const node = nodes[i];
+            const world = new Float64Array(16);
+            const local = node.local.matrix;
+
+            if (node.parent === -1) {
+                world.set(local);
+            } else {
+                m4_multiply(world, worlds[node.parent], local);
+            }
+
+            worlds[i] = world;
+        }
+
+        return worlds;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+SceneBundle.prototype.isSceneBundle = true;

package/src/shade/renderer/loader/SceneNode.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @typedef {import("../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ */
+/**
+ * One node of a loaded model, as a loader describes it: a name, the index of its parent, its own
+ * local transform, and — when the node draws — a geometry and a material.
+ *
+ * A description, not a runtime object. It has no children list, no world transform and no row:
+ * the parent index is the whole of the hierarchy, worlds are composed by whoever needs them
+ * (`prefab_compile` once per model, `shade_bundle_bounds` once per query), and what a node
+ * becomes on a screen is an entity of a {@link Prefab} instance. Nodes sit in a
+ * {@link SceneBundle} in pre-order — a parent's index below its children's — which is what lets
+ * every reader compose worlds in one forward pass.
+ *
+ * A node that draws is a primitive: a glTF mesh with one primitive is the node itself; one with
+ * several is a node with one child per primitive. Whether a primitive is skinned is not written
+ * on it — a skin names the nodes it deforms ({@link Skin.meshes}).
+ */
+export class SceneNode {
+    /**
+     * @param {object} [options]
+     * @param {string} [options.name]
+     * @param {number} [options.parent] -1 for a root
+     * @param {number[]} [options.translation]
+     * @param {number[]} [options.rotation] a quaternion, `x, y, z, w`
+     * @param {number[]} [options.scale]
+     * @param {ArrayLike<number>} [options.matrix] a column-major 4x4, instead of the three above
+     * @param {MeshletGeometry} [options.geometry]
+     * @param {ShadeMaterial} [options.material]
+     * @returns {SceneNode}
+     */
+    static from({ name, parent, translation, rotation, scale, matrix, geometry, material }?: {
+        name?: string;
+        parent?: number;
+        translation?: number[];
+        rotation?: number[];
+        scale?: number[];
+        matrix?: ArrayLike<number>;
+        geometry?: MeshletGeometry;
+        material?: ShadeMaterial;
+    }): SceneNode;
+    /**
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Index of the parent in the bundle's nodes, or -1 for a root.
+     *
+     * @type {number}
+     */
+    parent: number;
+    /**
+     * The node's own transform, relative to its parent. Kept with its matrix current: a reader
+     * composes worlds from `local.matrix` without asking.
+     *
+     * @type {Transform64}
+     */
+    local: Transform64;
+    /**
+     * What the node draws, or `null` for a node that only places others.
+     *
+     * @type {MeshletGeometry|null}
+     */
+    geometry: MeshletGeometry | null;
+    /**
+     * How it is drawn; `null` exactly when {@link geometry} is.
+     *
+     * @type {ShadeMaterial|null}
+     */
+    material: ShadeMaterial | null;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isSceneNode: boolean;
+}
+export type MeshletGeometry = import("../geometry/MeshletGeometry.js").MeshletGeometry;
+export type ShadeMaterial = import("../material/ShadeMaterial.js").ShadeMaterial;
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+//# sourceMappingURL=SceneNode.d.ts.map

package/src/shade/renderer/loader/SceneNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneNode.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/loader/SceneNode.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IAmCI;;;;;;;;;;;OAWG;IACH;QAV4B,IAAI,GAArB,MAAM;QACW,MAAM,GAAvB,MAAM;QACa,WAAW,GAA9B,MAAM,EAAE;QACW,QAAQ,GAA3B,MAAM,EAAE;QACW,KAAK,GAAxB,MAAM,EAAE;QACoB,MAAM,GAAlC,UAAU,MAAM,CAAC;QACS,QAAQ,GAAlC,eAAe;QACS,QAAQ,GAAhC,aAAa;QACX,SAAS,CAsCrB;IAlFD;;OAEG;IACH,MAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,WAAW,CAEK;IAE1B;;;;OAIG;IACH,UAFU,eAAe,GAAC,IAAI,CAEd;IAEhB;;;;OAIG;IACH,UAFU,aAAa,GAAC,IAAI,CAEZ;IAqDpB;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B;8BAvGY,OAAO,gCAAgC,EAAE,eAAe;4BACxD,OAAO,8BAA8B,EAAE,aAAa;4BAJrC,8CAA8C"}