@stowkit/three-loader 0.1.14 → 0.1.16

package/dist/stowkit-three-loader.esm.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { StowKitReader } from '@stowkit/reader';
+export { AssetType } from '@stowkit/reader';
 
 class MeshParser {
     /**
@@ -26,16 +27,13 @@ class MeshParser {
         if (metadataBlob.length < 140) {
             throw new Error(`Metadata blob too small: ${metadataBlob.length} bytes (expected at least 140)`);
         }
-        console.log(`Parsing mesh metadata: ${metadataBlob.length} bytes metadata, ${dataBlob.length} bytes data`);
         const metadata = this.parseMeshMetadata(metadataBlob);
-        console.log(`Mesh counts: ${metadata.meshGeometryCount} geometries, ${metadata.materialCount} materials, ${metadata.nodeCount} nodes`);
         // Check if the metadata blob contains just the header or all the mesh info
         const expectedMetadataSize = 140 +
             (metadata.meshGeometryCount * 40) + // Draco compressed (40 bytes each)
             (metadata.materialCount * 196) + // MaterialData header
             (metadata.nodeCount * 116);
         let hasExtendedMetadata = metadataBlob.length >= expectedMetadataSize;
-        console.log(`Expected metadata size: ${expectedMetadataSize}, actual: ${metadataBlob.length}, has extended: ${hasExtendedMetadata}`);
         // If metadata only has the header, the mesh info might be at the start of the data blob
         const sourceBlob = hasExtendedMetadata ? metadataBlob : dataBlob;
         const metaView = new DataView(sourceBlob.buffer, sourceBlob.byteOffset, sourceBlob.byteLength);
@@ -81,7 +79,6 @@ class MeshParser {
         }
         // Parse nodes first (they come before material properties in the blob)
         const nodes = [];
-        console.log(`\n=== Nodes from StowKit file (${metadata.nodeCount} total) ===`);
         for (let i = 0; i < metadata.nodeCount; i++) {
             if (offset + 116 > sourceBlob.length) {
                 console.warn(`Data truncated at node ${i}/${metadata.nodeCount}`);
@@ -109,11 +106,9 @@ class MeshParser {
                 meshCount: metaView.getUint32(offset + 108, true),
                 firstMeshIndex: metaView.getUint32(offset + 112, true)
             };
-            console.log(`Node ${i}: "${node.name}" (parent=${node.parentIndex}, meshCount=${node.meshCount}, firstMeshIndex=${node.firstMeshIndex})`);
             nodes.push(node);
             offset += 116; // Size of Node struct
         }
-        console.log(`=== End of nodes from file ===\n`);
         // Parse mesh indices
         const totalMeshRefs = nodes.reduce((sum, node) => sum + node.meshCount, 0);
         console.log(`Parsing ${totalMeshRefs} mesh indices at offset ${offset}`);
@@ -132,7 +127,6 @@ class MeshParser {
         // MaterialPropertyValue: field_name[64] + value[4*4=16] + texture_id[64] = 144 bytes
         for (let i = 0; i < materialData.length; i++) {
             const matData = materialData[i];
-            console.log(`Material "${matData.name}": schema="${matData.schemaId}", ${matData.propertyCount} properties`);
             for (let j = 0; j < matData.propertyCount; j++) {
                 if (offset + 144 > sourceBlob.length) {
                     console.warn(`Data truncated at property ${j}/${matData.propertyCount} of material ${i}`);
@@ -151,7 +145,6 @@ class MeshParser {
                     value,
                     textureId
                 });
-                console.log(`  Property "${fieldName}": value=[${value.join(', ')}], textureId="${textureId}"`);
                 offset += 144; // Size of MaterialPropertyValue
             }
             // Create Three.js material based on properties
@@ -161,16 +154,13 @@ class MeshParser {
                 // Start with default gray color
                 color: new THREE.Color(0.8, 0.8, 0.8)
             });
-            console.log(`Creating material ${i}: "${matData.name}", ${matData.propertyCount} properties`);
             // Apply properties
             for (const prop of matData.properties) {
                 if (prop.fieldName.toLowerCase() === 'tint' || prop.fieldName.toLowerCase().includes('color')) {
                     // Apply color/tint
                     mat.color = new THREE.Color(prop.value[0], prop.value[1], prop.value[2]);
-                    console.log(`  Applied tint color: rgb(${prop.value[0]}, ${prop.value[1]}, ${prop.value[2]})`);
                 }
             }
-            console.log(`  Material ${i} final color: rgb(${mat.color.r}, ${mat.color.g}, ${mat.color.b})`);
             materials.push(mat);
         }
         // Default material if none exist
@@ -188,14 +178,6 @@ class MeshParser {
      * Create Three.js BufferGeometry from Draco compressed mesh data
      */
     static async createGeometry(geoInfo, dataBlob, dracoLoader) {
-        console.log('Decoding Draco geometry:', {
-            vertexCount: geoInfo.vertexCount,
-            indexCount: geoInfo.indexCount,
-            hasNormals: geoInfo.hasNormals,
-            hasUVs: geoInfo.hasUVs,
-            compressedOffset: geoInfo.compressedBufferOffset,
-            compressedSize: geoInfo.compressedBufferSize
-        });
         // Extract the Draco compressed buffer
         if (geoInfo.compressedBufferOffset + geoInfo.compressedBufferSize > dataBlob.length) {
             throw new Error(`Compressed buffer out of bounds: offset=${geoInfo.compressedBufferOffset}, size=${geoInfo.compressedBufferSize}, dataLength=${dataBlob.length}`);
@@ -209,8 +191,7 @@ class MeshParser {
         const geometry = await new Promise((resolve, reject) => {
             dracoLoader.load(url, (decoded) => {
                 URL.revokeObjectURL(url);
-                console.log('Draco decoded successfully:', decoded);
-                // UVs are pre-flipped in the packer now, no need to flip here
+                // UVs are pre-flipped in the packer now
                 resolve(decoded);
             }, undefined, (error) => {
                 URL.revokeObjectURL(url);
@@ -221,13 +202,6 @@ class MeshParser {
         // Compute bounding volumes
         geometry.computeBoundingSphere();
         geometry.computeBoundingBox();
-        console.log('Final geometry:', {
-            hasPositions: !!geometry.attributes.position,
-            hasNormals: !!geometry.attributes.normal,
-            hasUVs: !!geometry.attributes.uv,
-            hasIndices: !!geometry.index,
-            vertexCount: geometry.attributes.position?.count || 0
-        });
         return geometry;
     }
     /**
@@ -237,18 +211,11 @@ class MeshParser {
         const root = new THREE.Group();
         root.name = 'StowKitMesh';
         const { geometries, materials, nodes, meshIndices } = parsedData;
-        console.log('Building scene with:', {
-            geometries: geometries.length,
-            materials: materials.length,
-            nodes: nodes.length,
-            meshIndices: meshIndices.length
-        });
         // Create all Three.js objects for nodes
         const nodeObjects = [];
         for (const node of nodes) {
             const obj = new THREE.Group();
             obj.name = node.name;
-            console.log(`Node ${node.name}: position=${node.position}, rotation=${node.rotation}, scale=${node.scale}, meshCount=${node.meshCount}, firstMeshIndex=${node.firstMeshIndex}`);
             // Apply transform
             obj.position.set(...node.position);
             obj.quaternion.set(...node.rotation);
@@ -257,10 +224,8 @@ class MeshParser {
             for (let i = 0; i < node.meshCount; i++) {
                 const meshIndexArrayPos = node.firstMeshIndex + i;
                 const meshIndex = meshIndices[meshIndexArrayPos];
-                console.log(`  meshIndices[${meshIndexArrayPos}] = ${meshIndex} (adding to node ${node.name})`);
                 if (meshIndex < geometries.length) {
                     const geoInfo = geometries[meshIndex];
-                    console.log(`  Creating geometry from geoInfo: vertices=${geoInfo.vertexCount}, indices=${geoInfo.indexCount}, material=${geoInfo.materialIndex}`);
                     const geometry = await this.createGeometry(geoInfo, dataBlob, dracoLoader);
                     // Use assigned material if valid, otherwise create default
                     let material;
@@ -278,35 +243,28 @@ class MeshParser {
                     }
                     const mesh = new THREE.Mesh(geometry, material);
                     obj.add(mesh);
-                    console.log(`  ✓ Added mesh to node ${node.name} (${geometry.attributes.position?.count || 0} vertices, material: ${material.name || 'default'})`);
                 }
                 else {
-                    console.error(`  ✗ Mesh index ${meshIndex} out of bounds (have ${geometries.length} geometries)`);
+                    console.error(`Mesh index ${meshIndex} out of bounds (${geometries.length} geometries available)`);
                 }
             }
-            console.log(`  Node ${node.name} now has ${obj.children.length} children`);
             nodeObjects.push(obj);
         }
         // Build hierarchy
-        console.log('Building node hierarchy...');
         for (let i = 0; i < nodes.length; i++) {
             const node = nodes[i];
             const obj = nodeObjects[i];
             if (node.parentIndex >= 0 && node.parentIndex < nodeObjects.length) {
-                console.log(`  Adding node "${node.name}" (index ${i}) as child of node "${nodes[node.parentIndex].name}" (index ${node.parentIndex})`);
                 nodeObjects[node.parentIndex].add(obj);
             }
             else {
-                console.log(`  Adding node "${node.name}" (index ${i}) as direct child of root (parentIndex=${node.parentIndex})`);
                 root.add(obj);
             }
         }
         // If no nodes, create a single mesh from all geometries
         if (nodes.length === 0 && geometries.length > 0) {
-            console.log('No nodes found, creating meshes directly from geometries');
             for (let index = 0; index < geometries.length; index++) {
                 const geoInfo = geometries[index];
-                console.log(`Creating direct mesh ${index}: materialIndex=${geoInfo.materialIndex}, vertices=${geoInfo.vertexCount}`);
                 const geometry = await this.createGeometry(geoInfo, dataBlob, dracoLoader);
                 // Use assigned material if valid, otherwise create default
                 let material;
@@ -325,33 +283,8 @@ class MeshParser {
                 const mesh = new THREE.Mesh(geometry, material);
                 mesh.name = `Mesh_${index}`;
                 root.add(mesh);
-                console.log(`Added mesh ${index} to root`);
             }
         }
-        console.log(`Final scene has ${root.children.length} direct children`);
-        // Debug: traverse and count all meshes, showing full hierarchy
-        let totalMeshCount = 0;
-        let hierarchyLog = 'Scene hierarchy:\n';
-        root.traverse((obj) => {
-            // Calculate depth by counting parents
-            let depth = 0;
-            let parent = obj.parent;
-            while (parent && parent !== root) {
-                depth++;
-                parent = parent.parent;
-            }
-            const indent = '  '.repeat(depth);
-            if (obj instanceof THREE.Mesh) {
-                totalMeshCount++;
-                const mat = obj.material;
-                hierarchyLog += `${indent}[Mesh] vertices=${obj.geometry.attributes.position?.count || 0}, material=${mat.name}, hasTexture=${!!mat.map}\n`;
-            }
-            else if (obj instanceof THREE.Group && obj !== root) {
-                hierarchyLog += `${indent}[Group] ${obj.name} (${obj.children.length} children)\n`;
-            }
-        });
-        console.log(hierarchyLog);
-        console.log(`Total meshes in scene: ${totalMeshCount}`);
         return root;
     }
     /**
@@ -374,6 +307,317 @@ class StowKitPack {
         this.ktx2Loader = ktx2Loader;
         this.dracoLoader = dracoLoader;
     }
+    /**
+     * Load a skinned mesh by its string ID
+     */
+    async loadSkinnedMesh(stringId) {
+        const assetIndex = this.reader.findAssetByPath(stringId);
+        if (assetIndex < 0) {
+            throw new Error(`Skinned mesh not found: ${stringId}`);
+        }
+        const data = this.reader.readAssetData(assetIndex);
+        const metadata = this.reader.readAssetMetadata(assetIndex);
+        if (!data)
+            throw new Error(`Failed to read skinned mesh data: ${stringId}`);
+        if (!metadata)
+            throw new Error(`No metadata for skinned mesh: ${stringId}`);
+        return await this.parseSkinnedMesh(metadata, data);
+    }
+    /**
+     * Parse skinned mesh from binary data
+     */
+    async parseSkinnedMesh(metadata, data) {
+        // Parse skinned mesh metadata
+        const view = new DataView(metadata.buffer, metadata.byteOffset, metadata.byteLength);
+        const decoder = new TextDecoder();
+        // SkinnedMeshMetadata: 4 uint32s (16 bytes) THEN string_id[128] = 144 bytes total
+        const meshGeometryCount = view.getUint32(0, true);
+        const materialCount = view.getUint32(4, true);
+        const nodeCount = view.getUint32(8, true);
+        const boneCount = view.getUint32(12, true);
+        const stringIdBytes = metadata.slice(16, 144);
+        const stringIdNullIndex = stringIdBytes.indexOf(0);
+        const stringId = decoder
+            .decode(stringIdBytes.slice(0, stringIdNullIndex >= 0 ? stringIdNullIndex : 128))
+            .trim();
+        let offset = 144;
+        // Parse all geometry infos
+        const geometryInfos = [];
+        // SkinnedMeshGeometryInfo: 4 uint32s + 6 uint64s + 2 uint32s = 16 + 48 + 8 = 72 bytes
+        // Layout: vertex_count, index_count, has_normals, has_uvs (16 bytes)
+        //         vertex_buffer_offset, vertex_buffer_size, index_buffer_offset, index_buffer_size, weights_offset, weights_size (48 bytes)
+        //         material_index, _padding (8 bytes)
+        for (let g = 0; g < meshGeometryCount; g++) {
+            if (offset + 72 > metadata.length) {
+                throw new Error(`Metadata too small for geometry ${g}`);
+            }
+            geometryInfos.push({
+                vertexCount: view.getUint32(offset, true),
+                indexCount: view.getUint32(offset + 4, true),
+                hasNormals: view.getUint32(offset + 8, true),
+                hasUVs: view.getUint32(offset + 12, true),
+                vertexBufferOffset: Number(view.getBigUint64(offset + 16, true)),
+                vertexBufferSize: Number(view.getBigUint64(offset + 24, true)),
+                indexBufferOffset: Number(view.getBigUint64(offset + 32, true)),
+                indexBufferSize: Number(view.getBigUint64(offset + 40, true)),
+                weightsOffset: Number(view.getBigUint64(offset + 48, true)),
+                weightsSize: Number(view.getBigUint64(offset + 56, true)),
+                materialIndex: view.getUint32(offset + 64, true)
+                // _padding at offset + 68 (ignored)
+            });
+            offset += 72;
+        }
+        const dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        // Sort geometry infos by vertex buffer offset to ensure sequential parsing
+        const sortedGeometryInfos = geometryInfos.slice().sort((a, b) => a.vertexBufferOffset - b.vertexBufferOffset);
+        // Parse materials from metadata (immediately after geometries)
+        let metadataOffset = 144 + meshGeometryCount * 72;
+        const materialData = [];
+        // Parse MaterialData headers
+        for (let i = 0; i < materialCount; i++) {
+            if (metadataOffset + 196 > metadata.length) {
+                console.warn('Skinned mesh metadata truncated while reading material headers');
+                break;
+            }
+            const nameBytes = metadata.slice(metadataOffset, metadataOffset + 64);
+            const schemaIdBytes = metadata.slice(metadataOffset + 64, metadataOffset + 192);
+            const name = decoder.decode(nameBytes.slice(0, nameBytes.indexOf(0) || 64));
+            const schemaId = decoder.decode(schemaIdBytes.slice(0, schemaIdBytes.indexOf(0) || 128));
+            const propertyCount = view.getUint32(metadataOffset + 192, true);
+            materialData.push({ name, schemaId, propertyCount, properties: [] });
+            metadataOffset += 196;
+        }
+        // Skip Node array and node_mesh_indices (not needed for rendering)
+        // Node struct: transform[16 floats] + name[64 bytes] + mesh_index[4 bytes] + parent_index[4 bytes] = 116 bytes
+        const NODE_STRIDE = 116;
+        metadataOffset += nodeCount * NODE_STRIDE;
+        metadataOffset += nodeCount * 4;
+        // Parse material properties
+        const PROPERTY_STRIDE = 144;
+        for (let i = 0; i < materialCount; i++) {
+            const mat = materialData[i];
+            for (let p = 0; p < mat.propertyCount; p++) {
+                try {
+                    if (metadataOffset + PROPERTY_STRIDE > metadata.length) {
+                        break;
+                    }
+                    const fieldNameBytes = metadata.slice(metadataOffset, metadataOffset + 64);
+                    const fieldName = decoder
+                        .decode(fieldNameBytes.slice(0, fieldNameBytes.indexOf(0) || 64))
+                        .trim();
+                    const value = [
+                        view.getFloat32(metadataOffset + 64, true),
+                        view.getFloat32(metadataOffset + 68, true),
+                        view.getFloat32(metadataOffset + 72, true),
+                        view.getFloat32(metadataOffset + 76, true)
+                    ];
+                    const textureIdBytes = metadata.slice(metadataOffset + 80, metadataOffset + 144);
+                    const textureIdNullIndex = textureIdBytes.indexOf(0);
+                    const textureId = (textureIdNullIndex >= 0
+                        ? decoder.decode(textureIdBytes.slice(0, textureIdNullIndex))
+                        : decoder.decode(textureIdBytes))
+                        .trim();
+                    mat.properties.push({ fieldName, value, textureId });
+                    metadataOffset += PROPERTY_STRIDE;
+                }
+                catch (err) {
+                    throw err;
+                }
+            }
+        }
+        // Parse bones
+        const BONE_STRIDE = 64 + 4 + 16 * 4;
+        const bones = [];
+        const parentIndices = [];
+        const boneMatrices = [];
+        const boneOriginalNames = [];
+        const bindPoses = [];
+        for (let i = 0; i < boneCount; i++) {
+            if (metadataOffset + BONE_STRIDE > metadata.length) {
+                throw new Error(`Skinned mesh metadata truncated while reading bone ${i}`);
+            }
+            const nameBytes = new Uint8Array(metadata.buffer, metadata.byteOffset + metadataOffset, 64);
+            const nullIndex = nameBytes.indexOf(0);
+            const rawName = decoder.decode(nameBytes.subarray(0, nullIndex >= 0 ? nullIndex : 64)).trim();
+            const parentIndex = view.getInt32(metadataOffset + 64, true);
+            const offsetMatrix = new THREE.Matrix4();
+            const matrixElements = new Float32Array(16);
+            for (let j = 0; j < 16; j++) {
+                matrixElements[j] = view.getFloat32(metadataOffset + 68 + j * 4, true);
+            }
+            offsetMatrix.fromArray(matrixElements);
+            const sanitizedName = this.sanitizeTrackName(rawName);
+            const bone = new THREE.Bone();
+            bone.name = sanitizedName;
+            bone.userData.originalName = rawName;
+            bones.push(bone);
+            parentIndices.push(parentIndex);
+            boneMatrices.push(offsetMatrix);
+            boneOriginalNames.push(rawName);
+            bindPoses.push(offsetMatrix.clone().invert());
+            metadataOffset += BONE_STRIDE;
+        }
+        // Build bone hierarchy
+        for (let i = 0; i < bones.length; i++) {
+            const parentIndex = parentIndices[i];
+            if (parentIndex >= 0 && parentIndex < bones.length && parentIndex !== i) {
+                bones[parentIndex].add(bones[i]);
+            }
+        }
+        // Set bones to bind pose for correct static display
+        for (let i = 0; i < bones.length; i++) {
+            const bone = bones[i];
+            const bindPose = bindPoses[i];
+            const parentIndex = parentIndices[i];
+            if (parentIndex < 0) {
+                const pos = new THREE.Vector3();
+                const quat = new THREE.Quaternion();
+                const scale = new THREE.Vector3();
+                bindPose.decompose(pos, quat, scale);
+                bone.position.copy(pos);
+                bone.quaternion.copy(quat);
+                bone.scale.set(1, 1, 1);
+            }
+            else {
+                const parentBindPose = bindPoses[parentIndex];
+                const parentInv = new THREE.Matrix4().copy(parentBindPose).invert();
+                const localMatrix = new THREE.Matrix4().multiplyMatrices(parentInv, bindPose);
+                const pos = new THREE.Vector3();
+                const quat = new THREE.Quaternion();
+                const scale = new THREE.Vector3();
+                localMatrix.decompose(pos, quat, scale);
+                bone.position.copy(pos);
+                bone.quaternion.copy(quat);
+                bone.scale.set(1, 1, 1);
+            }
+            bone.updateMatrix();
+        }
+        // Create Three.js materials with properties (same as static meshes)
+        const materials = [];
+        for (let i = 0; i < materialCount; i++) {
+            const mat = materialData[i];
+            const material = new THREE.MeshStandardMaterial({
+                side: THREE.DoubleSide,
+                name: mat.name || `Material_${i}`,
+                color: new THREE.Color(0.8, 0.8, 0.8) // Default gray
+            });
+            // Apply non-texture properties
+            for (const prop of mat.properties) {
+                const fieldName = prop.fieldName.toLowerCase();
+                // Handle color properties
+                if (fieldName.includes('color') || fieldName.includes('tint')) {
+                    material.color.setRGB(prop.value[0], prop.value[1], prop.value[2]);
+                }
+                else if (fieldName === 'metallic') {
+                    material.metalness = prop.value[0];
+                }
+                else if (fieldName === 'roughness') {
+                    material.roughness = prop.value[0];
+                }
+            }
+            materials.push(material);
+        }
+        await this.loadMaterialTextures(materialData, materials);
+        // Collect root bones (hierarchy already built earlier)
+        const rootBones = bones.filter((_, index) => parentIndices[index] < 0);
+        // Create shared skeleton
+        const skeleton = new THREE.Skeleton(bones, boneMatrices);
+        // Pre-allocate combined buffers
+        const totalVertexCount = sortedGeometryInfos.reduce((sum, info) => sum + info.vertexCount, 0);
+        const totalIndexCount = sortedGeometryInfos.reduce((sum, info) => sum + info.indexCount, 0);
+        const combinedPositions = new Float32Array(totalVertexCount * 3);
+        const combinedNormals = new Float32Array(totalVertexCount * 3);
+        const combinedUVs = new Float32Array(totalVertexCount * 2);
+        const combinedSkinIndices = new Uint16Array(totalVertexCount * 4);
+        const combinedSkinWeights = new Float32Array(totalVertexCount * 4);
+        const combinedIndices = new Uint32Array(totalIndexCount);
+        const combinedGeometry = new THREE.BufferGeometry();
+        combinedGeometry.clearGroups();
+        let vertexCursor = 0; // counts vertices
+        let indexCursor = 0; // counts indices
+        for (const geomInfo of sortedGeometryInfos) {
+            const vertexStrideBytes = 32;
+            const vertexBase = vertexCursor; // base vertex index for this submesh
+            // Validate offsets before parsing
+            const requiredVertexBytes = geomInfo.vertexBufferOffset + geomInfo.vertexCount * vertexStrideBytes;
+            const requiredIndexBytes = geomInfo.indexBufferOffset + geomInfo.indexCount * 4;
+            const requiredWeightBytes = geomInfo.weightsOffset + geomInfo.vertexCount * 32;
+            if (requiredVertexBytes > data.byteLength) {
+                throw new Error(`Vertex buffer out of bounds: need ${requiredVertexBytes}, have ${data.byteLength}`);
+            }
+            if (requiredIndexBytes > data.byteLength) {
+                throw new Error(`Index buffer out of bounds: need ${requiredIndexBytes}, have ${data.byteLength}`);
+            }
+            if (requiredWeightBytes > data.byteLength) {
+                throw new Error(`Weight buffer out of bounds: need ${requiredWeightBytes}, have ${data.byteLength}`);
+            }
+            // Parse vertices
+            for (let v = 0; v < geomInfo.vertexCount; v++) {
+                const vertexOffset = geomInfo.vertexBufferOffset + v * vertexStrideBytes;
+                // positions
+                combinedPositions[(vertexCursor + v) * 3 + 0] = dataView.getFloat32(vertexOffset + 0, true);
+                combinedPositions[(vertexCursor + v) * 3 + 1] = dataView.getFloat32(vertexOffset + 4, true);
+                combinedPositions[(vertexCursor + v) * 3 + 2] = dataView.getFloat32(vertexOffset + 8, true);
+                // normals
+                if (geomInfo.hasNormals) {
+                    combinedNormals[(vertexCursor + v) * 3 + 0] = dataView.getFloat32(vertexOffset + 12, true);
+                    combinedNormals[(vertexCursor + v) * 3 + 1] = dataView.getFloat32(vertexOffset + 16, true);
+                    combinedNormals[(vertexCursor + v) * 3 + 2] = dataView.getFloat32(vertexOffset + 20, true);
+                }
+                // uvs
+                if (geomInfo.hasUVs) {
+                    combinedUVs[(vertexCursor + v) * 2 + 0] = dataView.getFloat32(vertexOffset + 24, true);
+                    combinedUVs[(vertexCursor + v) * 2 + 1] = dataView.getFloat32(vertexOffset + 28, true);
+                }
+                // bone indices & weights
+                const weightOffset = geomInfo.weightsOffset + v * 32;
+                for (let j = 0; j < 4; j++) {
+                    const boneIndex = dataView.getUint32(weightOffset + j * 4, true);
+                    combinedSkinIndices[(vertexCursor + v) * 4 + j] = boneIndex < boneCount ? boneIndex : 0;
+                }
+                for (let j = 0; j < 4; j++) {
+                    combinedSkinWeights[(vertexCursor + v) * 4 + j] = dataView.getFloat32(weightOffset + 16 + j * 4, true);
+                }
+            }
+            // Parse indices
+            const groupStart = indexCursor;
+            for (let i = 0; i < geomInfo.indexCount; i++) {
+                const indexValue = dataView.getUint32(geomInfo.indexBufferOffset + i * 4, true);
+                combinedIndices[indexCursor + i] = indexValue + vertexBase;
+            }
+            combinedGeometry.addGroup(groupStart, geomInfo.indexCount, Math.min(geomInfo.materialIndex, materials.length - 1));
+            vertexCursor += geomInfo.vertexCount;
+            indexCursor += geomInfo.indexCount;
+        }
+        combinedGeometry.setAttribute('position', new THREE.BufferAttribute(combinedPositions, 3));
+        if (geometryInfos.some(info => info.hasNormals)) {
+            combinedGeometry.setAttribute('normal', new THREE.BufferAttribute(combinedNormals, 3));
+        }
+        if (geometryInfos.some(info => info.hasUVs)) {
+            combinedGeometry.setAttribute('uv', new THREE.BufferAttribute(combinedUVs, 2));
+        }
+        combinedGeometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(combinedSkinIndices, 4));
+        combinedGeometry.setAttribute('skinWeight', new THREE.BufferAttribute(combinedSkinWeights, 4));
+        combinedGeometry.setIndex(new THREE.BufferAttribute(combinedIndices, 1));
+        combinedGeometry.computeBoundingBox();
+        combinedGeometry.computeBoundingSphere();
+        const skinnedMesh = new THREE.SkinnedMesh(combinedGeometry, materials);
+        // Create a separate bone container to preserve hierarchy
+        const boneContainer = new THREE.Group();
+        boneContainer.name = 'BoneContainer';
+        rootBones.forEach((root) => boneContainer.add(root));
+        // Bind skeleton with our provided inverse bind matrices
+        skinnedMesh.bind(skeleton, skinnedMesh.matrixWorld);
+        skinnedMesh.normalizeSkinWeights();
+        skinnedMesh.updateMatrixWorld(true);
+        const container = new THREE.Group();
+        container.name = stringId || 'SkinnedMesh';
+        container.add(boneContainer);
+        container.add(skinnedMesh);
+        container.userData.boneOriginalNames = boneOriginalNames;
+        container.userData.skinnedMesh = skinnedMesh;
+        return container;
+    }
     /**
      * Load a mesh by its canonical path/name
      */
@@ -471,10 +715,16 @@ class StowKitPack {
         return this.reader.readAssetMetadata(index);
     }
     /**
-     * Parse texture metadata
+     * Load skinned mesh by index
      */
-    parseTextureMetadata(metadataBytes) {
-        return this.reader.parseTextureMetadata(metadataBytes);
+    async loadSkinnedMeshByIndex(index) {
+        const data = this.reader.readAssetData(index);
+        const metadata = this.reader.readAssetMetadata(index);
+        if (!data)
+            throw new Error(`Failed to read skinned mesh data for index ${index}`);
+        if (!metadata)
+            throw new Error(`No metadata for skinned mesh index ${index}`);
+        return await this.parseSkinnedMesh(metadata, data);
     }
     /**
      * Load mesh by index
@@ -516,56 +766,167 @@ class StowKitPack {
         return audio;
     }
     /**
-     * Get audio metadata by path
+     * Get audio metadata by path (uses WASM parsing)
      */
     getAudioMetadata(assetPath) {
         const assetIndex = this.reader.findAssetByPath(assetPath);
         if (assetIndex < 0)
             return null;
-        const metadata = this.reader.readAssetMetadata(assetIndex);
-        if (!metadata || metadata.length < 140)
-            return null;
-        const view = new DataView(metadata.buffer, metadata.byteOffset, metadata.byteLength);
-        const decoder = new TextDecoder();
-        const stringIdBytes = metadata.slice(0, 128);
-        const nullIdx = stringIdBytes.indexOf(0);
-        const stringId = decoder.decode(stringIdBytes.slice(0, nullIdx >= 0 ? nullIdx : 128));
-        return {
-            stringId,
-            sampleRate: view.getUint32(128, true),
-            channels: view.getUint32(132, true),
-            durationMs: view.getUint32(136, true)
-        };
+        return this.reader.parseAudioMetadata(assetIndex);
     }
     /**
-     * Load material schema by index
+     * Get animation metadata by index (uses WASM parsing)
      */
-    loadMaterialSchemaByIndex(index) {
-        return this.loadMaterialSchemaByIndex_internal(index);
+    getAnimationMetadata(index) {
+        return this.reader.parseAnimationMetadata(index);
     }
     /**
-     * Get mesh materials by index
+     * Get texture metadata by index (uses WASM parsing)
      */
-    getMeshMaterialsByIndex(index) {
-        return this.getMeshMaterialsByIndex_internal(index);
+    getTextureMetadata(index) {
+        return this.reader.parseTextureMetadata(index);
     }
     /**
-     * Get material schema information
+     * Load animation clip by string ID
      */
-    getMaterialSchema(assetPath) {
-        const assetIndex = this.reader.findAssetByPath(assetPath);
-        if (assetIndex < 0)
-            return null;
-        return this.loadMaterialSchemaByIndex_internal(assetIndex);
+    async loadAnimationClip(stringId) {
+        const index = this.reader.findAssetByPath(stringId);
+        if (index < 0) {
+            throw new Error(`Animation clip not found: ${stringId}`);
+        }
+        return this.loadAnimationClipByIndex(index);
     }
     /**
-     * Get mesh materials information
+     * Load and play animation on a skinned mesh group
      */
-    getMeshMaterials(assetPath) {
-        const assetIndex = this.reader.findAssetByPath(assetPath);
-        if (assetIndex < 0)
-            return null;
-        return this.getMeshMaterialsByIndex_internal(assetIndex);
+    async loadAnimation(skinnedMeshGroup, animationPath) {
+        const clip = await this.loadAnimationClip(animationPath);
+        const mixer = new THREE.AnimationMixer(skinnedMeshGroup);
+        const action = mixer.clipAction(clip);
+        action.setLoop(THREE.LoopRepeat, Infinity);
+        action.play();
+        return { mixer, action, clip };
+    }
+    /**
+     * Load and play animation by index
+     */
+    async loadAnimationByIndex(skinnedMeshGroup, animationIndex) {
+        const clip = await this.loadAnimationClipByIndex(animationIndex);
+        const mixer = new THREE.AnimationMixer(skinnedMeshGroup);
+        const action = mixer.clipAction(clip);
+        action.setLoop(THREE.LoopRepeat, Infinity);
+        action.play();
+        return { mixer, action, clip };
+    }
+    /**
+     * Load animation clip by index
+     */
+    async loadAnimationClipByIndex(index) {
+        const metadata = this.reader.readAssetMetadata(index);
+        const data = this.reader.readAssetData(index);
+        if (!metadata || !data) {
+            throw new Error('Failed to read animation clip data');
+        }
+        return this.parseAnimationClip(metadata, data);
+    }
+    /**
+     * Parse animation clip from binary data
+     */
+    parseAnimationClip(metadata, data) {
+        const view = new DataView(metadata.buffer, metadata.byteOffset, metadata.byteLength);
+        const decoder = new TextDecoder();
+        // Parse AnimationClipMetadata (272 bytes total)
+        const stringIdBytes = metadata.slice(0, 128);
+        const stringIdNullIndex = stringIdBytes.indexOf(0);
+        const stringId = decoder.decode(stringIdBytes.slice(0, stringIdNullIndex >= 0 ? stringIdNullIndex : 128));
+        const targetMeshIdBytes = metadata.slice(128, 256);
+        const targetMeshIdNullIndex = targetMeshIdBytes.indexOf(0);
+        decoder
+            .decode(targetMeshIdBytes.slice(0, targetMeshIdNullIndex >= 0 ? targetMeshIdNullIndex : 128))
+            .trim();
+        const durationSeconds = view.getFloat32(256, true); // Duration in seconds (per C header)
+        view.getFloat32(260, true); // For custom playback rate if needed
+        const channelCount = view.getUint32(264, true);
+        const boneCount = view.getUint32(268, true);
+        // Parse AnimationChannel[] (starts at offset 272, each is 28 bytes)
+        const channelsOffset = 272;
+        const channels = [];
+        for (let i = 0; i < channelCount; i++) {
+            const chOffset = channelsOffset + i * 28;
+            channels.push({
+                boneIndex: view.getUint32(chOffset, true),
+                keyframeType: view.getUint32(chOffset + 4, true),
+                keyframeCount: view.getUint32(chOffset + 8, true),
+                keyframeTimesOffset: Number(view.getBigUint64(chOffset + 12, true)),
+                keyframeValuesOffset: Number(view.getBigUint64(chOffset + 20, true))
+            });
+        }
+        // Parse AnimationBoneInfo[] (starts after all channels, each is 68 bytes)
+        const bonesOffset = channelsOffset + channelCount * 28;
+        const bones = [];
+        for (let i = 0; i < boneCount; i++) {
+            const boneOffset = bonesOffset + i * 68;
+            const nameBytes = metadata.slice(boneOffset, boneOffset + 64);
+            const nullIndex = nameBytes.indexOf(0);
+            const rawName = decoder
+                .decode(nameBytes.slice(0, nullIndex >= 0 ? nullIndex : 64))
+                .trim();
+            const sanitizedName = this.sanitizeTrackName(rawName);
+            const parentIndex = view.getInt32(boneOffset + 64, true);
+            bones.push({ name: rawName, parentIndex, sanitizedName });
+        }
+        // Create DataView for keyframe data
+        const dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        // Create Three.js KeyframeTracks
+        const tracks = [];
+        let maxKeyframeTime = 0;
+        // Process channels - each channel specifies which bone it animates via boneIndex
+        for (let i = 0; i < channelCount; i++) {
+            const channel = channels[i];
+            // Validate bone index
+            if (channel.boneIndex >= boneCount) {
+                console.warn(`[AnimationClip] Channel ${i} references invalid bone index ${channel.boneIndex} (have ${boneCount} bones)`);
+                continue;
+            }
+            const boneName = bones[channel.boneIndex].sanitizedName;
+            // Skip scale tracks - bones should always have unit scale
+            if (channel.keyframeType === 2) {
+                continue;
+            }
+            // Read times (already in seconds per C header)
+            const times = this.readFloatArray(dataView, channel.keyframeTimesOffset, channel.keyframeCount);
+            // Track the maximum keyframe time to calculate actual duration
+            if (times.length > 0) {
+                const channelMaxTime = times[times.length - 1];
+                if (channelMaxTime > maxKeyframeTime) {
+                    maxKeyframeTime = channelMaxTime;
+                }
+            }
+            // Create track based on keyframe type
+            if (channel.keyframeType === 0) {
+                // Position (vec3)
+                const values = this.readFloatArray(dataView, channel.keyframeValuesOffset, channel.keyframeCount * 3);
+                tracks.push(new THREE.VectorKeyframeTrack(`${boneName}.position`, times, values));
+            }
+            else if (channel.keyframeType === 1) {
+                // Rotation (quaternion)
+                const values = this.readFloatArray(dataView, channel.keyframeValuesOffset, channel.keyframeCount * 4);
+                tracks.push(new THREE.QuaternionKeyframeTrack(`${boneName}.quaternion`, times, values));
+            }
+        }
+        // Use the actual maximum keyframe time as duration instead of metadata duration
+        const actualDuration = maxKeyframeTime > 0 ? maxKeyframeTime : durationSeconds;
+        return new THREE.AnimationClip(stringId, actualDuration, tracks);
+    }
+    /**
+     * Helper to read float array from DataView
+     */
+    readFloatArray(view, offset, count) {
+        const result = new Float32Array(count);
+        for (let i = 0; i < count; i++) {
+            result[i] = view.getFloat32(offset + i * 4, true);
+        }
+        return result;
     }
     /**
      * Close the pack and free resources
@@ -579,13 +940,15 @@ class StowKitPack {
             const matData = materialData[i];
             const material = materials[i];
             for (const prop of matData.properties) {
-                if (prop.textureId && prop.textureId.length > 0) {
+                // Trim and check for truly non-empty texture ID
+                const textureId = prop.textureId?.trim();
+                if (textureId && textureId.length > 0) {
                     try {
-                        const texture = await this.loadTexture(prop.textureId);
+                        const texture = await this.loadTexture(textureId);
                         this.applyTextureToMaterial(material, prop.fieldName, texture);
                     }
                     catch (error) {
-                        console.error(`Failed to load texture "${prop.textureId}":`, error);
+                        console.error(`Failed to load texture "${textureId}":`, error);
                     }
                 }
             }
@@ -632,88 +995,11 @@ class StowKitPack {
         }
         material.needsUpdate = true;
     }
-    loadMaterialSchemaByIndex_internal(index) {
-        const metadata = this.reader.readAssetMetadata(index);
-        if (!metadata || metadata.length < 196)
-            return null;
-        const view = new DataView(metadata.buffer, metadata.byteOffset, metadata.byteLength);
-        const decoder = new TextDecoder();
-        const stringIdBytes = metadata.slice(0, 128);
-        const schemaNameBytes = metadata.slice(128, 192);
-        const stringId = decoder.decode(stringIdBytes.slice(0, stringIdBytes.indexOf(0) || 128));
-        const schemaName = decoder.decode(schemaNameBytes.slice(0, schemaNameBytes.indexOf(0) || 64));
-        const fieldCount = view.getUint32(192, true);
-        const fields = [];
-        let offset = 196;
-        for (let i = 0; i < fieldCount; i++) {
-            if (offset + 88 > metadata.length)
-                break;
-            const fieldNameBytes = metadata.slice(offset, offset + 64);
-            const fieldName = decoder.decode(fieldNameBytes.slice(0, fieldNameBytes.indexOf(0) || 64));
-            const fieldType = view.getUint32(offset + 64, true);
-            const previewFlags = view.getUint32(offset + 68, true);
-            const defaultValue = [
-                view.getFloat32(offset + 72, true),
-                view.getFloat32(offset + 76, true),
-                view.getFloat32(offset + 80, true),
-                view.getFloat32(offset + 84, true)
-            ];
-            const typeNames = ['Texture', 'Color', 'Float', 'Vec2', 'Vec3', 'Vec4', 'Int'];
-            const previewFlagNames = ['None', 'MainTex', 'Tint'];
-            fields.push({
-                name: fieldName,
-                type: typeNames[fieldType] || 'Float',
-                previewFlag: previewFlagNames[previewFlags] || 'None',
-                defaultValue
-            });
-            offset += 88;
-        }
-        return { stringId, schemaName, fields };
-    }
-    getMeshMaterialsByIndex_internal(index) {
-        const metadata = this.reader.readAssetMetadata(index);
-        if (!metadata || metadata.length < 140)
-            return null;
-        const view = new DataView(metadata.buffer, metadata.byteOffset, metadata.byteLength);
-        const decoder = new TextDecoder();
-        const meshGeometryCount = view.getUint32(0, true);
-        const materialCount = view.getUint32(4, true);
-        const nodeCount = view.getUint32(8, true);
-        let offset = 140;
-        offset += meshGeometryCount * 40;
-        const materials = [];
-        for (let i = 0; i < materialCount; i++) {
-            if (offset + 196 > metadata.length)
-                break;
-            const nameBytes = metadata.slice(offset, offset + 64);
-            const schemaIdBytes = metadata.slice(offset + 64, offset + 192);
-            const name = decoder.decode(nameBytes.slice(0, nameBytes.indexOf(0) || 64));
-            const schemaId = decoder.decode(schemaIdBytes.slice(0, schemaIdBytes.indexOf(0) || 128));
-            const propertyCount = view.getUint32(offset + 192, true);
-            materials.push({ name, schemaId, propertyCount, properties: [] });
-            offset += 196;
-        }
-        offset += nodeCount * 116;
-        offset += nodeCount * 4;
-        for (const mat of materials) {
-            for (let j = 0; j < mat.propertyCount; j++) {
-                if (offset + 144 > metadata.length)
-                    break;
-                const fieldNameBytes = metadata.slice(offset, offset + 64);
-                const fieldName = decoder.decode(fieldNameBytes.slice(0, fieldNameBytes.indexOf(0) || 64));
-                const value = [
-                    view.getFloat32(offset + 64, true),
-                    view.getFloat32(offset + 68, true),
-                    view.getFloat32(offset + 72, true),
-                    view.getFloat32(offset + 76, true)
-                ];
-                const textureIdBytes = metadata.slice(offset + 80, offset + 144);
-                const textureId = decoder.decode(textureIdBytes.slice(0, textureIdBytes.indexOf(0) || 64));
-                mat.properties.push({ fieldName, value, textureId });
-                offset += 144;
-            }
-        }
-        return materials;
+    sanitizeTrackName(name) {
+        return name
+            .trim()
+            .replace(/[^A-Za-z0-9_\-]+/g, '_')
+            .replace(/_{2,}/g, '_');
     }
 }
 
@@ -761,7 +1047,10 @@ class StowKitLoader {
         if (data instanceof ArrayBuffer) {
             arrayBuffer = data;
         }
-        else if (data instanceof Blob || data instanceof File) {
+        else if (typeof Blob !== 'undefined' && data instanceof Blob) {
+            arrayBuffer = await data.arrayBuffer();
+        }
+        else if ('arrayBuffer' in data && typeof data.arrayBuffer === 'function') {
             arrayBuffer = await data.arrayBuffer();
         }
         else {