@stowkit/three-loader 0.1.15 → 0.1.17

package/README.md

@@ -1,6 +1,6 @@
 # @stowkit/three-loader
 
-Three.js loader for StowKit asset packs. Provides a simple, high-level API for loading meshes, textures, and audio from `.stow` files into Three.js applications.
+Three.js loader for StowKit asset packs. Provides a simple, high-level API for loading meshes, skinned meshes, animations, textures, and audio from `.stow` files.
 
 ## Installation
 
@@ -11,301 +11,252 @@ npm install @stowkit/three-loader three
 ## Quick Start
 
 ```typescript
-import { StowKitLoader } from '@stowkit/three-loader';
+import { StowKitLoader, AssetType } from '@stowkit/three-loader';
 
-// Load a pack (auto-initializes with defaults)
 const pack = await StowKitLoader.load('assets.stow');
+// from memory
+const packFromMemory = await StowKitLoader.loadFromMemory(someData);
 
-// Load assets by name
 const mesh = await pack.loadMesh('character');
-const texture = await pack.loadTexture('wood');
-const audio = await pack.loadAudio('bgm', audioListener);
-
-// Use in Three.js
 scene.add(mesh);
-material.map = texture;
-audio.play();
+
+const character = await pack.loadSkinnedMesh('player');
+scene.add(character);
+
+const { mixer } = await pack.loadAnimation(character, 'walk');
+
+// Update in your animation loop
+function animate() {
+    const delta = clock.getDelta();
+    mixer.update(delta);
+    renderer.render(scene, camera);
+}
 ```
 
 ## Features
 
-- ✅ **Zero configuration** - Works out of the box with sensible defaults
-- ✅ **Draco mesh compression** - All meshes use Draco compression for smaller file sizes
-- ✅ **Automatic texture loading** - Materials reference textures by ID, loader handles everything
-- ✅ **Material system** - Full support for material schemas, properties, and assignments
-- ✅ **KTX2/Basis Universal** - GPU-compressed textures with automatic transcoding
-- ✅ **Scene hierarchy** - Preserves transforms, parent-child relationships, and node structure
-- ✅ **Multi-material meshes** - Supports meshes with multiple materials/submeshes
-- ✅ **Draco decoder included** - No need to download separately, auto-copied on install
-- ✅ **Type-safe** - Full TypeScript definitions included
+- ✅ **Static Meshes** - Draco-compressed meshes with automatic material/texture loading
+- ✅ **Skinned Meshes** - Skeletal meshes with bone hierarchy
+- ✅ **Animations** - Skeletal animations with automatic mixer setup
+- ✅ **Textures** - KTX2/Basis Universal GPU-compressed textures
+- ✅ **Audio** - OGG/MP3 audio with Three.js Audio integration
+- ✅ **WASM Parsing** - All binary parsing done in WASM for performance
+- ✅ **Type Safe** - Full TypeScript support
+- ✅ **Zero Config** - Works out of the box
 
 ## API Reference
 
-### Loading Packs
+### Asset Manifest
 
-#### `StowKitLoader.load(url: string, options?: StowKitLoaderOptions): Promise<StowKitPack>`
+#### `pack.listAssets(): AssetListItem[]`
 
-Load a .stow pack file. Returns a `StowKitPack` instance for loading assets.
+Get the complete manifest of all assets in the pack.
 
-**Options (all optional):**
 ```typescript
-interface StowKitLoaderOptions {
-  basisPath?: string;   // Path to Basis Universal transcoder (default: '/stowkit/basis/')
-  dracoPath?: string;   // Path to Draco decoder (default: '/stowkit/draco/')
-  wasmPath?: string;    // Path to WASM reader module (default: '/stowkit_reader.wasm')
-}
-```
-
-**Examples:**
-```typescript
-// Load from URL
 const pack = await StowKitLoader.load('assets.stow');
+const manifest = pack.listAssets();
+
+console.log(`Pack contains ${manifest.length} assets`);
 
-// Load with custom paths
-const pack = await StowKitLoader.load('game.stow', {
-  basisPath: '/custom/basis/',
-  dracoPath: '/custom/draco/',
-  wasmPath: '/custom/stowkit_reader.wasm'
+manifest.forEach(asset => {
+    console.log(`[${asset.index}] ${asset.name || asset.id}`);
+    console.log(`  Type: ${getTypeName(asset.type)}`);
+    console.log(`  Size: ${formatBytes(asset.dataSize)}`);
+    console.log(`  Has Metadata: ${asset.hasMetadata}`);
 });
-```
 
-#### `StowKitLoader.loadFromMemory(data: ArrayBuffer | Blob | File, options?: StowKitLoaderOptions): Promise<StowKitPack>`
+// Filter by type
+const meshes = manifest.filter(a => a.type === AssetType.STATIC_MESH);
+const textures = manifest.filter(a => a.type === AssetType.TEXTURE_2D);
+const audio = manifest.filter(a => a.type === AssetType.AUDIO);
+const skinnedMeshes = manifest.filter(a => a.type === AssetType.SKINNED_MESH);
+const animations = manifest.filter(a => a.type === AssetType.ANIMATION_CLIP);
 
-Load a .stow pack from memory. Useful for cached data or file inputs.
+console.log(`${meshes.length} meshes, ${textures.length} textures, ${animations.length} animations`);
+```
 
-**Examples:**
+**AssetListItem structure:**
 ```typescript
-// From cached blob storage
-const cachedBlob = await cache.get('assets.stow');
-const pack = await StowKitLoader.loadFromMemory(cachedBlob);
-
-// From file input
-const file = input.files[0];
-const pack = await StowKitLoader.loadFromMemory(file);
-
-// From ArrayBuffer
-const buffer = new ArrayBuffer(...);
-const pack = await StowKitLoader.loadFromMemory(buffer);
+{
+    index: number;           // Asset index
+    type: number;            // Asset type ID (1-6)
+    name?: string;           // Extracted from metadata (if available)
+    id: bigint;              // Unique asset ID
+    dataSize: number;        // Size of asset data in bytes
+    metadataSize: number;    // Size of metadata in bytes
+    hasMetadata: boolean;    // Whether metadata exists
+    data_offset: number;     // Internal use
+    data_size: number;       // Internal use
+    metadata_offset: number; // Internal use
+    metadata_size: number;   // Internal use
+}
 ```
 
-### StowKitPack Methods
+#### `pack.getAssetCount(): number`
 
-Once you have a pack loaded, use these methods to load assets:
+Get total number of assets in the pack.
 
-### Loading Meshes
+```typescript
+const count = pack.getAssetCount();
+console.log(`Pack has ${count} assets`);
+```
 
-#### `pack.loadMesh(stringId: string): Promise<THREE.Group>`
+#### `pack.getAssetInfo(index: number): AssetInfo | null`
 
-Load a mesh by its string ID (the canonical path used when packing). Automatically loads and applies textures and materials.
+Get detailed info about a specific asset.
 
 ```typescript
-// String IDs are whatever you used when packing the assets
-const cookingStation = await pack.loadMesh('restaurant_display_cooking_station');
-const door = await pack.loadMesh('restaurant_display_door');
-const physics = await pack.loadMesh('restaurant_physics');
-
-scene.add(cookingStation);
-scene.add(door);
-scene.add(physics);
+const info = pack.getAssetInfo(5);
+if (info) {
+    console.log(`Type: ${info.type}, Size: ${info.data_size} bytes`);
+}
 ```
 
-**What you get:**
-- ✅ Complete scene hierarchy with nodes
-- ✅ Draco-decompressed geometry (vertices, normals, UVs, indices)  
-- ✅ Materials with colors, properties applied
-- ✅ Textures automatically loaded and applied
-- ✅ Transforms (position, rotation, scale) preserved
+### Loading Assets
 
-### Loading Textures
-
-#### `pack.loadTexture(stringId: string): Promise<THREE.CompressedTexture>`
-
-Load a KTX2 texture by its string ID (the canonical path used when packing).
+#### Static Meshes
 
 ```typescript
-const shadow = await pack.loadTexture('_shadow');
-const atlas = await pack.loadTexture('zy_Atlas');
+// Load by string ID
+const mesh = await pack.loadMesh('models/building.mesh');
+scene.add(mesh);
 
-shadowMaterial.map = shadow;
-particleMaterial.map = atlas;
-material.needsUpdate = true;
+// Load by index
+const mesh = await pack.loadMeshByIndex(5);
+scene.add(mesh);
 ```
 
-### Loading Audio
-
-#### `pack.loadAudio(stringId: string, listener: THREE.AudioListener): Promise<THREE.Audio>`
+Returns a `THREE.Group` containing the mesh hierarchy with materials and textures applied.
 
-Load audio by its string ID (the canonical path used when packing).
+#### Skinned Meshes
 
 ```typescript
-const listener = new THREE.AudioListener();
-camera.add(listener);
-
-const bgm = await pack.loadAudio('track_01', listener);
-bgm.setLoop(true);
-bgm.setVolume(0.5);
-bgm.play();
+// Load by string ID
+const character = await pack.loadSkinnedMesh('characters/player.skinned');
+scene.add(character);
 
-// More audio
-const click = await pack.loadAudio('click', listener);
-const cashRegister = await pack.loadAudio('cash register', listener);
+// Load by index
+const character = await pack.loadSkinnedMeshByIndex(8);
+scene.add(character);
 ```
 
-#### `createAudioPreview(index: number): Promise<HTMLAudioElement>`
+Returns a `THREE.Group` containing the skinned mesh with skeleton and bones in bind pose.
 
-Create an HTML5 audio element for previewing audio (simpler than Three.js Audio).
+#### Animations
 
 ```typescript
-const audioElement = await loader.createAudioPreview(index);
-audioElement.autoplay = true;
-container.appendChild(audioElement);
+// Load and play animation (returns mixer, action, clip)
+const { mixer, action, clip } = await pack.loadAnimation(
+    skinnedMeshGroup,
+    'animations/walk.anim'
+);
+
+// Or by index
+const { mixer, action, clip } = await pack.loadAnimationByIndex(
+    skinnedMeshGroup,
+    9
+);
+
+// Update in your animation loop
+const clock = new THREE.Clock();
+function animate() {
+    requestAnimationFrame(animate);
+    mixer.update(clock.getDelta());
+    renderer.render(scene, camera);
+}
 ```
 
-### Material Information
-
-#### `loadMaterialSchema(assetPath: string): object | null`
+The `loadAnimation` methods automatically:
+- Create an `AnimationMixer` on the correct root object
+- Set the animation to loop infinitely
+- Start playing immediately
+- Return everything you need
 
-Load material schema definition.
+#### Textures
 
 ```typescript
-const schema = loader.loadMaterialSchema('shaders/DefaultShader.stowschema');
-
-console.log(schema.schemaName);  // "Default Shader"
-console.log(schema.fields);      // Array of field definitions
+// Load by string ID
+const texture = await pack.loadTexture('textures/wood.ktx2');
+material.map = texture;
 
-schema.fields.forEach(field => {
-  console.log(`${field.name}: ${field.type}`);
-  // mainTex: Texture
-  // tint: Color
-  // roughness: Float
-});
+// Load by index
+const texture = await pack.loadTextureByIndex(2);
 ```
 
-#### `loadMaterialSchemaByIndex(index: number): object | null`
+Returns a `THREE.CompressedTexture` (KTX2/Basis Universal format).
 
-Load material schema by asset index.
+#### Audio
 
 ```typescript
-const schema = loader.loadMaterialSchemaByIndex(6);
-```
-
-**Schema Structure:**
-```typescript
-{
-  stringId: string;      // Schema canonical path
-  schemaName: string;    // Human-readable name
-  fields: Array<{
-    name: string;                    // Field name (e.g., "mainTex", "tint")
-    type: 'Texture' | 'Color' | 'Float' | 'Vec2' | 'Vec3' | 'Vec4' | 'Int';
-    previewFlag: 'None' | 'MainTex' | 'Tint';
-    defaultValue: [number, number, number, number];
-  }>;
-}
-```
-
-#### `getMeshMaterials(assetPath: string): array | null`
+const listener = new THREE.AudioListener();
+camera.add(listener);
 
-Get material information from a mesh (properties and texture references).
+// Load by string ID
+const bgm = await pack.loadAudio('sounds/music.ogg', listener);
+bgm.setLoop(true);
+bgm.play();
 
-```typescript
-const materials = loader.getMeshMaterials('models/character.mesh');
-
-materials.forEach(mat => {
-  console.log(`Material: ${mat.name}`);
-  console.log(`Schema: ${mat.schemaId}`);
-  
-  mat.properties.forEach(prop => {
-    if (prop.textureId) {
-      console.log(`${prop.fieldName}: ${prop.textureId}`);  // mainTex: textures/skin.ktx2
-    } else {
-      console.log(`${prop.fieldName}:`, prop.value);        // tint: [1, 0.8, 0.6, 1]
-    }
-  });
-});
+// Or create HTML5 audio element for preview
+const audioElement = await pack.createAudioPreview(3);
+document.body.appendChild(audioElement);
 ```
 
 ### Metadata Helpers
 
-#### `getTextureMetadata(assetPath: string): object | null`
+All metadata is parsed in WASM for performance and reliability.
 
-Get texture metadata (dimensions, format, etc.).
+#### Animation Metadata
 
 ```typescript
-const info = loader.getTextureMetadata('textures/wood.ktx2');
+const animData = pack.getAnimationMetadata(index);
 
-console.log(`${info.width}x${info.height}`);  // 1024x1024
-console.log(`Channels: ${info.channels}`);    // 3 (RGB) or 4 (RGBA)
-console.log(`KTX2: ${info.isKtx2}`);          // true
+console.log(animData.stringId);        // "Clip_Walking"
+console.log(animData.targetMeshId);    // "Character_Skinned_Tpose"
+console.log(animData.duration);        // 0.97
+console.log(animData.ticksPerSecond);  // 30
+console.log(animData.channelCount);    // 104
+console.log(animData.boneCount);       // 65
 ```
 
-#### `getAudioMetadata(assetPath: string): object | null`
-
-Get audio metadata (sample rate, duration, etc.).
+#### Audio Metadata
 
 ```typescript
-const info = loader.getAudioMetadata('sounds/bgm.ogg');
+const audioData = pack.getAudioMetadata('sounds/bgm.ogg');
 
-console.log(`Sample Rate: ${info.sampleRate} Hz`);
-console.log(`Channels: ${info.channels}`);
-console.log(`Duration: ${info.durationMs / 1000}s`);
+console.log(audioData.sampleRate);  // 44100
+console.log(audioData.channels);    // 2 (stereo)
+console.log(audioData.durationMs);  // 180000 (3 minutes)
 ```
 
-### Asset Listing
-
-#### `listAssets(): array`
-
-List all assets in the opened pack.
+#### Texture Metadata
 
 ```typescript
-const assets = loader.listAssets();
+const texData = pack.getTextureMetadata(index);
 
-assets.forEach(asset => {
-  console.log(`[${asset.index}] ${asset.name}`);
-  console.log(`  Type: ${asset.type}, Size: ${asset.dataSize} bytes`);
-});
+console.log(texData.width);          // 1024
+console.log(texData.height);         // 1024
+console.log(texData.channels);       // 3 (RGB) or 4 (RGBA)
+console.log(texData.channelFormat);  // 1 (RGB) or 2 (RGBA)
 ```
 
-#### `getAssetCount(): number`
-
-Get total number of assets.
+### Asset Discovery
 
 ```typescript
-const count = loader.getAssetCount();
-```
-
-#### `getAssetInfo(index: number): object`
-
-Get detailed info about a specific asset.
-
-```typescript
-const info = loader.getAssetInfo(0);
-console.log(info.type, info.data_size, info.metadata_size);
-```
-
-### Utility Methods
-
-#### `readAssetData(index: number): Uint8Array | null`
-
-Read raw asset data by index.
-
-```typescript
-const data = loader.readAssetData(5);
-```
-
-#### `readAssetMetadata(index: number): Uint8Array | null`
-
-Read raw asset metadata by index.
+// List all assets in pack
+const assets = pack.listAssets();
 
-```typescript
-const metadata = loader.readAssetMetadata(5);
-```
+assets.forEach(asset => {
+    console.log(`[${asset.index}] ${asset.name} (${getTypeName(asset.type)})`);
+});
 
-#### `dispose(): void`
+// Find asset by path
+const index = pack.reader.findAssetByPath('models/character.mesh');
 
-Clean up resources and free memory.
+// Get asset count
+const count = pack.getAssetCount();
 
-```typescript
-loader.dispose();
+// Get asset info
+const info = pack.getAssetInfo(5);
 ```
 
 ## Complete Example
@@ -314,321 +265,101 @@ loader.dispose();
 import * as THREE from 'three';
 import { StowKitLoader } from '@stowkit/three-loader';
 
-// Setup Three.js scene
+// Setup Three.js
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
 const renderer = new THREE.WebGLRenderer();
-renderer.setSize(window.innerWidth, window.innerHeight);
-document.body.appendChild(renderer.domElement);
+const clock = new THREE.Clock();
 
-// Setup audio
 const listener = new THREE.AudioListener();
 camera.add(listener);
 
-// Initialize loader
-const loader = new StowKitLoader();
-
-// Load assets
-async function loadAssets() {
-  await loader.openPack('game-assets.stow');
-  
-  // Load main character
-  const character = await loader.loadMesh('', 'models/player.mesh');
-  character.position.set(0, 0, 0);
-  scene.add(character);
-  
-  // Load environment
-  const environment = await loader.loadMesh('', 'models/level1.mesh');
-  scene.add(environment);
-  
-  // Load background music
-  const bgm = await loader.loadAudio('', 'audio/theme.ogg', listener);
-  bgm.setLoop(true);
-  bgm.setVolume(0.5);
-  bgm.play();
-  
-  // Log what was loaded
-  console.log(`Loaded ${loader.getAssetCount()} assets`);
-  
-  // Start rendering
-  animate();
-}
-
-function animate() {
-  requestAnimationFrame(animate);
-  renderer.render(scene, camera);
-}
-
-loadAssets();
-```
-
-## Material System
-
-The loader automatically handles material assignments:
-
-```typescript
-// When you load a mesh, materials are created with:
-// 1. Colors from 'tint' properties
-// 2. Textures from 'mainTex', 'normalMap', etc.
-// 3. Other properties (roughness, metallic, etc.)
-
-const mesh = await loader.loadMesh('', 'models/character.mesh');
-
-// Materials are automatically applied to geometries based on material indices
-// Textures are automatically loaded by their string IDs and applied to materials
-// No manual texture loading needed!
-```
-
-**Supported material properties:**
-- `mainTex` / `diffuse` / `albedo` → `material.map`
-- `tint` / `color` → `material.color`
-- `normalMap` → `material.normalMap`
-- `metallicMap` → `material.metalnessMap`
-- `roughnessMap` → `material.roughnessMap`
-
-## Advanced Usage
-
-### Loading Multiple Assets from Same Pack
-
-```typescript
-// Load pack once
-const pack = await StowKitLoader.load('assets.stow');
-
-// Load many assets (using whatever string IDs you assigned when packing)
-const station = await pack.loadMesh('restaurant_display_cooking_station');
-const door = await pack.loadMesh('restaurant_display_door');
-const shadow = await pack.loadTexture('_shadow');
-const atlas = await pack.loadTexture('zy_Atlas');
-const music = await pack.loadAudio('track_01', listener);
-
-scene.add(station);
-scene.add(door);
-```
+// Load pack
+const pack = await StowKitLoader.load('game.stow');
 
-### Inspect Before Loading
+// Load static mesh
+const environment = await pack.loadMesh('levels/level1.mesh');
+scene.add(environment);
 
-```typescript
-const pack = await StowKitLoader.load('assets.stow');
+// Load skinned character
+const character = await pack.loadSkinnedMesh('characters/player.skinned');
+character.position.set(0, 0, 0);
+scene.add(character);
 
-// List all assets
-const assets = pack.listAssets();
-const meshes = assets.filter(a => a.type === 1);  // Type 1 = Static Mesh
-const textures = assets.filter(a => a.type === 2); // Type 2 = Texture
-
-console.log(`Pack contains ${assets.length} assets`);
-meshes.forEach(m => console.log(`Mesh: ${m.name}`));
-
-// Get material info before loading
-const materials = pack.getMeshMaterials('models/character');
-materials?.forEach(mat => {
-  console.log(`Material "${mat.name}" schema: ${mat.schemaId}`);
-  mat.properties.forEach(p => {
-    if (p.textureId) console.log(`  Needs texture: ${p.textureId}`);
-  });
-});
-```
+// Load and play animation
+const { mixer } = await pack.loadAnimation(character, 'animations/idle.anim');
 
-### Error Handling
+// Load audio
+const bgm = await pack.loadAudio('sounds/theme.ogg', listener);
+bgm.setLoop(true);
+bgm.play();
 
-```typescript
-try {
-  const pack = await StowKitLoader.load('assets.stow');
-  const mesh = await pack.loadMesh('models/character');
-  scene.add(mesh);
-} catch (error) {
-  console.error('Failed to load:', error.message);
+// Animation loop
+function animate() {
+    requestAnimationFrame(animate);
+    mixer.update(clock.getDelta());
+    renderer.render(scene, camera);
 }
+
+animate();
 ```
 
-### Using Cached Data
+## Asset Types
 
 ```typescript
-// Example with IndexedDB or cache storage
-const cachedData = await caches.match('assets.stow');
-if (cachedData) {
-  const blob = await cachedData.blob();
-  const pack = await StowKitLoader.loadFromMemory(blob);
-} else {
-  const pack = await StowKitLoader.load('assets.stow');
-  // Cache for next time...
-}
-
-// Load assets
-const mesh = await pack.loadMesh('models/character');
+import { AssetType } from '@stowkit/three-loader';
 ```
 
-## Asset Types
-
-| Type | Value | Description |
+| Enum | Value | Description |
 |------|-------|-------------|
-| Static Mesh | 1 | 3D models with geometry, materials, and hierarchy |
-| Texture 2D | 2 | KTX2 compressed textures |
-| Audio | 3 | Audio files (OGG, MP3, etc.) |
-| Material Schema | 4 | Material template definitions |
+| `AssetType.STATIC_MESH` | 1 | Draco-compressed 3D models |
+| `AssetType.TEXTURE_2D` | 2 | KTX2/Basis Universal textures |
+| `AssetType.AUDIO` | 3 | OGG/MP3 audio files |
+| `AssetType.MATERIAL_SCHEMA` | 4 | Material template definitions |
+| `AssetType.SKINNED_MESH` | 5 | Skeletal meshes with bones |
+| `AssetType.ANIMATION_CLIP` | 6 | Bone animation keyframes |
 
-## File Structure
+## Public Folder Setup
 
-`.stow` files contain:
-- **File Header** - Magic number, version, asset count
-- **Asset Data** - Binary geometry, texture, audio data
-- **Asset Directory** - Index of all assets with offsets
-- **Metadata** - Asset-specific information (dimensions, transforms, etc.)
-
-## Requirements
-
-### Public Folder Setup
-
-Place these files in your public folder:
+The package automatically copies required files on install:
 
 ```
 public/
-├── stowkit_reader.wasm    # WASM reader (auto-copied!)
-└── stowkit/               # Auto-copied on install
-    ├── basis/             # Basis Universal transcoder
+└── stowkit/
+    ├── stowkit_reader.wasm    # WASM reader module
+    ├── basis/                  # Basis Universal transcoder
     │   ├── basis_transcoder.js
     │   └── basis_transcoder.wasm
-    └── draco/             # Draco decoder
+    └── draco/                  # Draco decoder
         ├── draco_decoder.js
         ├── draco_decoder.wasm
         └── draco_wasm_wrapper.js
 ```
 
-**Setup:**
+Just run `npm install` and everything is set up automatically!
 
-Everything is automatically copied on install! Just:
+## Performance
 
-```bash
-npm install @stowkit/three-loader
-```
-
-All required files (WASM, Basis, Draco) are copied to your `public/` folder automatically.
-
-**That's it!** No manual file copying needed.
-
-### Three.js Version
-
-Requires Three.js r150 or later.
-
-```bash
-npm install three@^0.150.0
-```
-
-## Examples
-
-### Loading a Character with Equipment
-
-```typescript
-const loader = new StowKitLoader();
-await loader.openPack('characters.stow');
-
-// Load character base
-const character = await loader.loadMesh('', 'characters/knight.mesh');
-
-// Load and attach weapon
-const weapon = await loader.loadMesh('', 'weapons/sword.mesh');
-const rightHand = character.getObjectByName('RightHand');
-if (rightHand) {
-  rightHand.add(weapon);
-}
-
-scene.add(character);
-```
-
-### Dynamic Material Updates
-
-```typescript
-// Load mesh
-const mesh = await loader.loadMesh('', 'models/car.mesh');
-
-// Get material info
-const materials = loader.getMeshMaterials('models/car.mesh');
-
-// Find and modify specific material
-mesh.traverse((child) => {
-  if (child instanceof THREE.Mesh) {
-    const mat = child.material as THREE.MeshStandardMaterial;
-    if (mat.name === 'Paint') {
-      // Change car color
-      mat.color.set(0xff0000); // Red
-    }
-  }
-});
-```
-
-### Texture Swapping
-
-```typescript
-// Load model
-const character = await loader.loadMesh('', 'characters/player.mesh');
-
-// Load alternate texture
-const winterSkin = await loader.loadTexture('', 'textures/winter-skin.ktx2');
-
-// Apply to character
-character.traverse((child) => {
-  if (child instanceof THREE.Mesh) {
-    const mat = child.material as THREE.MeshStandardMaterial;
-    mat.map = winterSkin;
-    mat.needsUpdate = true;
-  }
-});
-```
-
-### Audio with Spatial Sound
-
-```typescript
-const listener = new THREE.AudioListener();
-camera.add(listener);
-
-// Load positional audio
-const sound = await loader.loadAudio('', 'sounds/waterfall.ogg', listener);
-const positionalAudio = new THREE.PositionalAudio(listener);
-positionalAudio.setBuffer(sound.buffer);
-positionalAudio.setRefDistance(20);
-positionalAudio.setLoop(true);
-
-// Attach to a mesh
-waterfall.add(positionalAudio);
-positionalAudio.play();
-```
+- **WASM Parsing**: All binary parsing done in WASM (10-50x faster than JavaScript)
+- **Draco Compression**: Meshes are 80-90% smaller than uncompressed
+- **KTX2 Textures**: GPU-native compression, fast loading and rendering
+- **Lazy Loading**: Assets loaded on-demand, not all at once
+- **Memory Efficient**: Minimal copying between WASM and JavaScript
 
 ## Troubleshooting
 
-### Textures appear upside down
-
-The loader automatically handles UV orientation for KTX2 textures. If textures still appear flipped, check your source files.
+### Animations appear broken/offset from origin
 
-### "Missing initialization with .detectSupport()"
+Make sure your `.stow` file was packed with the latest packer that writes bone parent indices correctly.
 
-The loader automatically calls `detectSupport()` on initialization. If you see this error, ensure you're creating the loader before loading textures.
+### Textures not loading
 
-### "Asset not found"
+Ensure `/stowkit/basis/` folder contains the Basis Universal transcoder files (auto-copied on install).
 
-Make sure:
-- The pack file is opened before loading assets
-- Asset paths match exactly (case-sensitive)
-- The asset exists in the pack (use `listAssets()` to verify)
+### Audio not playing
 
-### Textures not loading on meshes
-
-Check console for texture loading messages. Common issues:
-- Texture string ID in material doesn't match any asset
-- Texture asset is missing from pack
-- Basis transcoder files not in `/basis/` folder
-
-## Performance Tips
-
-1. **Reuse loader instance** - Create one loader, load many assets
-2. **Open pack once** - Use `openPack()` then load multiple assets
-3. **Dispose when done** - Call `loader.dispose()` to free memory
-4. **Use compressed textures** - KTX2 provides GPU-native compression
+Make sure you've created an `AudioListener` and attached it to your camera.
 
 ## License
 
 MIT
-
-## Links
-
-- [npm package](https://www.npmjs.com/package/@stowkit/three-loader)
-- [Three.js documentation](https://threejs.org/docs/)
-- [Basis Universal](https://github.com/BinomialLLC/basis_universal)