@dylanebert/shallot-gltf 0.0.0-stage → 0.1.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dylan Ebert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# shallot-gltf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental static glTF 2.0 loading and placement for Shallot. Not specification-complete or optimized.
+
+```sh
+bun add @dylanebert/shallot-gltf @dylanebert/shallot
+```
+
+```ts
+import { MeshPlugin, type Plugin, runApp } from "@dylanebert/shallot";
+import { loadGltfScene, spawnGltfScene } from "@dylanebert/shallot-gltf";
+
+const Model: Plugin = {
+    name: "Model",
+    dependencies: [MeshPlugin],
+    async initialize(world, onProgress) {
+        const model = await loadGltfScene(world, new URL("/model.glb", location.href), onProgress);
+        spawnGltfScene(world, model, { translation: [0, 0, 0] });
+        console.log(model.unsupported);
+    },
+};
+await runApp({ plugins: [Model] });
+```
+
+The game owns loading and placement; this package needs no plugin state. Call `loadGltfScene` from the game's async `initialize`, before image warm-up. Its handle belongs to that world. `spawnGltfScene` creates one entity per primitive instance, composing placement onto its node world transform. A composition with shear refuses with the node named, before spawning any entities. There is no core parent relation or model-root entity. Repeated placements share the load's meshes and materials, rather than registering copies. `model.primitives` exposes each `mesh`, `material` and model-space `matrix` for games that supply placements through `registerProducerTable` instead.
+
+`loadGltf` and `parse` remain deviceless entry points. [examples/gltf-model](examples/gltf-model) loads the textured Khronos Cesium Milk Truck through the package name. Run it with `bunx vite examples/gltf-model`; check its presentation with `bunx playwright test -c examples/gltf-model --workers=1`.
+
+## Compatibility
+
+| shallot-gltf | Shallot |
+| --- | --- |
+| 0.1.0-next.1 | 0.10.0-next.5 and later 0.10 releases |
+
+## Supported subset
+
+- `.gltf` and `.glb` v2, with external, data-URI or BIN buffers. `parse` accepts already-resolved buffers. External image URIs become absolute; embedded images expose their bytes. `loadGltfScene` registers these images in Shallot's shared sRGB image array; Shallot decodes them at warm.
+- Triangle primitives: positions, normals, first UV set and unsigned indices, including interleaved accessors and accessor offsets. Missing normals deindex the triangles and compute flat normals as glTF requires (three.js's smooth fallback is deliberately not copied).
+- Default scene hierarchy, matrix or TRS nodes, shared mesh primitives and column-major world matrices per primitive instance. Matrices retain shear; geometry remains mesh-local. No core parent relation is needed.
+- Linear base color RGBA, base color image reference, metallic, roughness and emissive factors, OPAQUE/MASK/BLEND, cutoff (default 0.5), and `KHR_materials_unlit`. These target Shallot's existing `StandardMaterial` fields rather than extending core.
+
+Unknown required extensions refuse with their names, including compression extensions. Unknown optional extensions and ignored features are named in `unsupported`. Non-triangle primitives and sparse-accessor primitives are skipped and reported. Vertex colors, tangents and extra UV sets are ignored and named. Base color textures requesting a UV set other than zero are omitted and reported. Base-color textures register their own wrap modes and texel filters, including glTF's default REPEAT wrapping. Unspecified filters follow GLTFLoader: linear magnification and linear-mipmap-linear minification. Shallot selects the nearest mip, so `unsupported` includes `sampler.minFilter.mipSelection` for linear mip blending or disabled mipmapping, including the unspecified minification default. Double-sided materials are reported, not mapped. Metallic-roughness, normal, occlusion and emissive maps are each named when ignored; their factors still decode.
+
+## Scope cuts
+
+- Skinning, VAT, morph targets and animation clips are outside the static mesh pipeline; static geometry remains, without deformation or playback.
+- Lights and cameras are outside that pipeline.
+- Draco, meshopt and KTX2/Basis decoders are excluded: Bevy's core glTF loader ships none of them; each needs a vendored WASM decoder without a consumer here. Required compressed features refuse; optional extensions are reported and fallback data is used when available.
+- The archived worker pool, albedo buckets, palette union and scene routes depended on Shallot's removed renderer and are not recovered.
+
+The accessor, packing and node-local transform code is adapted from Shallot's archived `src/transitional/gltf/` at `f1023acd28a0fe31f64bc61345d4605887495201`; Accessor and GLB container tests are recovered from `a4e87190^:src/extras/gltf/`. Loading registers images before warm-up; runtime streaming is outside the supported subset.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for verification and [fixture provenance](tests/fixtures/README.md) for licenses.

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "@dylanebert/shallot-gltf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@dylanebert/shallot-gltf",
+    "version": "0.1.0-next.1",
+    "description": "Experimental static glTF loading and placement for Shallot.",
+    "license": "MIT",
+    "author": "Dylan Ebert <dylan.ebert@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/dylanebert/shallot-gltf.git"
+    },
+    "homepage": "https://github.com/dylanebert/shallot-gltf",
+    "bugs": "https://github.com/dylanebert/shallot-gltf/issues",
+    "keywords": [
+        "gltf",
+        "shallot-plugin"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "packageManager": "bun@1.4.3",
+    "engines": {
+        "bun": ">=1.4.3"
+    },
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "files": [
+        "src",
+        "!src/**/*.test.ts"
+    ],
+    "scripts": {
+        "lint": "biome check",
+        "test": "bun test"
+    },
+    "peerDependencies": {
+        "@dylanebert/shallot": "^0.10.0-next.5"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.5.13",
+        "@dylanebert/shallot": "0.10.0-next.5",
+        "@playwright/test": "^1.64.1",
+        "@types/bun": "^1.4.3",
+        "@types/three": "0.180.0",
+        "bun-webgpu": "github:dylanebert/bun-webgpu#7b75d0440d2f22e2c9a1cb383d15529652c53d98",
+        "three": "0.180.0",
+        "vite": "^8.3.4"
+    }
+}

package/src/glb.ts

@@ -0,0 +1,34 @@
+import type { GltfJson } from "./gltf";
+
+const MAGIC = 0x46546c67; // "glTF", little-endian
+const JSON_CHUNK = 0x4e4f534a; // "JSON"
+const BIN_CHUNK = 0x004e4942; // "BIN\0"
+
+export function isGlb(bytes: ArrayBuffer): boolean {
+    return bytes.byteLength >= 12 && new DataView(bytes).getUint32(0, true) === MAGIC;
+}
+
+export function parseGlb(bytes: ArrayBuffer): { json: GltfJson; bin?: ArrayBuffer } {
+    const dv = new DataView(bytes);
+    if (dv.getUint32(0, true) !== MAGIC) throw new Error("[gltf] not a .glb (bad magic)");
+    const version = dv.getUint32(4, true);
+    if (version !== 2) throw new Error(`[gltf] unsupported .glb version ${version} (expected 2)`);
+    const total = Math.min(dv.getUint32(8, true), bytes.byteLength);
+
+    let json: GltfJson | undefined;
+    let bin: ArrayBuffer | undefined;
+
+    for (let o = 12; o + 8 <= total; ) {
+        const length = dv.getUint32(o, true);
+        const type = dv.getUint32(o + 4, true);
+        const start = o + 8;
+        if (type === JSON_CHUNK) {
+            json = JSON.parse(new TextDecoder().decode(new Uint8Array(bytes, start, length)));
+        } else if (type === BIN_CHUNK) {
+            bin = bytes.slice(start, start + length);
+        }
+        o = start + length;
+    }
+    if (!json) throw new Error("[gltf] .glb has no JSON chunk");
+    return { json, bin };
+}

package/src/gltf.ts

@@ -0,0 +1,490 @@
+import {
+    ImageAddressMode,
+    ImageFilterMode,
+    type ImageSamplerDescriptor,
+} from "@dylanebert/shallot/rendering";
+import { composeMat4 as compose, multiplyMat4 as multiply } from "@dylanebert/shallot/utils";
+
+const VERTEX_FLOATS = 8;
+
+export interface GltfJson {
+    accessors?: Accessor[];
+    bufferViews?: BufferView[];
+    meshes?: GltfJsonMesh[];
+    materials?: Material[];
+    images?: { uri?: string; bufferView?: number; mimeType?: string }[];
+    textures?: { source?: number; sampler?: number; extensions?: Extensions }[];
+    samplers?: { wrapS?: number; wrapT?: number; magFilter?: number; minFilter?: number }[];
+    nodes?: Node[];
+    scenes?: { nodes?: number[] }[];
+    scene?: number;
+    buffers?: { uri?: string; byteLength: number; extensions?: Record<string, unknown> }[];
+    animations?: object[];
+    skins?: object[];
+    extensionsRequired?: string[];
+    extensionsUsed?: string[];
+}
+
+type Extensions = Record<string, unknown>;
+
+interface Accessor {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: number;
+    normalized?: boolean;
+    count: number;
+    type: "SCALAR" | "VEC2" | "VEC3" | "VEC4" | "MAT2" | "MAT3" | "MAT4";
+    sparse?: object;
+}
+
+interface BufferView {
+    buffer: number;
+    byteOffset?: number;
+    byteLength: number;
+    byteStride?: number;
+    extensions?: Extensions;
+}
+
+interface GltfJsonMesh {
+    name?: string;
+    primitives: Primitive[];
+}
+
+interface Primitive {
+    attributes: {
+        POSITION: number;
+
+        NORMAL?: number;
+
+        TEXCOORD_0?: number;
+
+        TEXCOORD_1?: number;
+
+        COLOR_0?: number;
+
+        JOINTS_0?: number;
+
+        WEIGHTS_0?: number;
+
+        TANGENT?: number;
+    };
+    indices?: number;
+    material?: number;
+    mode?: number;
+    targets?: object[];
+    extensions?: Extensions;
+}
+
+interface Material {
+    name?: string;
+    doubleSided?: boolean;
+    pbrMetallicRoughness?: {
+        baseColorFactor?: number[];
+        baseColorTexture?: { index: number; texCoord?: number };
+        metallicFactor?: number;
+        roughnessFactor?: number;
+        metallicRoughnessTexture?: { index: number };
+    };
+    normalTexture?: { index: number; scale?: number };
+    occlusionTexture?: { index: number; strength?: number };
+    emissiveFactor?: number[];
+    emissiveTexture?: { index: number };
+    alphaMode?: "OPAQUE" | "MASK" | "BLEND";
+    alphaCutoff?: number;
+    extensions?: Extensions;
+}
+
+interface Node {
+    name?: string;
+    mesh?: number;
+    skin?: number;
+    children?: number[];
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+}
+
+export interface GltfMesh {
+    name: string;
+    /** Packed (px py pz u)(nx ny nz v), eight floats per vertex. */
+    vertices: Float32Array;
+    indices: Uint32Array;
+    material: number;
+}
+
+export interface GltfMaterial {
+    color: [number, number, number, number];
+    texture?: number;
+    metallic: number;
+    roughness: number;
+    emissive: [number, number, number];
+    alphaMode: "OPAQUE" | "MASK" | "BLEND";
+    cutoff: number;
+    unlit: boolean;
+}
+export interface GltfScene {
+    meshes: GltfMesh[];
+    instances: { mesh: number; node: string; matrix: Float32Array }[];
+    materials: GltfMaterial[];
+    images: { uri?: string; bytes?: Uint8Array; mimeType?: string }[];
+    textures: { image?: number; sampler: ImageSamplerDescriptor }[];
+    unsupported: string[];
+}
+const COMPONENTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 } as const;
+
+const BYTE = 5120;
+const UNSIGNED_BYTE = 5121;
+const SHORT = 5122;
+const UNSIGNED_SHORT = 5123;
+const UNSIGNED_INT = 5125;
+const TRIANGLES = 4;
+
+function localMatrix(node: Node, out: Float32Array): Float32Array {
+    if (node.matrix) {
+        out.set(node.matrix);
+        return out;
+    }
+    const t = node.translation ?? [0, 0, 0];
+    const r = node.rotation ?? [0, 0, 0, 1];
+    const s = node.scale ?? [1, 1, 1];
+    return compose(t[0], t[1], t[2], r[0], r[1], r[2], r[3], s[0], s[1], s[2], out);
+}
+
+function compSize(componentType: number): number {
+    switch (componentType) {
+        case BYTE:
+        case UNSIGNED_BYTE:
+            return 1;
+        case SHORT:
+        case UNSIGNED_SHORT:
+            return 2;
+        default:
+            return 4; // FLOAT / UNSIGNED_INT
+    }
+}
+
+function readComponent(
+    view: DataView,
+    o: number,
+    componentType: number,
+    normalized: boolean,
+): number {
+    switch (componentType) {
+        case BYTE: {
+            const v = view.getInt8(o);
+            return normalized ? Math.max(v / 127, -1) : v;
+        }
+        case UNSIGNED_BYTE: {
+            const v = view.getUint8(o);
+            return normalized ? v / 255 : v;
+        }
+        case SHORT: {
+            const v = view.getInt16(o, true);
+            return normalized ? Math.max(v / 32767, -1) : v;
+        }
+        case UNSIGNED_SHORT: {
+            const v = view.getUint16(o, true);
+            return normalized ? v / 65535 : v;
+        }
+        default:
+            return view.getFloat32(o, true);
+    }
+}
+
+function readFloats(gltf: GltfJson, buffers: ArrayBuffer[], index: number): Float32Array {
+    const acc = gltf.accessors![index];
+    const bv = gltf.bufferViews![acc.bufferView!];
+    const comps = COMPONENTS[acc.type];
+    const size = compSize(acc.componentType);
+    const stride = bv.byteStride ?? comps * size;
+    const base = (bv.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+    const norm = acc.normalized ?? false;
+    const view = new DataView(buffers[bv.buffer]);
+    const out = new Float32Array(acc.count * comps);
+    for (let i = 0; i < acc.count; i++) {
+        const o = base + i * stride;
+        for (let c = 0; c < comps; c++)
+            out[i * comps + c] = readComponent(view, o + c * size, acc.componentType, norm);
+    }
+    return out;
+}
+
+function readIndices(gltf: GltfJson, buffers: ArrayBuffer[], index: number): Uint32Array {
+    const acc = gltf.accessors![index];
+    const bv = gltf.bufferViews![acc.bufferView!];
+    const size =
+        acc.componentType === UNSIGNED_INT ? 4 : acc.componentType === UNSIGNED_SHORT ? 2 : 1;
+    const stride = bv.byteStride ?? size;
+    const base = (bv.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+    const view = new DataView(buffers[bv.buffer]);
+    const out = new Uint32Array(acc.count);
+    for (let i = 0; i < acc.count; i++) {
+        const o = base + i * stride;
+        out[i] =
+            acc.componentType === UNSIGNED_INT
+                ? view.getUint32(o, true)
+                : acc.componentType === UNSIGNED_SHORT
+                  ? view.getUint16(o, true)
+                  : view.getUint8(o);
+    }
+    return out;
+}
+
+export function computeNormals(pos: Float32Array, indices: Uint32Array): Float32Array {
+    const normals = new Float32Array(pos.length);
+    for (let i = 0; i + 2 < indices.length; i += 3) {
+        const a = indices[i] * 3;
+        const b = indices[i + 1] * 3;
+        const c = indices[i + 2] * 3;
+        const e1x = pos[b] - pos[a];
+        const e1y = pos[b + 1] - pos[a + 1];
+        const e1z = pos[b + 2] - pos[a + 2];
+        const e2x = pos[c] - pos[a];
+        const e2y = pos[c + 1] - pos[a + 1];
+        const e2z = pos[c + 2] - pos[a + 2];
+        const nx = e1y * e2z - e1z * e2y;
+        const ny = e1z * e2x - e1x * e2z;
+        const nz = e1x * e2y - e1y * e2x;
+        normals[a] += nx;
+        normals[a + 1] += ny;
+        normals[a + 2] += nz;
+        normals[b] += nx;
+        normals[b + 1] += ny;
+        normals[b + 2] += nz;
+        normals[c] += nx;
+        normals[c + 1] += ny;
+        normals[c + 2] += nz;
+    }
+    for (let i = 0; i < normals.length; i += 3) {
+        const len = Math.hypot(normals[i], normals[i + 1], normals[i + 2]) || 1;
+        normals[i] /= len;
+        normals[i + 1] /= len;
+        normals[i + 2] /= len;
+    }
+    return normals;
+}
+
+function packVertices(
+    pos: Float32Array,
+    normal: Float32Array | null,
+    uv: Float32Array | null,
+): Float32Array {
+    const count = pos.length / 3;
+    const vertices = new Float32Array(count * VERTEX_FLOATS);
+    for (let i = 0; i < count; i++) {
+        const o = i * VERTEX_FLOATS;
+        vertices[o] = pos[i * 3];
+        vertices[o + 1] = pos[i * 3 + 1];
+        vertices[o + 2] = pos[i * 3 + 2];
+        vertices[o + 3] = uv ? uv[i * 2] : 0;
+        vertices[o + 4] = normal ? normal[i * 3] : 0;
+        vertices[o + 5] = normal ? normal[i * 3 + 1] : 0;
+        vertices[o + 6] = normal ? normal[i * 3 + 2] : 0;
+        vertices[o + 7] = uv ? uv[i * 2 + 1] : 0;
+    }
+    return vertices;
+}
+
+function decodeMesh(
+    gltf: GltfJson,
+    buffers: ArrayBuffer[],
+    prim: Primitive,
+    name: string,
+): GltfMesh {
+    let pos = readFloats(gltf, buffers, prim.attributes.POSITION);
+    let uv =
+        prim.attributes.TEXCOORD_0 !== undefined
+            ? readFloats(gltf, buffers, prim.attributes.TEXCOORD_0)
+            : null;
+    let indices =
+        prim.indices !== undefined
+            ? readIndices(gltf, buffers, prim.indices)
+            : Uint32Array.from({ length: pos.length / 3 }, (_, i) => i);
+
+    if (prim.attributes.NORMAL === undefined) {
+        const source = pos;
+        pos = Float32Array.from(
+            Array.from(indices, (i) => Array.from(source.slice(i * 3, i * 3 + 3))).flat(),
+        );
+        if (uv) {
+            const sourceUv = uv;
+            uv = Float32Array.from(
+                Array.from(indices, (i) => Array.from(sourceUv.slice(i * 2, i * 2 + 2))).flat(),
+            );
+        }
+        indices = Uint32Array.from({ length: indices.length }, (_, i) => i);
+    }
+    const normal =
+        prim.attributes.NORMAL !== undefined
+            ? readFloats(gltf, buffers, prim.attributes.NORMAL)
+            : computeNormals(pos, indices);
+    return {
+        name,
+        vertices: packVertices(pos, normal, uv),
+        indices,
+        material: prim.material ?? -1,
+    };
+}
+
+function supportedExtension(name: string): boolean {
+    return name === "KHR_materials_unlit";
+}
+
+/** Refuses unsupported required extensions before their resources are read. */
+export function validateRequiredExtensions(gltf: GltfJson): void {
+    for (const name of gltf.extensionsRequired ?? []) {
+        if (!supportedExtension(name))
+            throw new Error(`Unsupported required glTF extension: ${name}`);
+    }
+}
+
+/** Decodes resolved buffers without a device. Required unsupported extensions refuse by name.
+ * Instances retain column-major world matrices, including shear; geometry stays mesh-local.
+ */
+export function parse(gltf: GltfJson, buffers: ArrayBuffer[]): GltfScene {
+    validateRequiredExtensions(gltf);
+    const ignored = new Set<string>();
+    const scan = (value: unknown): void => {
+        if (!value || typeof value !== "object") return;
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "extensions") {
+                for (const name of Object.keys(child))
+                    if (!supportedExtension(name)) ignored.add(name);
+            } else scan(child);
+        }
+    };
+    scan(gltf);
+    for (const name of gltf.extensionsUsed ?? []) if (!supportedExtension(name)) ignored.add(name);
+    if (gltf.skins?.length) ignored.add("skin");
+    if (gltf.animations?.length) ignored.add("animation");
+    if ("cameras" in gltf) ignored.add("camera");
+    const materials = (gltf.materials ?? []).map((m): GltfMaterial => {
+        const pbr = m.pbrMetallicRoughness;
+        if ((pbr?.baseColorTexture?.texCoord ?? 0) !== 0) ignored.add("baseColorTexture.texCoord");
+        const texture = pbr?.baseColorTexture;
+        const textureIndex = (texture?.texCoord ?? 0) === 0 ? texture?.index : undefined;
+        for (const [name, value] of Object.entries({
+            metallicRoughnessTexture: pbr?.metallicRoughnessTexture,
+            normalTexture: m.normalTexture,
+            occlusionTexture: m.occlusionTexture,
+            emissiveTexture: m.emissiveTexture,
+            doubleSided: m.doubleSided,
+        }))
+            if (value) ignored.add(name);
+        return {
+            color: (pbr?.baseColorFactor ?? [1, 1, 1, 1]) as GltfMaterial["color"],
+            texture: textureIndex,
+            metallic: pbr?.metallicFactor ?? 1,
+            roughness: pbr?.roughnessFactor ?? 1,
+            emissive: (m.emissiveFactor ?? [0, 0, 0]) as GltfMaterial["emissive"],
+            alphaMode: m.alphaMode ?? "OPAQUE",
+            cutoff: m.alphaCutoff ?? 0.5,
+            unlit: m.extensions?.KHR_materials_unlit !== undefined,
+        };
+    });
+    const addressMode = (wrap = 10497) =>
+        wrap === 33071
+            ? ImageAddressMode.ClampToEdge
+            : wrap === 33648
+              ? ImageAddressMode.MirrorRepeat
+              : ImageAddressMode.Repeat;
+    const textures = (gltf.textures ?? []).map((texture, index) => {
+        const sampler =
+            texture.sampler === undefined ? undefined : gltf.samplers?.[texture.sampler];
+        // Shallot selects the nearest mip; glTF's unspecified min filter follows GLTFLoader.
+        const min = sampler?.minFilter ?? 9987;
+        if (
+            materials.some((material) => material.texture === index) &&
+            min !== 9984 &&
+            min !== 9985
+        )
+            ignored.add("sampler.minFilter.mipSelection");
+        return {
+            image: texture.source,
+            sampler: {
+                addressModeU: addressMode(sampler?.wrapS),
+                addressModeV: addressMode(sampler?.wrapT),
+                magFilter:
+                    sampler?.magFilter === 9728 ? ImageFilterMode.Nearest : ImageFilterMode.Linear,
+                minFilter:
+                    min === 9728 || min === 9984 || min === 9986
+                        ? ImageFilterMode.Nearest
+                        : ImageFilterMode.Linear,
+            },
+        };
+    });
+    const meshes: GltfMesh[] = [];
+    const meshEntries = (gltf.meshes ?? []).map((mesh, meshIndex) => {
+        const entries: number[] = [];
+        for (const [primitiveIndex, prim] of mesh.primitives.entries()) {
+            for (const semantic of Object.keys(prim.attributes)) {
+                if (!["POSITION", "NORMAL", "TEXCOORD_0"].includes(semantic)) ignored.add(semantic);
+            }
+            if (prim.targets?.length) ignored.add("morph");
+            if ((prim.mode ?? TRIANGLES) !== TRIANGLES) {
+                ignored.add("primitive-mode");
+                continue;
+            }
+            const accessors = [
+                prim.attributes.POSITION,
+                prim.attributes.NORMAL,
+                prim.attributes.TEXCOORD_0,
+                prim.indices,
+            ].filter((a): a is number => a !== undefined);
+            if (
+                accessors.some(
+                    (a) =>
+                        gltf.accessors?.[a]?.sparse ||
+                        gltf.accessors?.[a]?.bufferView === undefined,
+                )
+            ) {
+                ignored.add("sparse-accessor");
+                continue;
+            }
+            entries.push(meshes.length);
+            meshes.push(
+                decodeMesh(
+                    gltf,
+                    buffers,
+                    prim,
+                    `${mesh.name ?? `Mesh${meshIndex}`}/Primitive${primitiveIndex}`,
+                ),
+            );
+        }
+        return entries;
+    });
+    const instances: GltfScene["instances"] = [];
+    const nodes = gltf.nodes ?? [];
+    const children = new Set(nodes.flatMap((n) => n.children ?? []));
+    const roots =
+        gltf.scenes?.[gltf.scene ?? 0]?.nodes ??
+        nodes.map((_, i) => i).filter((i) => !children.has(i));
+    const walk = (index: number, parent: Float32Array, ancestors: Set<number>): void => {
+        if (ancestors.has(index)) throw new Error("Cyclic glTF node hierarchy");
+        const node = nodes[index];
+        const matrix = multiply(parent, localMatrix(node, new Float32Array(16)));
+        if (node.mesh !== undefined)
+            for (const mesh of meshEntries[node.mesh])
+                instances.push({ mesh, node: node.name ?? `Node${index}`, matrix });
+        for (const child of node.children ?? [])
+            walk(child, matrix, new Set([...ancestors, index]));
+    };
+    const identity = compose(0, 0, 0, 0, 0, 0, 1, 1, 1, 1);
+    for (const root of roots) walk(root, identity, new Set());
+    return {
+        meshes,
+        instances,
+        materials,
+        textures,
+        images: (gltf.images ?? []).map((image) => {
+            if (image.bufferView === undefined) return { uri: image.uri, mimeType: image.mimeType };
+            const view = gltf.bufferViews![image.bufferView];
+            return {
+                mimeType: image.mimeType,
+                bytes: new Uint8Array(buffers[view.buffer], view.byteOffset ?? 0, view.byteLength),
+            };
+        }),
+        unsupported: [...ignored].sort(),
+    };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { isGlb, parseGlb } from "./glb";
+export { type GltfJson, type GltfMaterial, type GltfMesh, type GltfScene, parse } from "./gltf";
+export { loadGltf } from "./load";
+export {
+    type Gltf,
+    type GltfPlacement,
+    type GltfPrimitive,
+    loadGltfScene,
+    spawnGltfScene,
+} from "./scene";

package/src/load.ts

@@ -0,0 +1,33 @@
+import { isGlb, parseGlb } from "./glb";
+import { type GltfJson, type GltfScene, parse, validateRequiredExtensions } from "./gltf";
+
+/** Reads a glTF or GLB URL and resolves external and data-URI buffers with the supplied fetch.
+ * Image sources are returned without decoding; loading performs no GPU work.
+ */
+export async function loadGltf(url: string | URL, read: typeof fetch = fetch): Promise<GltfScene> {
+    const base = new URL(url);
+    const response = await read(base);
+    if (!response.ok) throw new Error(`glTF load failed: ${base} (${response.status})`);
+    const bytes = await response.arrayBuffer();
+    const { json, bin } = isGlb(bytes)
+        ? parseGlb(bytes)
+        : { json: JSON.parse(new TextDecoder().decode(bytes)) as GltfJson, bin: undefined };
+    validateRequiredExtensions(json);
+    const buffers = await Promise.all(
+        (json.buffers ?? []).map(async (buffer) => {
+            if (!buffer.uri) {
+                if (!bin) throw new Error("glTF buffer has no URI or BIN chunk");
+                return bin;
+            }
+            const response = await read(new URL(buffer.uri, base));
+            if (!response.ok)
+                throw new Error(`glTF buffer load failed: ${buffer.uri} (${response.status})`);
+            return response.arrayBuffer();
+        }),
+    );
+    const scene = parse(json, buffers);
+    scene.images = scene.images.map((image) =>
+        image.uri ? { ...image, uri: new URL(image.uri, base).href } : image,
+    );
+    return scene;
+}

package/src/scene.ts

@@ -0,0 +1,137 @@
+import {
+    AlphaMode,
+    composeMat4,
+    decomposeMat4,
+    Materials,
+    Meshes,
+    type MeshHandle,
+    MeshInstance,
+    MeshMaterial,
+    multiplyMat4,
+    registerImage,
+    StandardMaterial,
+    Transform,
+    type World,
+} from "@dylanebert/shallot";
+import type { MaterialHandle } from "@dylanebert/shallot/standard/rendering";
+import { loadGltf } from "./load";
+
+export interface GltfPrimitive {
+    readonly mesh: MeshHandle;
+    readonly material: MaterialHandle;
+    readonly node: string;
+    /** Node world transform in model space, before placement; treat its elements as immutable. */
+    readonly matrix: Float32Array;
+}
+
+export interface Gltf {
+    readonly world: World;
+    readonly primitives: readonly GltfPrimitive[];
+    readonly unsupported: readonly string[];
+}
+
+export interface GltfPlacement {
+    translation?: readonly [number, number, number];
+    rotation?: readonly [number, number, number, number];
+    scale?: readonly [number, number, number];
+}
+
+/** Registers the default scene before warm, from the game's async initialize.
+ * The handle and its mesh, image and material registrations belong to this world until disposal.
+ */
+export async function loadGltfScene(
+    world: World,
+    url: string | URL,
+    onProgress?: (progress: number) => void,
+): Promise<Gltf> {
+    onProgress?.(0);
+    const scene = await loadGltf(url);
+    onProgress?.(0.5);
+    const textures = scene.textures.map((texture) => {
+        if (texture.image === undefined) return undefined;
+        const image = scene.images[texture.image];
+        return registerImage(
+            world,
+            image.uri ?? new Blob([image.bytes!.slice().buffer], { type: image.mimeType }),
+            { sampler: texture.sampler },
+        );
+    });
+    const materials = world.resource(Materials);
+    const handles = scene.materials.map((material) =>
+        materials.add(
+            StandardMaterial({
+                baseColor: material.color,
+                baseColorTexture:
+                    material.texture === undefined ? undefined : textures[material.texture],
+                metallic: material.metallic,
+                perceptualRoughness: material.roughness,
+                emissive: material.emissive,
+                unlit: material.unlit,
+            }),
+            {
+                alphaMode:
+                    material.alphaMode === "MASK"
+                        ? AlphaMode.Mask(material.cutoff)
+                        : material.alphaMode === "BLEND"
+                          ? AlphaMode.Blend
+                          : AlphaMode.Opaque,
+            },
+        ),
+    );
+    let defaultMaterial: MaterialHandle | undefined;
+    const meshes = scene.meshes.map((mesh) => world.resource(Meshes).add(mesh));
+    const primitives = scene.instances.map((instance) => {
+        const materialIndex = scene.meshes[instance.mesh].material;
+        if (materialIndex < 0)
+            defaultMaterial ??= materials.add(
+                StandardMaterial({ metallic: 1, perceptualRoughness: 1 }),
+            );
+        return {
+            mesh: meshes[instance.mesh],
+            material: handles[materialIndex] ?? defaultMaterial!,
+            node: instance.node,
+            matrix: instance.matrix,
+        };
+    });
+    onProgress?.(1);
+    return { world, primitives, unsupported: scene.unsupported };
+}
+
+/** Spawns one entity per primitive instance, composing placement onto the node's world transform.
+ * Refuses a foreign-world handle or a non-TRS composition, naming the node, before spawning anything.
+ */
+export function spawnGltfScene(world: World, gltf: Gltf, placement: GltfPlacement = {}): number[] {
+    if (gltf.world !== world) throw new Error("glTF handle belongs to another world");
+    const matrix = composeMat4(
+        ...(placement.translation ?? [0, 0, 0]),
+        ...(placement.rotation ?? [0, 0, 0, 1]),
+        ...(placement.scale ?? [1, 1, 1]),
+    );
+    const transforms = gltf.primitives.map((primitive) => {
+        const composed = multiplyMat4(matrix, primitive.matrix);
+        const t = decomposeMat4(composed);
+        const recomposed = composeMat4(t[0], t[1], t[2], t[3], t[4], t[5], t[6], t[7], t[8], t[9]);
+        if (
+            composed.some(
+                (value, i) =>
+                    !Number.isFinite(value) ||
+                    Math.abs(value - recomposed[i]) > 1e-5 * Math.max(1, Math.abs(value)),
+            )
+        )
+            throw new Error(
+                `glTF node "${primitive.node}": composed transform has shear or cannot be represented as TRS`,
+            );
+        return {
+            translation: [t[0], t[1], t[2]] as [number, number, number],
+            rotation: [t[3], t[4], t[5], t[6]] as [number, number, number, number],
+            scale: [t[7], t[8], t[9]] as [number, number, number],
+        };
+    });
+    return gltf.primitives.map((primitive, i) => {
+        const eid = world.create();
+        world.add(eid, Transform, transforms[i]);
+        world.add(eid, MeshInstance, { mesh: primitive.mesh });
+        world.add(eid, MeshMaterial, primitive.material);
+        return eid;
+    });
+}