@adobe/data-gpu 0.9.69

package/src/graphics/scene/model/gltf/build-material-bind-group.ts

@@ -0,0 +1,110 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { createStructBuffer, copyToGPUBuffer, getStructLayout, type TypedBuffer } from "@adobe/data/typed-buffer";
+import { schema as visibleMaterialSchema } from "../../../rendering/visible-material/schema.js";
+import type { VisibleMaterial } from "../../../rendering/visible-material/visible-material.js";
+import type { GltfAsset, GltfMaterial } from "./gltf-schema.js";
+
+const layout = getStructLayout(visibleMaterialSchema);
+
+export interface MaterialTextures {
+    baseColor: GPUTextureView;
+    metallicRoughness: GPUTextureView;
+    normal: GPUTextureView;
+    occlusion: GPUTextureView;
+    emissive: GPUTextureView;
+}
+
+export interface FallbackViews {
+    white: GPUTextureView;
+    black: GPUTextureView;
+    flatNormal: GPUTextureView;
+}
+
+function defaultMaterial(): VisibleMaterial {
+    return {
+        baseColorFactor: [1, 1, 1, 1],
+        emissiveFactor: [0, 0, 0],
+        metallicFactor: 1,
+        roughnessFactor: 1,
+        normalScale: 1,
+        occlusionStrength: 1,
+    };
+}
+
+function gltfToVisibleMaterial(m: GltfMaterial): VisibleMaterial {
+    const pbr = m.pbrMetallicRoughness;
+    return {
+        baseColorFactor: pbr?.baseColorFactor ?? [1, 1, 1, 1],
+        emissiveFactor: m.emissiveFactor ?? [0, 0, 0],
+        metallicFactor: pbr?.metallicFactor ?? 1,
+        roughnessFactor: pbr?.roughnessFactor ?? 1,
+        normalScale: m.normalTexture?.scale ?? 1,
+        occlusionStrength: m.occlusionTexture?.strength ?? 1,
+    };
+}
+
+function viewFor(
+    textures: GPUTexture[],
+    gltf: GltfAsset,
+    textureIndex: number | undefined,
+    fallback: GPUTextureView,
+): GPUTextureView {
+    if (textureIndex === undefined) return fallback;
+    const tex = gltf.textures?.[textureIndex];
+    if (!tex || tex.source === undefined) return fallback;
+    const gpuTexture = textures[tex.source];
+    if (!gpuTexture) return fallback;
+    return gpuTexture.createView();
+}
+
+/**
+ * Builds the per-primitive material bind group: a small uniform buffer holding
+ * the PBR factors plus the five sampled textures and a shared sampler.
+ *
+ * Missing textures fall back to neutral 1x1 textures so the shader always has
+ * a valid binding (white for baseColor/occlusion, black for emissive, flat
+ * (0.5, 0.5, 1) for the normal map).
+ */
+export function buildMaterialBindGroup(
+    device: GPUDevice,
+    gltf: GltfAsset,
+    sourceTextures: GPUTexture[],
+    fallback: FallbackViews,
+    sampler: GPUSampler,
+    layoutGpu: GPUBindGroupLayout,
+    materialIndex: number | undefined,
+): GPUBindGroup {
+    const material = materialIndex !== undefined && gltf.materials?.[materialIndex]
+        ? gltfToVisibleMaterial(gltf.materials[materialIndex])
+        : defaultMaterial();
+    const gltfMat = materialIndex !== undefined ? gltf.materials?.[materialIndex] : undefined;
+
+    const structBuffer: TypedBuffer<VisibleMaterial> = createStructBuffer(visibleMaterialSchema, layout.size);
+    structBuffer.set(0, material);
+
+    let uniformBuffer = device.createBuffer({
+        size: layout.size,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    uniformBuffer = copyToGPUBuffer(structBuffer, device, uniformBuffer);
+
+    const baseColorView = viewFor(sourceTextures, gltf, gltfMat?.pbrMetallicRoughness?.baseColorTexture?.index, fallback.white);
+    const mrView = viewFor(sourceTextures, gltf, gltfMat?.pbrMetallicRoughness?.metallicRoughnessTexture?.index, fallback.white);
+    const normalView = viewFor(sourceTextures, gltf, gltfMat?.normalTexture?.index, fallback.flatNormal);
+    const occlusionView = viewFor(sourceTextures, gltf, gltfMat?.occlusionTexture?.index, fallback.white);
+    const emissiveView = viewFor(sourceTextures, gltf, gltfMat?.emissiveTexture?.index, fallback.black);
+
+    return device.createBindGroup({
+        layout: layoutGpu,
+        entries: [
+            { binding: 0, resource: { buffer: uniformBuffer } },
+            { binding: 1, resource: baseColorView },
+            { binding: 2, resource: mrView },
+            { binding: 3, resource: normalView },
+            { binding: 4, resource: occlusionView },
+            { binding: 5, resource: emissiveView },
+            { binding: 6, resource: sampler },
+        ],
+    });
+}

package/src/graphics/scene/model/gltf/compute-world-matrices.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Mat4x4, Quat } from "@adobe/data/math";
+import type { GltfAsset, GltfNode } from "./gltf-schema.js";
+
+function localMatrix(node: GltfNode): Mat4x4 {
+    if (node.matrix && node.matrix.length === 16) {
+        // glTF spec guarantees a column-major 16-element float array when present.
+        return node.matrix as unknown as Mat4x4;
+    }
+    const t = node.translation ?? [0, 0, 0];
+    const r = node.rotation ?? [0, 0, 0, 1];
+    const s = node.scale ?? [1, 1, 1];
+    const T = Mat4x4.translation(t[0], t[1], t[2]);
+    // glTF rotation is a unit quaternion [x, y, z, w].
+    const R = Quat.toMat4(r as Quat);
+    const S = Mat4x4.scaling(s[0], s[1], s[2]);
+    return Mat4x4.multiply(Mat4x4.multiply(T, R), S);
+}
+
+/**
+ * Walks the scene graph and returns a world matrix for every node index.
+ * Nodes not reachable from a scene root get the identity matrix.
+ */
+export function computeWorldMatrices(gltf: GltfAsset): Mat4x4[] {
+    const result: Mat4x4[] = new Array((gltf.nodes ?? []).length).fill(Mat4x4.identity);
+
+    const visit = (nodeIdx: number, parent: Mat4x4): void => {
+        const node = gltf.nodes![nodeIdx];
+        const world = Mat4x4.multiply(parent, localMatrix(node));
+        result[nodeIdx] = world;
+        for (const child of node.children ?? []) {
+            visit(child, world);
+        }
+    };
+
+    const sceneIdx = gltf.scene ?? 0;
+    const roots = gltf.scenes?.[sceneIdx]?.nodes ?? [];
+    for (const r of roots) {
+        visit(r, Mat4x4.identity);
+    }
+    return result;
+}

package/src/graphics/scene/model/gltf/create-color-material.ts

@@ -0,0 +1,47 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { createStructBuffer, copyToGPUBuffer, getStructLayout } from "@adobe/data/typed-buffer";
+import { schema as visibleMaterialSchema } from "../../../rendering/visible-material/schema.js";
+import type { VisibleMaterial } from "../../../rendering/visible-material/visible-material.js";
+import type { ColorMaterialOptions } from "../../../rendering/visible-material/color-material-options.js";
+import type { FallbackViews } from "./build-material-bind-group.js";
+
+const layout = getStructLayout(visibleMaterialSchema);
+
+export function createColorMaterial(
+    device: GPUDevice,
+    bindGroupLayout: GPUBindGroupLayout,
+    sampler: GPUSampler,
+    fallback: FallbackViews,
+    options: ColorMaterialOptions,
+): GPUBindGroup {
+    const material: VisibleMaterial = {
+        baseColorFactor: options.color,
+        emissiveFactor: options.emissive ?? [0, 0, 0],
+        metallicFactor: options.metallic ?? 0,
+        roughnessFactor: options.roughness ?? 0.8,
+        normalScale: 1,
+        occlusionStrength: 1,
+    };
+
+    const structBuffer = createStructBuffer(visibleMaterialSchema, layout.size);
+    structBuffer.set(0, material);
+    let uniformBuffer = device.createBuffer({
+        size: layout.size,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    uniformBuffer = copyToGPUBuffer(structBuffer, device, uniformBuffer);
+
+    return device.createBindGroup({
+        layout: bindGroupLayout,
+        entries: [
+            { binding: 0, resource: { buffer: uniformBuffer } },
+            { binding: 1, resource: fallback.white },
+            { binding: 2, resource: fallback.white },
+            { binding: 3, resource: fallback.flatNormal },
+            { binding: 4, resource: fallback.white },
+            { binding: 5, resource: fallback.white },
+            { binding: 6, resource: sampler },
+        ],
+    });
+}

package/src/graphics/scene/model/gltf/decode-images.ts

@@ -0,0 +1,93 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { readImageBytes } from "./accessor-view.js";
+import type { GltfAsset } from "./gltf-schema.js";
+
+/**
+ * Categorizes each image index as either "color" (sRGB) or "data" (linear).
+ * glTF spec: baseColor and emissive textures are in sRGB color space; normal,
+ * metallic-roughness, and occlusion textures are in linear color space.
+ *
+ * When an image is referenced from both kinds of slot, "color" wins because
+ * losing precision in a data texture is more visible than gamma drift in a
+ * color one.
+ */
+function categorizeImages(gltf: GltfAsset): ("color" | "data")[] {
+    const out: ("color" | "data")[] = new Array((gltf.images ?? []).length).fill("data");
+
+    const markColor = (textureIndex: number | undefined): void => {
+        if (textureIndex === undefined) return;
+        const t = gltf.textures?.[textureIndex];
+        if (t?.source !== undefined) out[t.source] = "color";
+    };
+
+    for (const mat of gltf.materials ?? []) {
+        markColor(mat.pbrMetallicRoughness?.baseColorTexture?.index);
+        markColor(mat.emissiveTexture?.index);
+    }
+
+    return out;
+}
+
+async function decodeOne(
+    device: GPUDevice,
+    bytes: Uint8Array,
+    mimeType: string | undefined,
+    colorSpace: "color" | "data",
+): Promise<GPUTexture> {
+    const blob = new Blob([bytes], { type: mimeType ?? "image/png" });
+    const bitmap = await createImageBitmap(blob, { colorSpaceConversion: "none" });
+    const format: GPUTextureFormat = colorSpace === "color" ? "rgba8unorm-srgb" : "rgba8unorm";
+    const texture = device.createTexture({
+        size: [bitmap.width, bitmap.height, 1],
+        format,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+    device.queue.copyExternalImageToTexture(
+        { source: bitmap },
+        { texture },
+        [bitmap.width, bitmap.height, 1],
+    );
+    bitmap.close();
+    return texture;
+}
+
+export async function decodeAllImages(
+    device: GPUDevice,
+    gltf: GltfAsset,
+    bin: ArrayBuffer,
+): Promise<GPUTexture[]> {
+    const kinds = categorizeImages(gltf);
+    return Promise.all(
+        (gltf.images ?? []).map((image, idx) => {
+            const bytes = readImageBytes(gltf, bin, idx);
+            return decodeOne(device, bytes, image.mimeType, kinds[idx]);
+        }),
+    );
+}
+
+/**
+ * Creates 1x1 fallback textures that the renderer can bind when a material
+ * doesn't supply a particular slot. Avoids "if texture exists" branches in
+ * the shader.
+ */
+export function createFallbackTextures(device: GPUDevice): {
+    white: GPUTextureView;
+    black: GPUTextureView;
+    flatNormal: GPUTextureView;
+} {
+    const make = (pixel: Uint8Array, format: GPUTextureFormat): GPUTextureView => {
+        const tex = device.createTexture({
+            size: [1, 1, 1],
+            format,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        device.queue.writeTexture({ texture: tex }, pixel, { bytesPerRow: 4 }, [1, 1, 1]);
+        return tex.createView();
+    };
+    return {
+        white: make(new Uint8Array([255, 255, 255, 255]), "rgba8unorm-srgb"),
+        black: make(new Uint8Array([0, 0, 0, 255]), "rgba8unorm-srgb"),
+        flatNormal: make(new Uint8Array([128, 128, 255, 255]), "rgba8unorm"),
+    };
+}

package/src/graphics/scene/model/gltf/gltf-schema.ts

@@ -0,0 +1,161 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+// Minimal subset of glTF 2.0 schema fields we actually consume.
+// Spec: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
+
+export interface GltfAsset {
+    asset: { version: string };
+    scene?: number;
+    scenes?: GltfScene[];
+    nodes?: GltfNode[];
+    meshes?: GltfMesh[];
+    skins?: GltfSkin[];
+    materials?: GltfMaterial[];
+    textures?: GltfTexture[];
+    images?: GltfImage[];
+    samplers?: GltfSampler[];
+    accessors?: GltfAccessor[];
+    bufferViews?: GltfBufferView[];
+    buffers?: GltfBuffer[];
+    animations?: GltfAnimation[];
+}
+
+export interface GltfAnimation {
+    name?: string;
+    channels: GltfAnimationChannel[];
+    samplers: GltfAnimationSampler[];
+}
+
+export interface GltfAnimationChannel {
+    sampler: number;
+    target: { node: number; path: "translation" | "rotation" | "scale" | "weights" };
+}
+
+export interface GltfAnimationSampler {
+    input: number;   // accessor → keyframe times (Float32Array)
+    output: number;  // accessor → keyframe values
+    interpolation?: "LINEAR" | "STEP" | "CUBICSPLINE";
+}
+
+export interface GltfScene {
+    nodes?: number[];
+}
+
+export interface GltfNode {
+    name?: string;
+    mesh?: number;
+    skin?: number;
+    children?: number[];
+    translation?: [number, number, number];
+    rotation?: [number, number, number, number];
+    scale?: [number, number, number];
+    matrix?: number[];
+}
+
+export interface GltfMesh {
+    name?: string;
+    primitives: GltfPrimitive[];
+}
+
+export interface GltfPrimitive {
+    attributes: {
+        POSITION: number;
+        NORMAL?: number;
+        TANGENT?: number;
+        TEXCOORD_0?: number;
+        JOINTS_0?: number;
+        WEIGHTS_0?: number;
+        [key: string]: number | undefined;
+    };
+    indices?: number;
+    material?: number;
+    mode?: number; // default 4 (triangles)
+}
+
+export interface GltfSkin {
+    name?: string;
+    inverseBindMatrices?: number;  // accessor index → array of mat4
+    skeleton?: number;             // root joint node index
+    joints: number[];              // ordered list of node indices that are joints
+}
+
+export interface GltfMaterial {
+    name?: string;
+    pbrMetallicRoughness?: {
+        baseColorFactor?: [number, number, number, number];
+        baseColorTexture?: { index: number; texCoord?: number };
+        metallicFactor?: number;
+        roughnessFactor?: number;
+        metallicRoughnessTexture?: { index: number; texCoord?: number };
+    };
+    normalTexture?: { index: number; texCoord?: number; scale?: number };
+    occlusionTexture?: { index: number; texCoord?: number; strength?: number };
+    emissiveTexture?: { index: number; texCoord?: number };
+    emissiveFactor?: [number, number, number];
+    alphaMode?: "OPAQUE" | "MASK" | "BLEND";
+    alphaCutoff?: number;
+    doubleSided?: boolean;
+}
+
+export interface GltfTexture {
+    sampler?: number;
+    source?: number;
+}
+
+export interface GltfImage {
+    name?: string;
+    mimeType?: string;
+    bufferView?: number;
+    uri?: string;
+}
+
+export interface GltfSampler {
+    magFilter?: number;
+    minFilter?: number;
+    wrapS?: number;
+    wrapT?: number;
+}
+
+export interface GltfAccessor {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: number; // 5120..5126
+    count: number;
+    type: "SCALAR" | "VEC2" | "VEC3" | "VEC4" | "MAT2" | "MAT3" | "MAT4";
+    normalized?: boolean;
+    min?: number[];
+    max?: number[];
+}
+
+export interface GltfBufferView {
+    buffer: number;
+    byteOffset?: number;
+    byteLength: number;
+    byteStride?: number;
+    target?: number;
+}
+
+export interface GltfBuffer {
+    byteLength: number;
+    uri?: string;
+}
+
+// glTF componentType constants
+export const COMPONENT_TYPE = {
+    BYTE: 5120,
+    UNSIGNED_BYTE: 5121,
+    SHORT: 5122,
+    UNSIGNED_SHORT: 5123,
+    UNSIGNED_INT: 5125,
+    FLOAT: 5126,
+} as const;
+
+export const ACCESSOR_TYPE_COMPONENTS: Record<GltfAccessor["type"], number> = {
+    SCALAR: 1,
+    VEC2: 2,
+    VEC3: 3,
+    VEC4: 4,
+    MAT2: 4,
+    MAT3: 9,
+    MAT4: 16,
+};

package/src/graphics/scene/model/gltf/load-gltf-model.ts

@@ -0,0 +1,220 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Mat4x4, type Aabb } from "@adobe/data/math";
+import { VisibleMaterial } from "../../../rendering/visible-material/visible-material.js";
+import { readAccessor } from "./accessor-view.js";
+import { buildMaterialBindGroup, type FallbackViews } from "./build-material-bind-group.js";
+import { computeWorldMatrices } from "./compute-world-matrices.js";
+import { createFallbackTextures, decodeAllImages } from "./decode-images.js";
+import { packPrimitiveVertices } from "./pack-vertex-buffer.js";
+import { parseGlb } from "./parse-glb.js";
+import { parseGltfSkin, type LoadedSkin } from "./parse-skin.js";
+import { parseGltfAnimations, type LoadedAnimation } from "./parse-animations.js";
+
+export interface GpuPrimitiveData {
+    pbrVertexBuffer: GPUBuffer;
+    /** Secondary VBO with skinning attributes (joints u32×4, weights f32×4).
+     *  Null for non-skinned primitives. Drives the renderer's pipeline choice. */
+    pbrSkinVertexBuffer: GPUBuffer | null;
+    pbrIndexBuffer: GPUBuffer;
+    pbrIndexCount: number;
+    pbrIndexFormat: GPUIndexFormat;
+    pbrMaterialBindGroup: GPUBindGroup;
+    /** Node's model-root-local matrix. Renderers pre-multiply this with the
+     *  per-instance model-root world matrix at draw time. Identity for
+     *  single-node and skinned-mesh primitives (skin owns the deformation). */
+    pbrNodeLocalMatrix: Mat4x4;
+}
+
+export interface LoadedGltfData {
+    primitives: GpuPrimitiveData[];
+    bounds: Aabb;
+    /** Present when the glTF declares a `skins[0]`. */
+    skin: LoadedSkin | null;
+    /** Parsed `animations[]`; jointIndex on each track is into `skin.jointTemplate`. */
+    animations: LoadedAnimation[];
+    /** Model-space collision geometry retained on the CPU for auto-generating
+     *  physics colliders (convex hull / trimesh) — the non-skinned primitives'
+     *  positions (each baked by its node matrix) + indices, aggregated. Null when
+     *  the model has no static geometry (e.g. skin-only). */
+    collision: { positions: Float32Array; indices: Uint32Array } | null;
+    /** Skinned vertices retained on the CPU (mesh-bind positions + 4 joint
+     *  indices + 4 weights per vertex), for fitting per-bone ragdoll capsules.
+     *  Null for non-skinned models. */
+    skinVertices: { positions: Float32Array; joints: Uint32Array; weights: Float32Array } | null;
+}
+
+function expandBounds(
+    m: Mat4x4,
+    localMin: readonly [number, number, number],
+    localMax: readonly [number, number, number],
+    outMin: [number, number, number],
+    outMax: [number, number, number],
+): void {
+    const xs = [localMin[0], localMax[0]];
+    const ys = [localMin[1], localMax[1]];
+    const zs = [localMin[2], localMax[2]];
+    for (const lx of xs) for (const ly of ys) for (const lz of zs) {
+        const wx = m[0] * lx + m[4] * ly + m[8]  * lz + m[12];
+        const wy = m[1] * lx + m[5] * ly + m[9]  * lz + m[13];
+        const wz = m[2] * lx + m[6] * ly + m[10] * lz + m[14];
+        if (wx < outMin[0]) outMin[0] = wx; if (wx > outMax[0]) outMax[0] = wx;
+        if (wy < outMin[1]) outMin[1] = wy; if (wy > outMax[1]) outMax[1] = wy;
+        if (wz < outMin[2]) outMin[2] = wz; if (wz > outMax[2]) outMax[2] = wz;
+    }
+}
+
+function pickIndexFormat(raw: Uint16Array | Uint32Array | Uint8Array | Float32Array): {
+    indices: Uint16Array | Uint32Array;
+    format: GPUIndexFormat;
+} {
+    if (raw instanceof Uint32Array) return { indices: raw, format: "uint32" };
+    if (raw instanceof Uint16Array) return { indices: raw, format: "uint16" };
+    if (raw instanceof Uint8Array) {
+        const u16 = new Uint16Array(raw.length);
+        for (let i = 0; i < raw.length; i++) u16[i] = raw[i];
+        return { indices: u16, format: "uint16" };
+    }
+    throw new Error("Index accessor must be an integer type");
+}
+
+export async function loadGltfPrimitives(device: GPUDevice, url: string): Promise<LoadedGltfData> {
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status}`);
+    const buffer = await response.arrayBuffer();
+
+    const { json, bin } = parseGlb(buffer);
+
+    const materialLayout = VisibleMaterial.createBindGroupLayout(device);
+    const sourceTextures = await decodeAllImages(device, json, bin);
+    const fallback: FallbackViews = createFallbackTextures(device);
+
+    const sampler = device.createSampler({
+        magFilter: "linear",
+        minFilter: "linear",
+        addressModeU: "repeat",
+        addressModeV: "repeat",
+    });
+
+    const worldMatrices = computeWorldMatrices(json);
+    const skin = parseGltfSkin(json, bin);
+    const animations = skin ? parseGltfAnimations(json, bin, json.skins![0].joints) : [];
+
+    const boundsMin: [number, number, number] = [Infinity, Infinity, Infinity];
+    const boundsMax: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+    const primitives: GpuPrimitiveData[] = [];
+    // CPU-retained collision geometry (model space, non-skinned primitives only).
+    const collPositions: number[] = [], collIndices: number[] = [];
+    // CPU-retained skin vertices (mesh-bind space, skinned primitives only).
+    const skinPos: number[] = [], skinJoints: number[] = [], skinWeights: number[] = [];
+
+    for (let nodeIdx = 0; nodeIdx < (json.nodes ?? []).length; nodeIdx++) {
+        const node = json.nodes![nodeIdx];
+        if (node.mesh === undefined) continue;
+        const mesh = json.meshes![node.mesh];
+        // For skinned primitives the joint transforms own the deformation;
+        // the mesh node's own transform must not be baked in. For non-skinned
+        // primitives we pre-bake the node's world matrix as before.
+        const skinned = node.skin !== undefined;
+        const pbrNodeLocalMatrix = skinned ? Mat4x4.identity : worldMatrices[nodeIdx];
+
+        for (const prim of mesh.primitives) {
+            const packed = packPrimitiveVertices(json, bin, prim);
+
+            expandBounds(pbrNodeLocalMatrix, packed.boundsMin, packed.boundsMax, boundsMin, boundsMax);
+
+            const vertexBuffer = device.createBuffer({
+                size: packed.vertices.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(vertexBuffer, 0, packed.vertices);
+
+            let skinVertexBuffer: GPUBuffer | null = null;
+            if (packed.skinningAttributes) {
+                skinVertexBuffer = device.createBuffer({
+                    size: packed.skinningAttributes.byteLength,
+                    usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+                });
+                device.queue.writeBuffer(skinVertexBuffer, 0, packed.skinningAttributes);
+            }
+
+            // Non-indexed primitives are valid in glTF — synthesize sequential indices.
+            let indices: Uint16Array | Uint32Array;
+            let format: GPUIndexFormat;
+            if (prim.indices === undefined) {
+                if (packed.vertexCount <= 0xffff) {
+                    indices = new Uint16Array(packed.vertexCount);
+                    for (let k = 0; k < packed.vertexCount; k++) indices[k] = k;
+                    format = "uint16";
+                } else {
+                    indices = new Uint32Array(packed.vertexCount);
+                    for (let k = 0; k < packed.vertexCount; k++) indices[k] = k;
+                    format = "uint32";
+                }
+            } else {
+                const raw = readAccessor(json, bin, prim.indices);
+                ({ indices, format } = pickIndexFormat(raw));
+            }
+
+            const indexBuffer = device.createBuffer({
+                size: indices.byteLength,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(indexBuffer, 0, indices);
+
+            // Retain collision geometry for non-skinned primitives: deinterleave the
+            // positions (stride = floats/vertex, position at offset 0), bake the node
+            // matrix into model space, and append with index offset. Skinned primitives
+            // deform at runtime, so a static collider from their bind pose is meaningless.
+            if (!skinned) {
+                const m = pbrNodeLocalMatrix, verts = packed.vertices;
+                const stride = packed.vertices.length / packed.vertexCount;
+                const vbase = collPositions.length / 3;
+                for (let v = 0; v < packed.vertexCount; v++) {
+                    const o = v * stride, x = verts[o], y = verts[o + 1], z = verts[o + 2];
+                    collPositions.push(
+                        m[0] * x + m[4] * y + m[8] * z + m[12],
+                        m[1] * x + m[5] * y + m[9] * z + m[13],
+                        m[2] * x + m[6] * y + m[10] * z + m[14],
+                    );
+                }
+                for (let k = 0; k < indices.length; k++) collIndices.push(indices[k] + vbase);
+            } else if (packed.skinningAttributes) {
+                // Retain skin vertices (mesh-bind positions + joints/weights) for
+                // fitting per-bone ragdoll capsules. Skinning attributes pack 8 words
+                // per vertex: joints (u32×4) in words 0–3, weights (f32×4) in 4–7.
+                const verts = packed.vertices, stride = packed.vertices.length / packed.vertexCount;
+                const sj = new Uint32Array(packed.skinningAttributes), sw = new Float32Array(packed.skinningAttributes);
+                for (let v = 0; v < packed.vertexCount; v++) {
+                    const o = v * stride, s = v * 8;
+                    skinPos.push(verts[o], verts[o + 1], verts[o + 2]);
+                    skinJoints.push(sj[s], sj[s + 1], sj[s + 2], sj[s + 3]);
+                    skinWeights.push(sw[s + 4], sw[s + 5], sw[s + 6], sw[s + 7]);
+                }
+            }
+
+            const materialBindGroup = buildMaterialBindGroup(
+                device, json, sourceTextures, fallback, sampler, materialLayout, prim.material,
+            );
+
+            primitives.push({
+                pbrVertexBuffer: vertexBuffer,
+                pbrSkinVertexBuffer: skinVertexBuffer,
+                pbrIndexBuffer: indexBuffer,
+                pbrIndexCount: indices.length,
+                pbrIndexFormat: format,
+                pbrMaterialBindGroup: materialBindGroup,
+                pbrNodeLocalMatrix,
+            });
+        }
+    }
+
+    return {
+        primitives,
+        bounds: { min: boundsMin as [number, number, number], max: boundsMax as [number, number, number] },
+        skin,
+        animations,
+        collision: collPositions.length ? { positions: new Float32Array(collPositions), indices: new Uint32Array(collIndices) } : null,
+        skinVertices: skinPos.length ? { positions: new Float32Array(skinPos), joints: new Uint32Array(skinJoints), weights: new Float32Array(skinWeights) } : null,
+    };
+}