@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/renderer/loader/gltf/tiny-gltf.js

@@ -1,646 +1,646 @@
-import { gltf_apply_buffer_view_extensions } from "./ext/gltf_apply_buffer_view_extensions.js";
-import { GLTF_BUFFER_VIEW_EXTENSIONS } from "./ext/gltf_buffer_view_extensions.js";
-import { gltf_node_world_matrices, gltf_root_nodes } from "./gltf_node_world_matrices.js";
-import { gltf_parse_container, gltf_require_supported_version } from "./gltf_parse_container.js";
-import { gltf_used_image_indices } from "./gltf_used_image_indices.js";
-/**
- * TinyGltf
- * Loads glTF 2.0 file, resolves buffer and image dependencies, and computes node world transforms and aabbs.
- * This is a VERY simplified glTF loader that avoids doing too much work for you.
- * It should generally not be used outside of simple tutorials or examples.
- *
- * What it adds over the container-level readers beside it is **resolution**: buffers and images are
- * fetched through the {@link AssetManager}, decoded, and written back into the document. Splitting
- * the container, reading an accessor and walking the node graph are all questions of the format
- * rather than of where the bytes come from, and live in their own modules so that a caller with no
- * asset framework - the virtual-geometry builder, running under node - can use them too.
- */
-
-import { assert } from "../../../../core/assert.js";
-import { aabb3_array_combine } from "../../../../core/geom/3d/aabb/aabb3_array_combine.js";
-import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
-import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
-import { GameAssetType } from "../../../../engine/asset/GameAssetType.js";
-
-/**
- * glTF's default texture wrap mode, by its own number.
- * @type {number}
- */
-const GLTF_WRAP_REPEAT = 10497;
-
-/**
- * What a buffer the file never wrote resolves to - a placeholder some extension declares.
- * Zero length rather than the declared one: a well-formed file reads none of it, and a malformed one
- * fails loudly on the first accessor instead of quietly rendering a megabyte of zeroes.
- * @type {Uint8Array}
- */
-const EMPTY_BUFFER = new Uint8Array(0);
-
-const DEFAULT_TRANSLATION = [0, 0, 0];
-const DEFAULT_ROTATION = [0, 0, 0, 1];
-const DEFAULT_SCALE = [1, 1, 1];
-
-/**
- * A URI that names its own scheme, by RFC 3986's rule for one.
- *
- * Every scheme rather than the page's: built from `window.location.protocol`, this called an
- * `https:` asset on an `http:` page relative — and a `blob:` or a `data:` likewise — and answered it
- * with the model's own directory glued to the front.
- *
- * @type {RegExp}
- */
-const ABSOLUTE_URI = /^[a-z][a-z0-9+.-]*:/i;
-
-/**
- * Protocol-relative, which names no scheme and is absolute all the same.
- * @type {RegExp}
- */
-const PROTOCOL_RELATIVE_URI = /^\/\//;
-
-function resolveUri(uri, baseUrl) {
-    if (ABSOLUTE_URI.test(uri) || PROTOCOL_RELATIVE_URI.test(uri)) {
-        return uri;
-    }
-    return baseUrl + uri;
-}
-
-/**
- * A resolved buffer, in the form the document exposes it.
- *
- * `Uint8Array` rather than `ArrayBuffer` throughout: a buffer is a *range* of bytes, and a `.glb`'s
- * binary chunk is a range of the file it arrived in. Carrying the offset with the bytes is what lets
- * that chunk be handed on without copying it, and it is the only form an accessor can be read out of
- * without caring how the container happened to be aligned.
- *
- * @param {ArrayBuffer} array_buffer
- * @returns {Uint8Array}
- */
-function as_bytes(array_buffer) {
-    return new Uint8Array(array_buffer);
-}
-
-/*
- Very simple AABB tracking so that we can position cameras sensibly.
-
- A box is six numbers — `[x0, y0, z0, x1, y1, z1]`, min before max — which is the layout every
- `aabb3_*` function in `core/geom/3d/aabb` reads and writes. There is no box object because nothing
- downstream asks for one: a mesh, a node and a scene each carry their bounds so that a camera can
- be pointed at the model, and the six numbers are the whole of that.
-*/
-
-/**
- * Scratch for one accessor's authored bounds, read as a box.
- *
- * Module scope rather than per primitive: it is filled and consumed by two adjacent statements
- * of a walk that never awaits, so no second accessor can be in flight while one is being read.
- *
- * @type {Float64Array}
- */
-const ACCESSOR_BOUNDS_SCRATCH = new Float64Array(6);
-
-/**
- * A box that bounds nothing, so that the first union with it yields the other operand whole.
- *
- * The bounds are inverted for that: `+Infinity` min against `-Infinity` max. The class this replaced
- * seeded its max with `Number.MIN_VALUE`, which is the smallest *positive* double rather than the most
- * negative one — a mesh living entirely below the origin came out of it with a max pinned near zero,
- * and a box that did not contain the mesh.
- *
- * `Float64Array` because glTF authors accessor bounds as JSON doubles, and these are combined and
- * transformed all the way up the node graph before anyone reads them.
- *
- * @returns {Float64Array} six numbers, `[x0, y0, z0, x1, y1, z1]`
- */
-function aabb3_allocate_empty() {
-    const result = new Float64Array(6);
-
-    aabb3_array_set(
-        result, 0,
-        Infinity, Infinity, Infinity,
-        -Infinity, -Infinity, -Infinity
-    );
-
-    return result;
-}
-
-/**
- * Whether a box bounds anything at all, as opposed to being the empty one {@link aabb3_allocate_empty}
- * hands out.
- *
- * Worth asking before transforming one: the empty box's bounds are infinite, and an infinity met
- * by one of the matrix's zeroes is a NaN, which then spreads into every box above it in the graph.
- *
- * @param {Float64Array|number[]} box six numbers
- * @returns {boolean}
- */
-function aabb3_is_bounded(box) {
-    return box[0] <= box[3] && box[1] <= box[4] && box[2] <= box[5];
-}
-
-
-/**
- * Give every node the graph reaches its world matrix and its normal matrix.
- *
- * @param {{nodes?:object[], scenes?:object[]}} gltf
- */
-function set_node_matrices(gltf) {
-    const world_matrices = gltf_node_world_matrices(gltf);
-
-    const nodes = gltf.nodes ?? [];
-
-    for (let index = 0; index < nodes.length; index++) {
-        const world = world_matrices[index];
-
-        if (world === undefined) {
-            // a node no root reaches is placed by nothing, and has no world transform to speak of
-            continue;
-        }
-
-        const node = nodes[index];
-
-        node.worldMatrix = world;
-
-        /*
-         The normal matrix — the one that carries a *normal* rather than a point, since a normal does
-         not ride the transform itself wherever that transform is not a similarity: a non-uniform
-         scale tilts a surface one way and its normal the other.
-
-         Meep's own primitive, and a 3x3: the cofactor of the linear part, which points where the
-         inverse transpose points without inverting anything. So it reads no translation (a direction
-         has no position) and it has an answer for a transform with an axis scaled to nothing, where
-         an inverse does not exist — the gl-matrix code this replaced handed that case's `null`
-         straight on to `mat4.transpose` and threw. Vectors come out of it unnormalized; that is the
-         method, not a defect.
-        */
-        node.normalMatrix = new Float32Array(9);
-
-        m4_normal_matrix3(node.normalMatrix, world);
-    }
-}
-
-/**
- * The box a mesh's own vertices occupy, in model space, computed once and kept on the mesh.
- *
- * Read off the accessors' authored bounds rather than the vertex data: the spec requires them on a
- * POSITION accessor, and this runs before a single buffer has resolved.
- *
- * @param {{accessors?:object[]}} gltf
- * @param {{primitives:object[], aabb?:Float64Array}} mesh
- * @returns {Float64Array} six numbers, and unbounded when no primitive declared any
- */
-function mesh_bounds(gltf, mesh) {
-    if (mesh.aabb !== undefined) {
-        return mesh.aabb;
-    }
-
-    const result = aabb3_allocate_empty();
-
-    mesh.aabb = result;
-
-    for (const primitive of mesh.primitives) {
-        const accessor = gltf.accessors[primitive.attributes.POSITION];
-
-        const min = accessor?.min;
-        const max = accessor?.max;
-
-        /*
-         The spec requires bounds on a POSITION accessor, and a file that omits them is one this can
-         say nothing about. A primitive contributing no bounds is a better answer than six NaNs
-         poisoning every box above it.
-        */
-        if (min === undefined || max === undefined || min.length < 3 || max.length < 3) {
-            continue;
-        }
-
-        aabb3_array_set(
-            ACCESSOR_BOUNDS_SCRATCH, 0,
-            min[0], min[1], min[2],
-            max[0], max[1], max[2]
-        );
-
-        aabb3_array_combine(result, 0, result, 0, ACCESSOR_BOUNDS_SCRATCH, 0);
-    }
-
-    return result;
-}
-
-/**
- * Grow whatever box `holder` carries so that it also holds `addition`, giving it one if it had none.
- *
- * @param {{aabb?:Float64Array}} holder a node or a scene
- * @param {Float64Array} addition six numbers
- */
-function absorb_bounds(holder, addition) {
-    if (holder.aabb === undefined) {
-        // a copy: a box aliased to a child's would grow with it
-        holder.aabb = new Float64Array(addition);
-
-        return;
-    }
-
-    aabb3_array_combine(holder.aabb, 0, holder.aabb, 0, addition, 0);
-}
-
-/**
- * Bound a node in world space by what it places, and by everything below it.
- *
- * A node reached twice keeps the box of its first visit, the same rule the world matrices follow —
- * so the second parent still spans the child, but does not re-walk the subtree under it.
- *
- * @param {{nodes:object[], meshes?:object[]}} gltf
- * @param {number} index
- * @param {Set<number>} visited
- */
-function set_node_bounds(gltf, index, visited) {
-    if (visited.has(index)) {
-        return;
-    }
-
-    visited.add(index);
-
-    const node = gltf.nodes[index];
-
-    if ('mesh' in node) {
-        const bounds = mesh_bounds(gltf, gltf.meshes[node.mesh]);
-
-        // a mesh whose primitives all declined to declare bounds leaves the node without any
-        if (aabb3_is_bounded(bounds)) {
-            // a fresh box, which is also what `aabb3_matrix4_project` requires: it may not alias its input
-            node.aabb = new Float64Array(6);
-
-            aabb3_matrix4_project(node.aabb, bounds, node.worldMatrix);
-        }
-    }
-
-    for (const child_index of node.children ?? []) {
-        set_node_bounds(gltf, child_index, visited);
-
-        const child = gltf.nodes[child_index];
-
-        if (child.aabb !== undefined) {
-            absorb_bounds(node, child.aabb);
-        }
-    }
-}
-
-/**
- * Place every node, and bound every mesh, node and scene.
- *
- * @param {{nodes?:object[], meshes?:object[], scenes?:object[]}} gltf
- */
-function place_nodes(gltf) {
-    set_node_matrices(gltf);
-
-    const visited = new Set();
-
-    // shared across the scenes, so a node two of them list is measured once and spans both
-    for (const root of gltf_root_nodes(gltf)) {
-        set_node_bounds(gltf, root, visited);
-    }
-
-    for (const scene of gltf.scenes ?? []) {
-        for (const node_index of scene.nodes ?? []) {
-            const node = gltf.nodes[node_index];
-
-            if (node.aabb !== undefined) {
-                absorb_bounds(scene, node.aabb);
-            }
-        }
-    }
-}
-
-export class TinyGltf {
-    loadImageSlots = undefined;
-
-    /**
-     * The bufferView extensions this parser will honour.
-     *
-     * Replaceable so that a caller can add a codec, or take one away, without a loader learning any
-     * extension's name. The default is shared across the process; assign a
-     * {@link GltfBufferViewExtensionSet} of your own rather than adding to it if that matters.
-     *
-     * @type {GltfBufferViewExtensionSet}
-     */
-    bufferViewExtensions = GLTF_BUFFER_VIEW_EXTENSIONS;
-
-    /**
-     * Optional map of relative file paths to Blob/File/ArrayBuffer objects.
-     * When set, buffer and image URIs in the GLTF JSON are resolved from this map
-     * before the asset framework is asked. Enables loading multi-file GLTF bundles from
-     * drag-and-drop or other in-memory sources.
-     *
-     * Keys should match the URI strings in the GLTF JSON (e.g. "scene.bin", "textures/albedo.png").
-     *
-     * @type {Map<string, File|Blob|ArrayBuffer>|undefined}
-     */
-    fileMap = undefined;
-
-    /**
-     * Where every byte this parser reads comes from.
-     *
-     * A glTF is not one file: the container names buffers and images that live beside it, and a
-     * level places models that share them. Asking the framework rather than the network is what
-     * makes a texture two models use one download and one decode, records each request against the
-     * load that caused it, and cancels the lot when the scene that asked goes away.
-     *
-     * @type {AssetManager}
-     */
-    #assetManager;
-
-    /**
-     * The load these requests belong to, or `null` for a caller that is not itself an asset load.
-     *
-     * @type {AssetRequestScope|null}
-     */
-    #scope;
-
-    /**
-     * @param {AssetManager} assetManager
-     * @param {AssetRequestScope} [scope]
-     */
-    constructor(assetManager, scope = null) {
-        assert.defined(assetManager, 'assetManager');
-
-        this.#assetManager = assetManager;
-        this.#scope = scope;
-    }
-
-    /**
-     * The bytes of a file this asset needs, through the framework.
-     *
-     * @param {string} path un-resolved, as the manager takes it
-     * @param {string} type see {@link GameAssetType}
-     * @returns {Promise<*>}
-     */
-    async #read(path, type) {
-        const asset = await this.#assetManager.promise(path, type, { scope: this.#scope });
-
-        return asset.create();
-    }
-
-    /**
-     * @param {string} url `.gltf` or `.glb`, un-resolved — the manager resolves network paths
-     * @returns {Promise<TinyGltf>}
-     */
-    async loadFromUrl(url) {
-        assert.isString(url, 'url');
-
-        const i = url.lastIndexOf('/');
-        const baseUrl = (i !== 0) ? url.substring(0, i + 1) : './';
-
-        /*
-         The container is read as bytes whatever it is called and told apart by its magic number,
-         rather than by an extension. One path instead of three, and it is the only one that was ever
-         correct for a `blob:` url — which is what drag-and-drop produces.
-        */
-        const buffer = await this.#read(url, GameAssetType.ArrayBuffer);
-
-        return this.loadFromBinary(buffer, baseUrl);
-    }
-
-    /**
-     * Load a container that is already in memory, whichever of the two forms it is in.
-     *
-     * @param {ArrayBuffer} arrayBuffer a `.glb`, or the bytes of a `.gltf`
-     * @param {string} baseUrl
-     * @return {Promise<{asset}|*>}
-     */
-    async loadFromBinary(arrayBuffer, baseUrl) {
-        const container = gltf_parse_container(new Uint8Array(arrayBuffer));
-
-        return this.loadFromJson(container.json, baseUrl, container.binary_chunk);
-    }
-
-    /**
-     *
-     * @param {{bufferViews,asset,accessors:[],nodes:[],samplers?:[],buffers:[],materials:[], textures:[], images:[],scenes:[]}} json
-     * @param {string} baseUrl
-     * @param {Uint8Array} [binaryChunk]
-     * @return {Promise<{asset}|*>}
-     */
-    async loadFromJson(json, baseUrl, binaryChunk = null) {
-        if (!baseUrl) {
-            throw new Error('baseUrl must be specified.');
-        }
-
-        gltf_require_supported_version(json);
-
-        // Resolve defaults for as many properties as we can.
-        for (const accessor of json.accessors) {
-            accessor.byteOffset = accessor.byteOffset ?? 0;
-            accessor.normalized = accessor.normalized ?? false;
-        }
-
-        for (const bufferView of json.bufferViews) {
-            bufferView.byteOffset = bufferView.byteOffset ?? 0;
-        }
-
-        for (const node of json.nodes) {
-            if (!node.matrix) {
-                node.rotation = node.rotation ?? DEFAULT_ROTATION;
-                node.scale = node.scale ?? DEFAULT_SCALE;
-                node.translation = node.translation ?? DEFAULT_TRANSLATION;
-            }
-        }
-
-        if (json.samplers) {
-            for (const sampler of json.samplers) {
-                sampler.wrapS = sampler.wrapS ?? GLTF_WRAP_REPEAT;
-                sampler.wrapT = sampler.wrapT ?? GLTF_WRAP_REPEAT;
-            }
-        }
-
-        // Resolve buffers and images first, since these are the only external resources that the file
-        // might reference.
-        // Buffers will be exposed as Uint8Arrays.
-        // Images will be exposed as ImageBitmaps.
-
-        /**
-         * Buffers
-         * @type {Promise<Uint8Array>[]}
-         */
-        const pendingBuffers = [];
-
-        const declaredBuffers = json.buffers ?? [];
-
-        /*
-         A .glb's buffer 0 is its binary chunk and names no URI. The buffers after it are ordinary,
-         and are where an extension that produces its own bufferView bytes puts the placeholder those
-         views point at - so the chunk is a special case of buffer 0, not a reason to stop looking at
-         the rest.
-        */
-        const bufferCount = Math.max(declaredBuffers.length, binaryChunk ? 1 : 0);
-
-        for (let index = 0; index < bufferCount; index++) {
-            if (binaryChunk && index === 0) {
-                pendingBuffers[index] = Promise.resolve(binaryChunk);
-                continue;
-            }
-
-            const buffer = declaredBuffers[index];
-
-            /*
-             A buffer with no URI was never written. Asking for one produced a request for
-             "<baseUrl>undefined", which is how a compressed .gltf with a fallback buffer - the shape
-             gltfpack writes - failed before it read a single accessor.
-            */
-            if (buffer.uri === undefined || this.bufferViewExtensions.is_placeholder_buffer(buffer)) {
-                pendingBuffers[index] = Promise.resolve(EMPTY_BUFFER);
-                continue;
-            }
-
-            // Check fileMap first (enables loading from dropped files)
-            if (this.fileMap) {
-                const file = this.fileMap.get(buffer.uri);
-
-                if (file !== undefined) {
-                    // File or Blob
-                    pendingBuffers[index] = (file instanceof ArrayBuffer)
-                        ? Promise.resolve(new Uint8Array(file))
-                        : file.arrayBuffer().then(as_bytes);
-
-                    continue;
-                }
-            }
-
-            pendingBuffers[index] = this.#read(
-                resolveUri(buffer.uri, baseUrl),
-                GameAssetType.ArrayBuffer
-            ).then(as_bytes);
-        }
-
-        // If the loader has been instructed to only load certain images (such as just baseColorTexture)
-        // then scan through all the materials first and gather the image IDs for only those images.
-        // (This feature really only makes sense for this specific set of samples.)
-        let activeImageSet;
-        if (this.loadImageSlots) {
-            activeImageSet = new Set();
-            for (const material of json.materials) {
-                for (const imageChannel of this.loadImageSlots) {
-                    const texture = material[imageChannel] ?? material.pbrMetallicRoughness[imageChannel];
-                    if (texture !== undefined) {
-                        activeImageSet.add(json.textures[texture.index].source);
-                    }
-                }
-            }
-        } else {
-            /*
-             Only the images something will actually sample. A texture may offer the same picture in
-             several containers — `source` plus an extension — and fetching the ones this loader has
-             already decided against is not merely wasted: `createImageBitmap` rejects on a container
-             the browser cannot decode, and an image nothing was going to sample takes the whole model
-             down with it. The game's level models each carry a DDS beside their PNG for exactly that
-             reason, and not one of them loaded.
-             */
-            activeImageSet = gltf_used_image_indices(json);
-        }
-
-        /**
-         * Images
-         * @type {Promise<ImageBitmap>[]}
-         */
-        const pendingImages = [];
-        for (let index = 0; index < json.images?.length || 0; ++index) {
-            if (activeImageSet && !activeImageSet.has(index)) {
-                continue;
-            }
-            const image = json.images[index];
-
-            /**
-             *
-             * @param {Blob} blob
-             * @return {Promise<ImageBitmap>}
-             */
-            function blob_to_bitmap(blob) {
-                return createImageBitmap(blob, {
-                    // premultiplication is done during texture upload
-                    premultiplyAlpha: "none",
-                })
-            }
-
-            if (image.uri) {
-
-                // Check fileMap first (enables loading from dropped files)
-                if (this.fileMap) {
-                    const file = this.fileMap.get(image.uri);
-
-                    if (file !== undefined) {
-                        const blob = (file instanceof Blob) ? file : new Blob([file]);
-                        pendingImages[index] = blob_to_bitmap(blob);
-                        continue;
-                    }
-                }
-
-                /*
-                 Decoded by the framework rather than here, which is what makes one texture shared
-                 by two models one decode instead of two — the expensive half of loading a model is
-                 its images, and a level places the same handful of them hundreds of times.
-                */
-                pendingImages[index] = this.#read(
-                    resolveUri(image.uri, baseUrl),
-                    GameAssetType.ImageBitmap
-                );
-
-            } else {
-
-                const bufferView = json.bufferViews[image.bufferView];
-
-                const claimed = this.bufferViewExtensions.claim(bufferView, image.bufferView);
-
-                if (claimed !== null) {
-                    /*
-                     Legal to write and pointless to: the payload is a PNG or a JPEG, already
-                     compressed. Decoding it is not implemented, and the alternative to saying so is
-                     handing the image decoder a placeholder buffer's bytes.
-                    */
-                    throw new Error(
-                        `images[${index}] is sourced from a bufferView '${claimed.name}' produces,`
-                        + ` which is not supported`
-                    );
-                }
-
-                pendingImages[index] = pendingBuffers[bufferView.buffer].then((buffer) => {
-
-                    const blob = new Blob(
-                        [buffer.subarray(
-                            bufferView.byteOffset,
-                            bufferView.byteOffset + bufferView.byteLength
-                        )],
-                        { type: image.mimeType }
-                    );
-
-                    return blob_to_bitmap(blob);
-                });
-
-            }
-        }
-
-        // Place every node, and bound every mesh, node and scene, starting at the roots.
-        place_nodes(json);
-
-        // Replace the resolved resources in the JSON structure.
-        const buffers = await Promise.all(pendingBuffers);
-
-        /*
-         Views that some extension produces the bytes for become ordinary ones here, over decoded
-         buffers appended to the list, so that nothing downstream - accessors, sparse accessors, the
-         mesh reader - has to know any of those extensions exist. Nor does this parser: it asks the
-         set what claims a view, and the set is the one place that knows what is implemented.
-
-         Per view, and guarded per view. A file nothing claims - which is nearly all of them - gets
-         its own view objects back by identity and appends no buffer.
-        */
-        json.bufferViews = gltf_apply_buffer_view_extensions(
-            json.bufferViews, buffers, this.bufferViewExtensions
-        );
-
-        json.buffers = buffers;
-        json.images = await Promise.all(pendingImages);
-
-        return json;
-    }
-
-
-}
-
+import { gltf_apply_buffer_view_extensions } from "./ext/gltf_apply_buffer_view_extensions.js";
+import { GLTF_BUFFER_VIEW_EXTENSIONS } from "./ext/gltf_buffer_view_extensions.js";
+import { gltf_node_world_matrices, gltf_root_nodes } from "./gltf_node_world_matrices.js";
+import { gltf_parse_container, gltf_require_supported_version } from "./gltf_parse_container.js";
+import { gltf_used_image_indices } from "./gltf_used_image_indices.js";
+/**
+ * TinyGltf
+ * Loads glTF 2.0 file, resolves buffer and image dependencies, and computes node world transforms and aabbs.
+ * This is a VERY simplified glTF loader that avoids doing too much work for you.
+ * It should generally not be used outside of simple tutorials or examples.
+ *
+ * What it adds over the container-level readers beside it is **resolution**: buffers and images are
+ * fetched through the {@link AssetManager}, decoded, and written back into the document. Splitting
+ * the container, reading an accessor and walking the node graph are all questions of the format
+ * rather than of where the bytes come from, and live in their own modules so that a caller with no
+ * asset framework - the virtual-geometry builder, running under node - can use them too.
+ */
+
+import { assert } from "../../../../core/assert.js";
+import { aabb3_array_combine } from "../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
+import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
+import { GameAssetType } from "../../../../engine/asset/GameAssetType.js";
+
+/**
+ * glTF's default texture wrap mode, by its own number.
+ * @type {number}
+ */
+const GLTF_WRAP_REPEAT = 10497;
+
+/**
+ * What a buffer the file never wrote resolves to - a placeholder some extension declares.
+ * Zero length rather than the declared one: a well-formed file reads none of it, and a malformed one
+ * fails loudly on the first accessor instead of quietly rendering a megabyte of zeroes.
+ * @type {Uint8Array}
+ */
+const EMPTY_BUFFER = new Uint8Array(0);
+
+const DEFAULT_TRANSLATION = [0, 0, 0];
+const DEFAULT_ROTATION = [0, 0, 0, 1];
+const DEFAULT_SCALE = [1, 1, 1];
+
+/**
+ * A URI that names its own scheme, by RFC 3986's rule for one.
+ *
+ * Every scheme rather than the page's: built from `window.location.protocol`, this called an
+ * `https:` asset on an `http:` page relative — and a `blob:` or a `data:` likewise — and answered it
+ * with the model's own directory glued to the front.
+ *
+ * @type {RegExp}
+ */
+const ABSOLUTE_URI = /^[a-z][a-z0-9+.-]*:/i;
+
+/**
+ * Protocol-relative, which names no scheme and is absolute all the same.
+ * @type {RegExp}
+ */
+const PROTOCOL_RELATIVE_URI = /^\/\//;
+
+function resolveUri(uri, baseUrl) {
+    if (ABSOLUTE_URI.test(uri) || PROTOCOL_RELATIVE_URI.test(uri)) {
+        return uri;
+    }
+    return baseUrl + uri;
+}
+
+/**
+ * A resolved buffer, in the form the document exposes it.
+ *
+ * `Uint8Array` rather than `ArrayBuffer` throughout: a buffer is a *range* of bytes, and a `.glb`'s
+ * binary chunk is a range of the file it arrived in. Carrying the offset with the bytes is what lets
+ * that chunk be handed on without copying it, and it is the only form an accessor can be read out of
+ * without caring how the container happened to be aligned.
+ *
+ * @param {ArrayBuffer} array_buffer
+ * @returns {Uint8Array}
+ */
+function as_bytes(array_buffer) {
+    return new Uint8Array(array_buffer);
+}
+
+/*
+ Very simple AABB tracking so that we can position cameras sensibly.
+
+ A box is six numbers — `[x0, y0, z0, x1, y1, z1]`, min before max — which is the layout every
+ `aabb3_*` function in `core/geom/3d/aabb` reads and writes. There is no box object because nothing
+ downstream asks for one: a mesh, a node and a scene each carry their bounds so that a camera can
+ be pointed at the model, and the six numbers are the whole of that.
+*/
+
+/**
+ * Scratch for one accessor's authored bounds, read as a box.
+ *
+ * Module scope rather than per primitive: it is filled and consumed by two adjacent statements
+ * of a walk that never awaits, so no second accessor can be in flight while one is being read.
+ *
+ * @type {Float64Array}
+ */
+const ACCESSOR_BOUNDS_SCRATCH = new Float64Array(6);
+
+/**
+ * A box that bounds nothing, so that the first union with it yields the other operand whole.
+ *
+ * The bounds are inverted for that: `+Infinity` min against `-Infinity` max. The class this replaced
+ * seeded its max with `Number.MIN_VALUE`, which is the smallest *positive* double rather than the most
+ * negative one — a mesh living entirely below the origin came out of it with a max pinned near zero,
+ * and a box that did not contain the mesh.
+ *
+ * `Float64Array` because glTF authors accessor bounds as JSON doubles, and these are combined and
+ * transformed all the way up the node graph before anyone reads them.
+ *
+ * @returns {Float64Array} six numbers, `[x0, y0, z0, x1, y1, z1]`
+ */
+function aabb3_allocate_empty() {
+    const result = new Float64Array(6);
+
+    aabb3_array_set(
+        result, 0,
+        Infinity, Infinity, Infinity,
+        -Infinity, -Infinity, -Infinity
+    );
+
+    return result;
+}
+
+/**
+ * Whether a box bounds anything at all, as opposed to being the empty one {@link aabb3_allocate_empty}
+ * hands out.
+ *
+ * Worth asking before transforming one: the empty box's bounds are infinite, and an infinity met
+ * by one of the matrix's zeroes is a NaN, which then spreads into every box above it in the graph.
+ *
+ * @param {Float64Array|number[]} box six numbers
+ * @returns {boolean}
+ */
+function aabb3_is_bounded(box) {
+    return box[0] <= box[3] && box[1] <= box[4] && box[2] <= box[5];
+}
+
+
+/**
+ * Give every node the graph reaches its world matrix and its normal matrix.
+ *
+ * @param {{nodes?:object[], scenes?:object[]}} gltf
+ */
+function set_node_matrices(gltf) {
+    const world_matrices = gltf_node_world_matrices(gltf);
+
+    const nodes = gltf.nodes ?? [];
+
+    for (let index = 0; index < nodes.length; index++) {
+        const world = world_matrices[index];
+
+        if (world === undefined) {
+            // a node no root reaches is placed by nothing, and has no world transform to speak of
+            continue;
+        }
+
+        const node = nodes[index];
+
+        node.worldMatrix = world;
+
+        /*
+         The normal matrix — the one that carries a *normal* rather than a point, since a normal does
+         not ride the transform itself wherever that transform is not a similarity: a non-uniform
+         scale tilts a surface one way and its normal the other.
+
+         Meep's own primitive, and a 3x3: the cofactor of the linear part, which points where the
+         inverse transpose points without inverting anything. So it reads no translation (a direction
+         has no position) and it has an answer for a transform with an axis scaled to nothing, where
+         an inverse does not exist — the gl-matrix code this replaced handed that case's `null`
+         straight on to `mat4.transpose` and threw. Vectors come out of it unnormalized; that is the
+         method, not a defect.
+        */
+        node.normalMatrix = new Float32Array(9);
+
+        m4_normal_matrix3(node.normalMatrix, world);
+    }
+}
+
+/**
+ * The box a mesh's own vertices occupy, in model space, computed once and kept on the mesh.
+ *
+ * Read off the accessors' authored bounds rather than the vertex data: the spec requires them on a
+ * POSITION accessor, and this runs before a single buffer has resolved.
+ *
+ * @param {{accessors?:object[]}} gltf
+ * @param {{primitives:object[], aabb?:Float64Array}} mesh
+ * @returns {Float64Array} six numbers, and unbounded when no primitive declared any
+ */
+function mesh_bounds(gltf, mesh) {
+    if (mesh.aabb !== undefined) {
+        return mesh.aabb;
+    }
+
+    const result = aabb3_allocate_empty();
+
+    mesh.aabb = result;
+
+    for (const primitive of mesh.primitives) {
+        const accessor = gltf.accessors[primitive.attributes.POSITION];
+
+        const min = accessor?.min;
+        const max = accessor?.max;
+
+        /*
+         The spec requires bounds on a POSITION accessor, and a file that omits them is one this can
+         say nothing about. A primitive contributing no bounds is a better answer than six NaNs
+         poisoning every box above it.
+        */
+        if (min === undefined || max === undefined || min.length < 3 || max.length < 3) {
+            continue;
+        }
+
+        aabb3_array_set(
+            ACCESSOR_BOUNDS_SCRATCH, 0,
+            min[0], min[1], min[2],
+            max[0], max[1], max[2]
+        );
+
+        aabb3_array_combine(result, 0, result, 0, ACCESSOR_BOUNDS_SCRATCH, 0);
+    }
+
+    return result;
+}
+
+/**
+ * Grow whatever box `holder` carries so that it also holds `addition`, giving it one if it had none.
+ *
+ * @param {{aabb?:Float64Array}} holder a node or a scene
+ * @param {Float64Array} addition six numbers
+ */
+function absorb_bounds(holder, addition) {
+    if (holder.aabb === undefined) {
+        // a copy: a box aliased to a child's would grow with it
+        holder.aabb = new Float64Array(addition);
+
+        return;
+    }
+
+    aabb3_array_combine(holder.aabb, 0, holder.aabb, 0, addition, 0);
+}
+
+/**
+ * Bound a node in world space by what it places, and by everything below it.
+ *
+ * A node reached twice keeps the box of its first visit, the same rule the world matrices follow —
+ * so the second parent still spans the child, but does not re-walk the subtree under it.
+ *
+ * @param {{nodes:object[], meshes?:object[]}} gltf
+ * @param {number} index
+ * @param {Set<number>} visited
+ */
+function set_node_bounds(gltf, index, visited) {
+    if (visited.has(index)) {
+        return;
+    }
+
+    visited.add(index);
+
+    const node = gltf.nodes[index];
+
+    if ('mesh' in node) {
+        const bounds = mesh_bounds(gltf, gltf.meshes[node.mesh]);
+
+        // a mesh whose primitives all declined to declare bounds leaves the node without any
+        if (aabb3_is_bounded(bounds)) {
+            // a fresh box, which is also what `aabb3_matrix4_project` requires: it may not alias its input
+            node.aabb = new Float64Array(6);
+
+            aabb3_matrix4_project(node.aabb, bounds, node.worldMatrix);
+        }
+    }
+
+    for (const child_index of node.children ?? []) {
+        set_node_bounds(gltf, child_index, visited);
+
+        const child = gltf.nodes[child_index];
+
+        if (child.aabb !== undefined) {
+            absorb_bounds(node, child.aabb);
+        }
+    }
+}
+
+/**
+ * Place every node, and bound every mesh, node and scene.
+ *
+ * @param {{nodes?:object[], meshes?:object[], scenes?:object[]}} gltf
+ */
+function place_nodes(gltf) {
+    set_node_matrices(gltf);
+
+    const visited = new Set();
+
+    // shared across the scenes, so a node two of them list is measured once and spans both
+    for (const root of gltf_root_nodes(gltf)) {
+        set_node_bounds(gltf, root, visited);
+    }
+
+    for (const scene of gltf.scenes ?? []) {
+        for (const node_index of scene.nodes ?? []) {
+            const node = gltf.nodes[node_index];
+
+            if (node.aabb !== undefined) {
+                absorb_bounds(scene, node.aabb);
+            }
+        }
+    }
+}
+
+export class TinyGltf {
+    loadImageSlots = undefined;
+
+    /**
+     * The bufferView extensions this parser will honour.
+     *
+     * Replaceable so that a caller can add a codec, or take one away, without a loader learning any
+     * extension's name. The default is shared across the process; assign a
+     * {@link GltfBufferViewExtensionSet} of your own rather than adding to it if that matters.
+     *
+     * @type {GltfBufferViewExtensionSet}
+     */
+    bufferViewExtensions = GLTF_BUFFER_VIEW_EXTENSIONS;
+
+    /**
+     * Optional map of relative file paths to Blob/File/ArrayBuffer objects.
+     * When set, buffer and image URIs in the GLTF JSON are resolved from this map
+     * before the asset framework is asked. Enables loading multi-file GLTF bundles from
+     * drag-and-drop or other in-memory sources.
+     *
+     * Keys should match the URI strings in the GLTF JSON (e.g. "scene.bin", "textures/albedo.png").
+     *
+     * @type {Map<string, File|Blob|ArrayBuffer>|undefined}
+     */
+    fileMap = undefined;
+
+    /**
+     * Where every byte this parser reads comes from.
+     *
+     * A glTF is not one file: the container names buffers and images that live beside it, and a
+     * level places models that share them. Asking the framework rather than the network is what
+     * makes a texture two models use one download and one decode, records each request against the
+     * load that caused it, and cancels the lot when the scene that asked goes away.
+     *
+     * @type {AssetManager}
+     */
+    #assetManager;
+
+    /**
+     * The load these requests belong to, or `null` for a caller that is not itself an asset load.
+     *
+     * @type {AssetRequestScope|null}
+     */
+    #scope;
+
+    /**
+     * @param {AssetManager} assetManager
+     * @param {AssetRequestScope} [scope]
+     */
+    constructor(assetManager, scope = null) {
+        assert.defined(assetManager, 'assetManager');
+
+        this.#assetManager = assetManager;
+        this.#scope = scope;
+    }
+
+    /**
+     * The bytes of a file this asset needs, through the framework.
+     *
+     * @param {string} path un-resolved, as the manager takes it
+     * @param {string} type see {@link GameAssetType}
+     * @returns {Promise<*>}
+     */
+    async #read(path, type) {
+        const asset = await this.#assetManager.promise(path, type, { scope: this.#scope });
+
+        return asset.create();
+    }
+
+    /**
+     * @param {string} url `.gltf` or `.glb`, un-resolved — the manager resolves network paths
+     * @returns {Promise<TinyGltf>}
+     */
+    async loadFromUrl(url) {
+        assert.isString(url, 'url');
+
+        const i = url.lastIndexOf('/');
+        const baseUrl = (i !== 0) ? url.substring(0, i + 1) : './';
+
+        /*
+         The container is read as bytes whatever it is called and told apart by its magic number,
+         rather than by an extension. One path instead of three, and it is the only one that was ever
+         correct for a `blob:` url — which is what drag-and-drop produces.
+        */
+        const buffer = await this.#read(url, GameAssetType.ArrayBuffer);
+
+        return this.loadFromBinary(buffer, baseUrl);
+    }
+
+    /**
+     * Load a container that is already in memory, whichever of the two forms it is in.
+     *
+     * @param {ArrayBuffer} arrayBuffer a `.glb`, or the bytes of a `.gltf`
+     * @param {string} baseUrl
+     * @return {Promise<{asset}|*>}
+     */
+    async loadFromBinary(arrayBuffer, baseUrl) {
+        const container = gltf_parse_container(new Uint8Array(arrayBuffer));
+
+        return this.loadFromJson(container.json, baseUrl, container.binary_chunk);
+    }
+
+    /**
+     *
+     * @param {{bufferViews,asset,accessors:[],nodes:[],samplers?:[],buffers:[],materials:[], textures:[], images:[],scenes:[]}} json
+     * @param {string} baseUrl
+     * @param {Uint8Array} [binaryChunk]
+     * @return {Promise<{asset}|*>}
+     */
+    async loadFromJson(json, baseUrl, binaryChunk = null) {
+        if (!baseUrl) {
+            throw new Error('baseUrl must be specified.');
+        }
+
+        gltf_require_supported_version(json);
+
+        // Resolve defaults for as many properties as we can.
+        for (const accessor of json.accessors) {
+            accessor.byteOffset = accessor.byteOffset ?? 0;
+            accessor.normalized = accessor.normalized ?? false;
+        }
+
+        for (const bufferView of json.bufferViews) {
+            bufferView.byteOffset = bufferView.byteOffset ?? 0;
+        }
+
+        for (const node of json.nodes) {
+            if (!node.matrix) {
+                node.rotation = node.rotation ?? DEFAULT_ROTATION;
+                node.scale = node.scale ?? DEFAULT_SCALE;
+                node.translation = node.translation ?? DEFAULT_TRANSLATION;
+            }
+        }
+
+        if (json.samplers) {
+            for (const sampler of json.samplers) {
+                sampler.wrapS = sampler.wrapS ?? GLTF_WRAP_REPEAT;
+                sampler.wrapT = sampler.wrapT ?? GLTF_WRAP_REPEAT;
+            }
+        }
+
+        // Resolve buffers and images first, since these are the only external resources that the file
+        // might reference.
+        // Buffers will be exposed as Uint8Arrays.
+        // Images will be exposed as ImageBitmaps.
+
+        /**
+         * Buffers
+         * @type {Promise<Uint8Array>[]}
+         */
+        const pendingBuffers = [];
+
+        const declaredBuffers = json.buffers ?? [];
+
+        /*
+         A .glb's buffer 0 is its binary chunk and names no URI. The buffers after it are ordinary,
+         and are where an extension that produces its own bufferView bytes puts the placeholder those
+         views point at - so the chunk is a special case of buffer 0, not a reason to stop looking at
+         the rest.
+        */
+        const bufferCount = Math.max(declaredBuffers.length, binaryChunk ? 1 : 0);
+
+        for (let index = 0; index < bufferCount; index++) {
+            if (binaryChunk && index === 0) {
+                pendingBuffers[index] = Promise.resolve(binaryChunk);
+                continue;
+            }
+
+            const buffer = declaredBuffers[index];
+
+            /*
+             A buffer with no URI was never written. Asking for one produced a request for
+             "<baseUrl>undefined", which is how a compressed .gltf with a fallback buffer - the shape
+             gltfpack writes - failed before it read a single accessor.
+            */
+            if (buffer.uri === undefined || this.bufferViewExtensions.is_placeholder_buffer(buffer)) {
+                pendingBuffers[index] = Promise.resolve(EMPTY_BUFFER);
+                continue;
+            }
+
+            // Check fileMap first (enables loading from dropped files)
+            if (this.fileMap) {
+                const file = this.fileMap.get(buffer.uri);
+
+                if (file !== undefined) {
+                    // File or Blob
+                    pendingBuffers[index] = (file instanceof ArrayBuffer)
+                        ? Promise.resolve(new Uint8Array(file))
+                        : file.arrayBuffer().then(as_bytes);
+
+                    continue;
+                }
+            }
+
+            pendingBuffers[index] = this.#read(
+                resolveUri(buffer.uri, baseUrl),
+                GameAssetType.ArrayBuffer
+            ).then(as_bytes);
+        }
+
+        // If the loader has been instructed to only load certain images (such as just baseColorTexture)
+        // then scan through all the materials first and gather the image IDs for only those images.
+        // (This feature really only makes sense for this specific set of samples.)
+        let activeImageSet;
+        if (this.loadImageSlots) {
+            activeImageSet = new Set();
+            for (const material of json.materials) {
+                for (const imageChannel of this.loadImageSlots) {
+                    const texture = material[imageChannel] ?? material.pbrMetallicRoughness[imageChannel];
+                    if (texture !== undefined) {
+                        activeImageSet.add(json.textures[texture.index].source);
+                    }
+                }
+            }
+        } else {
+            /*
+             Only the images something will actually sample. A texture may offer the same picture in
+             several containers — `source` plus an extension — and fetching the ones this loader has
+             already decided against is not merely wasted: `createImageBitmap` rejects on a container
+             the browser cannot decode, and an image nothing was going to sample takes the whole model
+             down with it. The game's level models each carry a DDS beside their PNG for exactly that
+             reason, and not one of them loaded.
+             */
+            activeImageSet = gltf_used_image_indices(json);
+        }
+
+        /**
+         * Images
+         * @type {Promise<ImageBitmap>[]}
+         */
+        const pendingImages = [];
+        for (let index = 0; index < json.images?.length || 0; ++index) {
+            if (activeImageSet && !activeImageSet.has(index)) {
+                continue;
+            }
+            const image = json.images[index];
+
+            /**
+             *
+             * @param {Blob} blob
+             * @return {Promise<ImageBitmap>}
+             */
+            function blob_to_bitmap(blob) {
+                return createImageBitmap(blob, {
+                    // premultiplication is done during texture upload
+                    premultiplyAlpha: "none",
+                })
+            }
+
+            if (image.uri) {
+
+                // Check fileMap first (enables loading from dropped files)
+                if (this.fileMap) {
+                    const file = this.fileMap.get(image.uri);
+
+                    if (file !== undefined) {
+                        const blob = (file instanceof Blob) ? file : new Blob([file]);
+                        pendingImages[index] = blob_to_bitmap(blob);
+                        continue;
+                    }
+                }
+
+                /*
+                 Decoded by the framework rather than here, which is what makes one texture shared
+                 by two models one decode instead of two — the expensive half of loading a model is
+                 its images, and a level places the same handful of them hundreds of times.
+                */
+                pendingImages[index] = this.#read(
+                    resolveUri(image.uri, baseUrl),
+                    GameAssetType.ImageBitmap
+                );
+
+            } else {
+
+                const bufferView = json.bufferViews[image.bufferView];
+
+                const claimed = this.bufferViewExtensions.claim(bufferView, image.bufferView);
+
+                if (claimed !== null) {
+                    /*
+                     Legal to write and pointless to: the payload is a PNG or a JPEG, already
+                     compressed. Decoding it is not implemented, and the alternative to saying so is
+                     handing the image decoder a placeholder buffer's bytes.
+                    */
+                    throw new Error(
+                        `images[${index}] is sourced from a bufferView '${claimed.name}' produces,`
+                        + ` which is not supported`
+                    );
+                }
+
+                pendingImages[index] = pendingBuffers[bufferView.buffer].then((buffer) => {
+
+                    const blob = new Blob(
+                        [buffer.subarray(
+                            bufferView.byteOffset,
+                            bufferView.byteOffset + bufferView.byteLength
+                        )],
+                        { type: image.mimeType }
+                    );
+
+                    return blob_to_bitmap(blob);
+                });
+
+            }
+        }
+
+        // Place every node, and bound every mesh, node and scene, starting at the roots.
+        place_nodes(json);
+
+        // Replace the resolved resources in the JSON structure.
+        const buffers = await Promise.all(pendingBuffers);
+
+        /*
+         Views that some extension produces the bytes for become ordinary ones here, over decoded
+         buffers appended to the list, so that nothing downstream - accessors, sparse accessors, the
+         mesh reader - has to know any of those extensions exist. Nor does this parser: it asks the
+         set what claims a view, and the set is the one place that knows what is implemented.
+
+         Per view, and guarded per view. A file nothing claims - which is nearly all of them - gets
+         its own view objects back by identity and appends no buffer.
+        */
+        json.bufferViews = gltf_apply_buffer_view_extensions(
+            json.bufferViews, buffers, this.bufferViewExtensions
+        );
+
+        json.buffers = buffers;
+        json.images = await Promise.all(pendingImages);
+
+        return json;
+    }
+
+
+}
+