@woosh/meep-engine 3.14.2 → 3.14.4

package/src/engine/asset/GameAssetType.d.ts

@@ -5,6 +5,7 @@ export type GameAssetType = string;
 export namespace GameAssetType {
     let ModelGLTF: string;
     let ModelGLTF_JSON: string;
+    let ModelUSD: string;
     let ArrayBuffer: string;
     let Texture: string;
     let DeferredTexture: string;

package/src/engine/asset/GameAssetType.js

@@ -5,6 +5,14 @@
 export const GameAssetType = {
     ModelGLTF: "model/gltf",
     ModelGLTF_JSON: "model/gltf+json",
+    /**
+     * Every USD flavour — `.usd`, `.usda`, `.usdc`, `.usdz` — under the one type. The registry also
+     * lists `model/vnd.usdz+zip` for the archive, but a container is not a second kind of asset
+     * here: `load_usd` reads the magic bytes and tells the flavours apart itself, so one type means
+     * one loader to register and one cache key shape for a file whose extension says less than its
+     * bytes do.
+     */
+    ModelUSD: "model/vnd.usd",
     ArrayBuffer: "arraybuffer",
     /**
      * No loader produces one. Both texture types meant a three `Texture` — a renderer's own object

package/src/engine/asset/codec/DecodedImage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What every image codec in the asset tier hands back, whichever format it read.
+ *
+ * One shape rather than three: the worker returned `{data, width, height, itemSize, bitDepth}` with
+ * `data` an `ArrayBuffer` for the transfer, the canvas path returned the same fields around a
+ * `Uint8ClampedArray`, and the JPEG decoder returned `{data, width, height, exifBuffer}` with neither
+ * `itemSize` nor `bitDepth` — so the loader that consumed them knew which codec it had spoken to. It
+ * should not have to. Naming the record is what lets {@link CodecWithFallback } hand any of its
+ * children's answers up unchanged.
+ *
+ * `data` is the samples, interleaved, `itemSize` per texel, row-major, no padding. It is either the
+ * bytes themselves (an `ArrayBuffer`, as a worker transfers them) or a typed view of them; a consumer
+ * that needs one or the other wraps it — `new Uint8Array(data)` accepts both. Which typed view is
+ * right follows from `bitDepth`: 8 and below is one byte per sample (sub-byte depths are expanded on
+ * the way out), 16 is `Uint16` in platform byte order.
+ */
+type DecodedImage = {
+    /**
+     * interleaved samples
+     */
+    data: ArrayBuffer | ArrayBufferView;
+    /**
+     * texels
+     */
+    width: number;
+    /**
+     * texels
+     */
+    height: number;
+    /**
+     * channels per texel — 1, 2, 3 or 4
+     */
+    itemSize: number;
+    /**
+     * bits per sample — 1, 2, 4, 8 or 16
+     */
+    bitDepth: number;
+};
+//# sourceMappingURL=DecodedImage.d.ts.map

package/src/engine/asset/codec/DecodedImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecodedImage.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/codec/DecodedImage.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;UAiBc,WAAW,GAAC,eAAe;;;;WAC3B,MAAM;;;;YACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM"}

package/src/engine/asset/codec/DecodedImage.js

@@ -0,0 +1,26 @@
+/**
+ * What every image codec in the asset tier hands back, whichever format it read.
+ *
+ * One shape rather than three: the worker returned `{data, width, height, itemSize, bitDepth}` with
+ * `data` an `ArrayBuffer` for the transfer, the canvas path returned the same fields around a
+ * `Uint8ClampedArray`, and the JPEG decoder returned `{data, width, height, exifBuffer}` with neither
+ * `itemSize` nor `bitDepth` — so the loader that consumed them knew which codec it had spoken to. It
+ * should not have to. Naming the record is what lets {@link CodecWithFallback} hand any of its
+ * children's answers up unchanged.
+ *
+ * `data` is the samples, interleaved, `itemSize` per texel, row-major, no padding. It is either the
+ * bytes themselves (an `ArrayBuffer`, as a worker transfers them) or a typed view of them; a consumer
+ * that needs one or the other wraps it — `new Uint8Array(data)` accepts both. Which typed view is
+ * right follows from `bitDepth`: 8 and below is one byte per sample (sub-byte depths are expanded on
+ * the way out), 16 is `Uint16` in platform byte order.
+ *
+ * @typedef {object} DecodedImage
+ * @property {ArrayBuffer|ArrayBufferView} data interleaved samples
+ * @property {number} width texels
+ * @property {number} height texels
+ * @property {number} itemSize channels per texel — 1, 2, 3 or 4
+ * @property {number} bitDepth bits per sample — 1, 2, 4, 8 or 16
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */

package/src/engine/asset/guessAssetType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guessAssetType.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/guessAssetType.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAwCvB"}
+{"version":3,"file":"guessAssetType.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/guessAssetType.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAkDvB"}

package/src/engine/asset/guessAssetType.js

@@ -32,9 +32,19 @@ export function guessAssetType(url) {
             return 'model/gltf+json';
         case 'glb':
             return 'model/gltf';
+        /*
+         One type for all four: `load_usd` detects the flavour from the file's own magic bytes, so
+         the extension only has to say "this is USD" — see `GameAssetType.ModelUSD`.
+        */
+        case 'usd':
+        case 'usda':
+        case 'usdc':
+        case 'usdz':
+            return 'model/vnd.usd';
         case "jpg":
         case "jpeg":
         case "png":
+        case "avif":
             return "image";
         case "ogg":
         case "mp3":

package/src/engine/asset/load_model_scene_bundle.d.ts

@@ -8,7 +8,7 @@
  * preload filled.
  *
  * @param {AssetManager} assetManager
- * @param {string} url `.gltf` or `.glb`
+ * @param {string} url `.gltf`, `.glb`, or any USD flavour — `.usd`, `.usda`, `.usdz`
  * @returns {Promise<SceneBundle>} the loaded model itself, shared by every caller — see
  * {@link GLTFSceneBundleAssetLoader}
  */

package/src/engine/asset/load_model_scene_bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_model_scene_bundle.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/load_model_scene_bundle.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,yEAJW,MAAM,GACJ,oBAAoB,CAWhC"}
+{"version":3,"file":"load_model_scene_bundle.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/load_model_scene_bundle.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,yEAJW,MAAM,GACJ,oBAAoB,CAehC"}

package/src/engine/asset/load_model_scene_bundle.js

@@ -12,14 +12,18 @@ import { guessAssetType } from "./guessAssetType.js";
  * preload filled.
  *
  * @param {AssetManager} assetManager
- * @param {string} url `.gltf` or `.glb`
+ * @param {string} url `.gltf`, `.glb`, or any USD flavour — `.usd`, `.usda`, `.usdz`
  * @returns {Promise<SceneBundle>} the loaded model itself, shared by every caller — see
  * {@link GLTFSceneBundleAssetLoader}
  */
 export async function load_model_scene_bundle(assetManager, url) {
     const type = guessAssetType(url);
 
-    assert.isOneOf(type, [GameAssetType.ModelGLTF, GameAssetType.ModelGLTF_JSON], `asset type of '${url}'`);
+    assert.isOneOf(
+        type,
+        [GameAssetType.ModelGLTF, GameAssetType.ModelGLTF_JSON, GameAssetType.ModelUSD],
+        `asset type of '${url}'`
+    );
 
     const asset = await assetManager.promise(url, type);
 

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A USD file — `.usd`, `.usda`, `.usdz`, and `.usdc` once there is a crate parser — as Shade's own
+ * representation of it: a {@link SceneBundle} holding the scene roots that came out of the one file.
+ *
+ * The door {@link GLTFSceneBundleAssetLoader} is for glTF. Without it `load_usd` is reachable only by
+ * a caller who has already got the bytes, which is nothing the engine does: every other model in this
+ * engine arrives through the asset framework, by url and by type.
+ *
+ * The bytes come back through the manager as an {@link GameAssetType.ArrayBuffer} under this load's
+ * scope, rather than through `fetch` here, so a USD file two placements share is downloaded once and
+ * one a preload warmed is already in memory. The whole file is one request — a `.usdz` carries its
+ * textures inside the archive, and a `.usda` referencing external layers is not something `load_usd`
+ * resolves — so unlike the glTF loader there is no second tier of nested requests.
+ *
+ * The asset hands out **that same bundle** to every caller rather than a copy, for the reason
+ * {@link GLTFSceneBundleAssetLoader} gives: a bundle is the model as loaded, not a placement of it,
+ * and {@link instantiate_scene_bundle} is what makes a placement's private copy.
+ *
+ * @extends AssetLoader<*, SceneBundle>
+ */
+export class USDSceneBundleAssetLoader extends AssetLoader<any, SceneBundle> {
+    constructor();
+    /**
+     * @param {AssetRequestScope} scope
+     * @param {string} path
+     * @param {function(Asset): void} success
+     * @param {function} failure
+     * @param {function(number, number): void} progress forwarded to the byte request: one USD file
+     * is one download, so its progress is this asset's progress exactly
+     * @returns {Promise<Asset>}
+     */
+    load(scope: AssetRequestScope, path: string, success: (arg0: Asset<any>) => void, failure: Function, progress: (arg0: number, arg1: number) => void): Promise<Asset<any>>;
+}
+import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
+import { AssetLoader } from "./AssetLoader.js";
+import { Asset } from "../Asset.js";
+//# sourceMappingURL=USDSceneBundleAssetLoader.d.ts.map

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"USDSceneBundleAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/loaders/USDSceneBundleAssetLoader.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;IAoBI;;;;;;;;OAQG;IACH,qCAPW,MAAM,iCACW,IAAI,sCAEZ,MAAM,QAAE,MAAM,KAAG,IAAI,GAE5B,mBAAc,CAgD1B;CACJ;4BAtG2B,+CAA+C;4BAI/C,kBAAkB;sBAHxB,aAAa"}

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.js

@@ -0,0 +1,104 @@
+import { load_usd } from "../../../shade/renderer/loader/usd/load_usd.js";
+import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
+import { Asset } from "../Asset.js";
+import { GameAssetType } from "../GameAssetType.js";
+import { ArrayBufferLoader } from "./ArrayBufferLoader.js";
+import { AssetLoader } from "./AssetLoader.js";
+
+/**
+ * A USD file — `.usd`, `.usda`, `.usdz`, and `.usdc` once there is a crate parser — as Shade's own
+ * representation of it: a {@link SceneBundle} holding the scene roots that came out of the one file.
+ *
+ * The door {@link GLTFSceneBundleAssetLoader} is for glTF. Without it `load_usd` is reachable only by
+ * a caller who has already got the bytes, which is nothing the engine does: every other model in this
+ * engine arrives through the asset framework, by url and by type.
+ *
+ * The bytes come back through the manager as an {@link GameAssetType.ArrayBuffer} under this load's
+ * scope, rather than through `fetch` here, so a USD file two placements share is downloaded once and
+ * one a preload warmed is already in memory. The whole file is one request — a `.usdz` carries its
+ * textures inside the archive, and a `.usda` referencing external layers is not something `load_usd`
+ * resolves — so unlike the glTF loader there is no second tier of nested requests.
+ *
+ * The asset hands out **that same bundle** to every caller rather than a copy, for the reason
+ * {@link GLTFSceneBundleAssetLoader} gives: a bundle is the model as loaded, not a placement of it,
+ * and {@link instantiate_scene_bundle} is what makes a placement's private copy.
+ *
+ * @extends AssetLoader<*, SceneBundle>
+ */
+export class USDSceneBundleAssetLoader extends AssetLoader {
+
+    /**
+     * The file's bytes are asked of the manager, so the manager has to be able to serve them. Every
+     * other loader that reads raw bytes registers the fallback the same way — see
+     * {@link ImageRGBADataLoader#link} — because a shell that registers this loader and forgets
+     * `ArrayBuffer` otherwise fails at the first model rather than at startup.
+     *
+     * @param {AssetManager} assetManager
+     * @param {*} engine
+     */
+    async link(assetManager, engine) {
+
+        if (assetManager.getLoaderByType(GameAssetType.ArrayBuffer) === undefined) {
+            await assetManager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
+        }
+
+        await super.link(assetManager, engine);
+    }
+
+    /**
+     * @param {AssetRequestScope} scope
+     * @param {string} path
+     * @param {function(Asset): void} success
+     * @param {function} failure
+     * @param {function(number, number): void} progress forwarded to the byte request: one USD file
+     * is one download, so its progress is this asset's progress exactly
+     * @returns {Promise<Asset>}
+     */
+    async load(scope, path, success, failure, progress) {
+
+        /*
+         Un-resolved, like the glTF loader's: resolving here would hand the manager a network path to
+         key its cache on, and the preload that warmed it used the caller-facing one.
+        */
+        const bytes = await this.assetManager.promise(path, GameAssetType.ArrayBuffer, {
+            scope,
+            progress
+        });
+
+        /**
+         * @type {ArrayBuffer}
+         */
+        const buffer = bytes.create();
+
+        /*
+         Every USD flavour announces itself in its first bytes — a zip's "PK", "PXR-USDC", "#usda "
+         — and `load_usd` reads those before it looks at the name at all. The name is what is left
+         when none of them match: a text layer behind a byte order mark, or a `.usd` that is text by
+         convention. Passing the whole path is fine, the detection takes the extension off it.
+        */
+        const roots = await load_usd(buffer, { fileName: path });
+
+        const bundle = new SceneBundle();
+
+        bundle.scenes = roots;
+
+        /*
+         `usd_build_scene` produces neither skins nor clips: UsdSkel and the time-sampled attributes a
+         clip would come from are not read. Empty is the truth about what came out of the file, not a
+         placeholder — when USD animation lands, it lands by filling these in.
+        */
+        bundle.skins = [];
+        bundle.clips = [];
+
+        /*
+         There is no honest byte size to report, for the reason {@link GLTFSceneBundleAssetLoader}
+         gives: `1` is what every model asset in this engine carries, and the preloader's arithmetic
+         counts on it.
+        */
+        const asset = new Asset(() => bundle, 1);
+
+        success(asset);
+
+        return asset;
+    }
+}