@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,114 @@
+import { assert } from "../../../core/assert.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+
+/**
+ * @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 {
+    /**
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * Index of the parent in the bundle's nodes, or -1 for a root.
+     *
+     * @type {number}
+     */
+    parent = -1;
+
+    /**
+     * 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 = new Transform64();
+
+    /**
+     * What the node draws, or `null` for a node that only places others.
+     *
+     * @type {MeshletGeometry|null}
+     */
+    geometry = null;
+
+    /**
+     * How it is drawn; `null` exactly when {@link geometry} is.
+     *
+     * @type {ShadeMaterial|null}
+     */
+    material = null;
+
+    /**
+     * @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 = -1, translation, rotation, scale, matrix, geometry = null, material = null } = {}) {
+        assert.isString(name, 'name');
+        assert.isNumber(parent, 'parent');
+        assert.equal(Number.isInteger(parent) && parent >= -1, true, 'parent is an index into the bundle, or -1 for a root');
+        assert.equal((geometry === null) === (material === null), true, 'a primitive has a geometry and a material, and a node that does not draw has neither');
+
+        const r = new SceneNode();
+
+        r.name = name;
+        r.parent = parent;
+        r.geometry = geometry;
+        r.material = material;
+
+        const local = r.local;
+
+        if (matrix !== undefined) {
+            assert.equal(translation === undefined && rotation === undefined && scale === undefined, true, 'a matrix, or a translation, rotation and scale — not both');
+
+            local.fromMatrix(matrix);
+        } else {
+            if (translation !== undefined) {
+                local.setTranslation(translation[0], translation[1], translation[2]);
+            }
+
+            if (rotation !== undefined) {
+                local.setRotation(rotation[0], rotation[1], rotation[2], rotation[3]);
+            }
+
+            if (scale !== undefined) {
+                local.setScale(scale[0], scale[1], scale[2]);
+            }
+
+            local.updateMatrix();
+        }
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+SceneNode.prototype.isSceneNode = true;

package/src/shade/renderer/loader/gltf/load_gltf.d.ts

@@ -56,8 +56,9 @@ export function canonicalize_quaternion_signs(values: Float32Array, key_count: n
  * Callers add `bundle.scenes` to their scene, then pass the bundle's
  * `skins` / `clips` to the scene's animation manager (e.g. via
  * {@link GPUAnimationManager#register_skin} and
- * {@link GPUAnimationManager#register_clip}) once `scene.build` has
- * populated `id_mapping` for the joint and target nodes.
+ * {@link GPUAnimationManager#register_clip}) once the bundle has been
+ * compiled into a prefab and instantiated, so that the joints and targets
+ * are entities holding rows.
  *
  * @param {string} url un-resolved — the asset manager resolves network paths
  * @param {Object} options

package/src/shade/renderer/loader/gltf/load_gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/load_gltf.js"],"names":[],"mappings":"AAuIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,sDATW,YAAY,aAGZ,MAAM,iBACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,QAgDlD;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+BAdW,MAAM;IAEgB,YAAY;IAGN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IAGF,eAAe,GAA/C,qBAAqB;IAGpB,QAAQ,WAAW,CAAC,CA82B/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCARW,MAAM;IAEgB,YAAY;IACN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IACF,eAAe,GAA/C,qBAAqB;IACnB,QAAQ,QAAQ,CAAC,CAU7B;4BAnnC2B,mBAAmB;yBAStB,gBAAgB"}
+{"version":3,"file":"load_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/load_gltf.js"],"names":[],"mappings":"AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,sDATW,YAAY,aAGZ,MAAM,iBACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,QAgDlD;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+BAdW,MAAM;IAEgB,YAAY;IAGN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IAGF,eAAe,GAA/C,qBAAqB;IAGpB,QAAQ,WAAW,CAAC,CA+0B/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCARW,MAAM;IAEgB,YAAY;IACN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IACF,eAAe,GAA/C,qBAAqB;IACnB,QAAQ,QAAQ,CAAC,CAU7B;4BAtlC2B,mBAAmB;yBAUtB,gBAAgB"}

package/src/shade/renderer/loader/gltf/load_gltf.js

@@ -30,12 +30,10 @@ import { SpotLight } from "../../light/model/SpotLight.js";
 
 import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
 import { Node3DProperty } from "../../object_property/Node3DProperty.js";
-import { Mesh } from "../../scene/Mesh.js";
-import { Node3D } from "../../scene/Node3D.js";
-import { SkinnedMesh } from "../../scene/SkinnedMesh.js";
 import { ShadeTexture } from "../../texture/ShadeTexture.js";
 import { ShadeImage } from "../../texture/source/ShadeImage.js";
 import { SceneBundle } from "../SceneBundle.js";
+import { SceneNode } from "../SceneNode.js";
 import { coalesce_array_duplicates } from "../../../../format/scene/gltf/coalesce_array_duplicates.js";
 import { fix_up_material_sides } from "./fix_up_material_sides.js";
 import { GLTF_COMPONENT_TYPE } from "../../../../format/scene/gltf/gltf_component_type.js";
@@ -252,8 +250,9 @@ function gltf_interpolation_to_kind(interpolation) {
  * Callers add `bundle.scenes` to their scene, then pass the bundle's
  * `skins` / `clips` to the scene's animation manager (e.g. via
  * {@link GPUAnimationManager#register_skin} and
- * {@link GPUAnimationManager#register_clip}) once `scene.build` has
- * populated `id_mapping` for the joint and target nodes.
+ * {@link GPUAnimationManager#register_clip}) once the bundle has been
+ * compiled into a prefab and instantiated, so that the joints and targets
+ * are entities holding rows.
  *
  * @param {string} url un-resolved — the asset manager resolves network paths
  * @param {Object} options
@@ -314,7 +313,10 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
          *
          * @type {Node3D[]}
          */
-        const node3d_by_index = new Array((gltf.nodes ?? []).length);
+        const record_index_of = new Int32Array((gltf.nodes ?? []).length).fill(-1);
+
+        // what the file becomes: nodes in pre-order, as the walk below produces them
+        const bundle = new SceneBundle();
 
         /**
          * Queue of pending `skin.meshes` pushes. process_node() can't
@@ -583,7 +585,7 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
          * @param {boolean} is_skinned
          * @returns {Mesh[]}
          */
-        function process_mesh(mesh_index, node, is_skinned) {
+        function process_mesh(mesh_index) {
 
             const mesh = meshes[mesh_index];
 
@@ -592,8 +594,7 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
             const primitive_count = primitives.length;
 
             /**
-             *
-             * @type {Mesh[]}
+             * @type {{geometry: MeshletGeometry, material: StandardShadeMaterial, name: string}[]}
              */
             const result = [];
 
@@ -637,17 +638,7 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
                     material = default_material;
                 }
 
-                const engine_mesh = is_skinned ? new SkinnedMesh() : new Mesh();
-                engine_mesh.geometry = geometry;
-                engine_mesh.material = material;
-                engine_mesh.transform_global.fromMatrix(node.worldMatrix);
-
-
-                if (mesh.name !== undefined) {
-                    engine_mesh.name = mesh.name;
-                }
-
-                result.push(engine_mesh);
+                result.push({ geometry, material, name: mesh.name ?? "" });
             }
 
             return result;
@@ -735,163 +726,147 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
          * @param {number} node_index
          */
         function process_node(parent, node_index) {
-
             const node = nodes[node_index];
 
-            // glTF "skin" attaches at the node, not the mesh: every
-            // primitive of the referenced mesh becomes a SkinnedMesh
-            // bound to this skin. Resolved later (after the recursion
-            // is done) against `skins[]`, which we've already built
-            // — the joint Node3Ds may be visited *after* this node,
-            // so we just record the produced SkinnedMeshes here and
-            // push them into `skin.meshes` once the walk finishes.
+            // glTF "skin" attaches at the node, not the mesh: every primitive of the referenced
+            // mesh deforms against this skin. Resolved later, against `skins[]`, which is built
+            // after the walk — the joints may be visited *after* this node — so the primitives
+            // produced here are queued and pushed into `skin.meshes` once the walk finishes.
             const skin_index = typeof node.skin === "number" ? node.skin : -1;
 
-            let node3d;
-            let produced_skinned_meshes = null;
-
-            if (node.extensions !== undefined && node.extensions.KHR_lights_punctual !== undefined) {
-                const light_index = node.extensions.KHR_lights_punctual.light;
-
-                try {
-                    node3d = process_light(light_index, node);
-                } catch (e) {
-                    console.error("Failed to process light ", light_index, " ", e);
-                }
-            }
-
+            const record = new SceneNode();
 
-            if (typeof node.mesh === "number") {
-                const meshes = process_mesh(node.mesh, node, skin_index !== -1);
-
-                if (meshes.length === 1) {
-                    node3d = meshes[0];
-                } else if (meshes.length > 1) {
-                    node3d = new Node3D();
-
-                    node3d.addChildren(meshes)
-                }
-
-                if (skin_index !== -1) {
-                    produced_skinned_meshes = meshes;
-                }
-            }
-
-            if (node3d === undefined) {
-                node3d = new Node3D();
-            }
-
-            // Stash by glTF index — joint refs and animation channel
-            // targets resolve through this lookup once the recursion
-            // unwinds.
-            node3d_by_index[node_index] = node3d;
+            record.parent = parent;
 
             if (node.name !== undefined) {
-                node3d.name = node.name;
+                record.name = node.name;
             }
 
-            if (node.matrix !== undefined) {
-
-                node3d.transform_local.fromMatrix(node.matrix);
+            const t = record.local;
 
+            if (node.matrix !== undefined) {
+                t.fromMatrix(node.matrix);
             } else {
-
-                const t = node3d.transform_local;
-
                 if (node.translation !== undefined) {
                     const v = node.translation;
-
                     t.setTranslation(v[0], v[1], v[2]);
                 }
 
                 if (node.rotation !== undefined) {
                     const q = node.rotation;
-
                     t.setRotation(q[0], q[1], q[2], q[3]);
                 }
 
                 if (node.scale !== undefined) {
                     const v = node.scale;
-
                     t.setScale(v[0], v[1], v[2]);
                 }
+
+                t.updateMatrix();
             }
 
+            const index = bundle.add_node(record);
 
-            if (node3d.isDirectionalLight || node3d.isSpotLight) {
-                // glTF lights shine along their local -Z; engine convention is forward = shining direction
-                const t = node3d.transform_local;
+            // joint refs, channel targets and light anchors resolve through this once the
+            // recursion unwinds
+            record_index_of[node_index] = index;
 
-                // the direction is read off the matrix, and a Transform64 does not maintain its own
-                t.updateMatrix();
+            if (node.extensions !== undefined && node.extensions.KHR_lights_punctual !== undefined) {
+                const light_index = node.extensions.KHR_lights_punctual.light;
 
-                t64_transform_direction(SCRATCH_DIRECTION, t, 0, 0, 1);
+                try {
+                    // a light is not a node: the node is where it is, and the bundle carries the pair
+                    const punctual = process_light(light_index, node);
+
+                    if (punctual.isDirectionalLight === true || punctual.isSpotLight === true) {
+                        // glTF lights shine along their local -Z; engine convention is forward =
+                        // shining direction. The direction is read off the matrix, which the
+                        // record keeps current.
+                        t64_transform_direction(SCRATCH_DIRECTION, t, 0, 0, 1);
+                        t64_look_rotation(
+                            t,
+                            -SCRATCH_DIRECTION.x, -SCRATCH_DIRECTION.y, -SCRATCH_DIRECTION.z,
+                            0, 1, 0
+                        );
+                        t.updateMatrix();
+                    }
 
-                t64_look_rotation(
-                    t,
-                    -SCRATCH_DIRECTION.x, -SCRATCH_DIRECTION.y, -SCRATCH_DIRECTION.z,
-                    0, 1, 0
-                );
+                    punctual_lights.push({ light: punctual, node: index });
+                } catch (e) {
+                    console.error("Failed to process light ", light_index, " ", e);
+                }
             }
 
-            parent.addChild(node3d);
+            if (typeof node.mesh === "number") {
+                const primitives = process_mesh(node.mesh);
 
-            if (produced_skinned_meshes !== null) {
-                // Defer the `skin.meshes` push to after `skins[]` is
-                // built — we collect into a queue here and process it
-                // at the end of process().
-                skin_mesh_pushes.push({
-                    skin_index,
-                    meshes: produced_skinned_meshes,
-                });
-            }
+                /** @type {number[]} the records that draw this mesh's primitives */
+                const produced = [];
 
+                if (primitives.length === 1) {
+                    // the node is the primitive. Its name wins over the mesh's, which is what the
+                    // pose query names parts by; the geometry keeps the mesh's own
+                    const primitive = primitives[0];
 
-            if (node.children !== undefined) {
+                    record.geometry = primitive.geometry;
+                    record.material = primitive.material;
 
-                for (let i = 0; i < node.children.length; i++) {
-                    const node_index = node.children[i];
+                    if (node.name === undefined) {
+                        record.name = primitive.name;
+                    }
+
+                    produced.push(index);
+                } else {
+                    // one child per primitive, each named after the mesh, at the node's own place
+                    for (let i = 0; i < primitives.length; i++) {
+                        const primitive = primitives[i];
+                        const child = new SceneNode();
+
+                        child.parent = index;
+                        child.name = primitive.name;
+                        child.geometry = primitive.geometry;
+                        child.material = primitive.material;
 
-                    process_node(node3d, node_index);
+                        produced.push(bundle.add_node(child));
+                    }
                 }
-            }
-        }
 
-        // console.time('parse-gltf');
-        // console.profile('parse-gltf');
+                if (skin_index !== -1 && produced.length > 0) {
+                    skin_mesh_pushes.push({
+                        skin_index,
+                        meshes: produced,
+                    });
+                }
+            }
 
-        /**
-         *
-         * @type {Node3D[]}
-         */
-        const scene_nodes3d = [];
+            if (node.children !== undefined) {
+                for (let i = 0; i < node.children.length; i++) {
+                    process_node(index, node.children[i]);
+                }
+            }
+        }
 
         for (let i = 0; i < scenes.length; i++) {
             const scene = scenes[i];
 
-            const scene_node3d = new Node3D();
-
-            scene_nodes3d.push(scene_node3d);
+            // a root per glTF scene, unnamed and at the identity — what the prefab compiler folds
+            const scene_root = bundle.add_node(new SceneNode());
 
             /**
              * @type {number[]}
              */
             const scene_nodes = scene.nodes;
-
             const node_count = scene_nodes.length;
 
             for (let i = 0; i < node_count; i++) {
-                const node_index = scene_nodes[i];
-                process_node(scene_node3d, node_index);
+                process_node(scene_root, scene_nodes[i]);
             }
-
-            scene_node3d.updateMatrices();
         }
 
         // ── Skins ──────────────────────────────────────────────────
         //
         // Build {@link Skin} objects from `gltf.skins[]`. Joints
-        // resolve to Node3D refs through `node3d_by_index` (fully
+        // resolve to node indices through `record_index_of` (fully
         // populated by the recursion above). Inverse-bind matrices
         // come from a single MAT4 accessor — `joint_count * 16` f32s
         // laid out column-major, copied into a flat Float32Array that
@@ -903,10 +878,10 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
             const joint_nodes = new Array(joint_count);
             for (let i = 0; i < joint_count; i++) {
                 const joint_node_index = joint_indices[i];
-                const joint_node = node3d_by_index[joint_node_index];
+                const joint_node = record_index_of[joint_node_index];
 
-                assert.defined(
-                    joint_node,
+                assert.notEqual(
+                    joint_node, -1,
                     `skin[${skin_index}].joints[${i}] references unknown node index ${joint_node_index}`
                 );
 
@@ -954,6 +929,9 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
         // (values) accessors via the engine's curve_from_track_data
         // helpers, which already handle STEP / LINEAR / CUBICSPLINE.
         const clips = [];
+
+        /** @type {{light: import("../../light/model/Light.js").Light, node: number}[]} */
+        const punctual_lights = [];
         const gltf_animations = gltf.animations ?? [];
         for (let a = 0; a < gltf_animations.length; a++) {
             const gltf_animation = gltf_animations[a];
@@ -976,10 +954,10 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
                     continue;
                 }
 
-                const target_node = node3d_by_index[target.node];
+                const target_node = record_index_of[target.node];
 
-                assert.defined(
-                    target_node,
+                assert.notEqual(
+                    target_node, -1,
                     `animations[${a}].channels[${c}].target.node ${target.node} not resolved`
                 );
 
@@ -1017,7 +995,7 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
                 if (property === Node3DProperty.Rotation && times.length >= 1) {
                     // `canonicalize_quaternion_signs` reads the rest rotation by component name,
                     // which a `Transform64` does not offer — hand it a quaternion instead
-                    const rest = target_node.transform_local;
+                    const rest = bundle.nodes[target_node].local;
 
                     SCRATCH_REST_ROTATION.set(
                         rest.rotation_x,
@@ -1084,7 +1062,7 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
                 before_curves += clip.channels[i].curve_count;
             }
 
-            clip.optimize();
+            clip.optimize(target => bundle.nodes[target].local);
 
             const after_channels = clip.channels.length;
             let after_curves = 0;
@@ -1108,35 +1086,25 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
         // console.profileEnd('parse-gltf');
         // console.timeEnd('parse-gltf');
 
-        const bundle = new SceneBundle();
-        bundle.scenes = scene_nodes3d;
         bundle.skins = skins;
         bundle.clips = clips;
+        bundle.lights = punctual_lights;
         return bundle;
     }
 
     /**
-     *
-     * @param {Node3D[]} scenes
+     * @param {SceneBundle} bundle
      */
-    function fix_scene_material_sidedness(scenes) {
-        const meshes = new Set();
+    function fix_scene_material_sidedness(bundle) {
+        const meshes = bundle.nodes.filter(node => node.geometry !== null);
 
-        for (const s of scenes) {
-            s.traverse(node => {
-                if (node.isMesh) {
-                    meshes.add(node);
-                }
-            });
-        }
-
-        const { geometries_modified: fixed_count, primitives_delta } = fix_up_material_sides(Array.from(meshes));
+        const { geometries_modified: fixed_count, primitives_delta } = fix_up_material_sides(meshes);
 
         if (fixed_count > 0) {
             console.warn(`Fixed ${fixed_count} geometries in accordance with material sidedness. Primitives added: ${number_format_by_thousands(primitives_delta)}`);
         }
 
-        return scenes;
+        return bundle;
     }
 
 

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#232@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#240@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/loader/usd/UsdExtensionRegistry.d.ts

@@ -7,9 +7,9 @@
  *
  * @typedef {Object} UsdExtension
  * @property {string} name - Unique extension name
- * @property {function(string, Object, Object):Node3D|null} [processPrim]
+ * @property {function(string, Object, Object):SceneNode|null} [processPrim]
  *     Custom prim handler. Receives (primPath, primFields, buildContext).
- *     Return a Node3D to override default handling, or null to skip.
+ *     Return a SceneNode to be added under the prim's parent, or null for default handling.
  * @property {function(Object):void} [postProcess]
  *     Post-process hook. Receives the full specsByPath after initial parsing.
  */
@@ -64,9 +64,9 @@ export type UsdExtension = {
     name: string;
     /**
      * Custom prim handler. Receives (primPath, primFields, buildContext).
-     * Return a Node3D to override default handling, or null to skip.
+     * Return a SceneNode to be added under the prim's parent, or null for default handling.
      */
-    processPrim?: (arg0: string, arg1: any, arg2: any) => Node3D | null;
+    processPrim?: (arg0: string, arg1: any, arg2: any) => SceneNode | null;
     /**
      * Post-process hook. Receives the full specsByPath after initial parsing.
      */

package/src/shade/renderer/loader/usd/UsdExtensionRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UsdExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/UsdExtensionRegistry.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;IAEI;;;OAGG;IACH,oBAAwB;IAExB;;;;OAIG;IACH,eAHW,MAAM,aACN,YAAY,QAItB;IAED;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAIlC;IAED;;OAEG;IACH,UAFa,iBAAiB,YAAY,CAAC,CAI1C;IAED;;OAEG;IACH,mBAEC;CACJ;AAED;;;GAGG;AACH,uCAFU,oBAAoB,CAEqC;;;;;;;;;;;;UA5DrD,MAAM;;;;;yBACG,MAAM,2BAAkB,SAAO,IAAI;;;;iCAG3B,IAAI"}
+{"version":3,"file":"UsdExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/UsdExtensionRegistry.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;IAEI;;;OAGG;IACH,oBAAwB;IAExB;;;;OAIG;IACH,eAHW,MAAM,aACN,YAAY,QAItB;IAED;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAIlC;IAED;;OAEG;IACH,UAFa,iBAAiB,YAAY,CAAC,CAI1C;IAED;;OAEG;IACH,mBAEC;CACJ;AAED;;;GAGG;AACH,uCAFU,oBAAoB,CAEqC;;;;;;;;;;;;UA5DrD,MAAM;;;;;yBACG,MAAM,2BAAkB,YAAU,IAAI;;;;iCAG9B,IAAI"}

package/src/shade/renderer/loader/usd/UsdExtensionRegistry.js

@@ -7,9 +7,9 @@
  *
  * @typedef {Object} UsdExtension
  * @property {string} name - Unique extension name
- * @property {function(string, Object, Object):Node3D|null} [processPrim]
+ * @property {function(string, Object, Object):SceneNode|null} [processPrim]
  *     Custom prim handler. Receives (primPath, primFields, buildContext).
- *     Return a Node3D to override default handling, or null to skip.
+ *     Return a SceneNode to be added under the prim's parent, or null for default handling.
  * @property {function(Object):void} [postProcess]
  *     Post-process hook. Receives the full specsByPath after initial parsing.
  */

package/src/shade/renderer/loader/usd/load_usd.d.ts

@@ -7,11 +7,12 @@
  *
  * @param {ArrayBuffer} buffer — Raw file bytes
  * @param {LoadUsdOptions} [options]
- * @returns {Promise<import("../../scene/Node3D.js").Node3D[]>} Root scene nodes
+ * @returns {Promise<import("../SceneBundle.js").SceneBundle>} the model — its nodes in pre-order; no
+ *          skins and no clips, which UsdSkel would fill in
  * @throws {UsdParseError} On malformed data
  * @throws {UsdUnsupportedError} On unsupported format (e.g. USDC before implementation)
  */
-export function load_usd(buffer: ArrayBuffer, options?: LoadUsdOptions): Promise<import("../../scene/Node3D.js").Node3D[]>;
+export function load_usd(buffer: ArrayBuffer, options?: LoadUsdOptions): Promise<import("../SceneBundle.js").SceneBundle>;
 export type LoadUsdOptions = {
     /**
      * — Original file name (used for format detection)

package/src/shade/renderer/loader/usd/load_usd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_usd.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/load_usd.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;GAYG;AACH,iCANW,WAAW,YACX,cAAc,GACZ,QAAQ,OAAO,uBAAuB,EAAE,MAAM,EAAE,CAAC,CAwE7D;;;;;eA5Ga,MAAM;;;;iBACN,oBAAoB;;qCAN6B,2BAA2B"}
+{"version":3,"file":"load_usd.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/load_usd.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;GAaG;AACH,iCAPW,WAAW,YACX,cAAc,GACZ,QAAQ,OAAO,mBAAmB,EAAE,WAAW,CAAC,CAuE5D;;;;;eA3Ga,MAAM;;;;iBACN,oBAAoB;;qCAN6B,2BAA2B"}

package/src/shade/renderer/loader/usd/load_usd.js

@@ -64,7 +64,8 @@ const USDA_HEADER = "#usda ";
  *
  * @param {ArrayBuffer} buffer — Raw file bytes
  * @param {LoadUsdOptions} [options]
- * @returns {Promise<import("../../scene/Node3D.js").Node3D[]>} Root scene nodes
+ * @returns {Promise<import("../SceneBundle.js").SceneBundle>} the model — its nodes in pre-order; no
+ *          skins and no clips, which UsdSkel would fill in
  * @throws {UsdParseError} On malformed data
  * @throws {UsdUnsupportedError} On unsupported format (e.g. USDC before implementation)
  */
@@ -132,10 +133,8 @@ export async function load_usd(buffer, options = {}) {
         }
     }
 
-    // Build scene
-    const nodes = usd_build_scene(parsed.specsByPath, { assetFiles: asset_files, extensions: registry });
-
-    return nodes;
+    // Build the model
+    return usd_build_scene(parsed.specsByPath, { assetFiles: asset_files, extensions: registry });
 }