@stowkit/three-loader 0.1.5 → 0.1.7

package/README.md

@@ -1,639 +1,640 @@
-# @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.
-
-## Installation
-
-```bash
-npm install @stowkit/three-loader three
-```
-
-## Quick Start
-
-```typescript
-import * as THREE from 'three';
-import { StowKitLoader } from '@stowkit/three-loader';
-
-// Create loader (auto-configured with defaults)
-// Draco decoder is auto-configured to /stowkit/draco/
-const loader = new StowKitLoader();
-
-// Optional: Override default paths if needed
-// loader.setDracoDecoderPath('/custom-draco-path/');
-// loader.setTranscoderPath('/custom-basis-path/');
-
-// Open a .stow pack file
-await loader.openPack('assets.stow');
-
-// Load a mesh with automatic textures and materials
-const scene = await loader.loadMesh('', 'models/character.mesh');
-threeScene.add(scene);
-```
-
-## 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
-
-## API Reference
-
-### Constructor
-
-```typescript
-new StowKitLoader(manager?: THREE.LoadingManager, parameters?: StowKitLoaderParameters)
-```
-
-**Parameters (all optional):**
-```typescript
-interface StowKitLoaderParameters {
-  transcoderPath?: string;  // Path to Basis Universal transcoder (default: '/basis/')
-  wasmPath?: string;        // Path to WASM reader module (default: '/stowkit_reader.wasm')
-  reader?: StowKitReader;   // Custom reader instance (advanced)
-}
-```
-
-**Example:**
-```typescript
-// Default configuration
-const loader = new StowKitLoader();
-
-// Custom paths
-const loader = new StowKitLoader(undefined, {
-  transcoderPath: '/my-basis-path/',
-  wasmPath: '/custom/stowkit_reader.wasm'
-});
-```
-
-### Opening Packs
-
-#### `openPack(url: string): Promise<void>`
-
-Open a .stow pack file from a URL. Call this once, then load multiple assets.
-
-```typescript
-await loader.openPack('assets.stow');
-```
-
-#### `open(fileOrBuffer: ArrayBuffer | File): Promise<boolean>`
-
-Open a pack from a File or ArrayBuffer.
-
-```typescript
-// From file input
-const file = input.files[0];
-await loader.open(file);
-
-// From fetch
-const response = await fetch('assets.stow');
-const buffer = await response.arrayBuffer();
-await loader.open(buffer);
-```
-
-### Loading Meshes
-
-#### `loadMesh(url: string, assetPath: string, onLoad?, onProgress?, onError?): Promise<THREE.Group>`
-
-Load a mesh asset with automatic texture and material loading.
-
-**Parameters:**
-- `url` - URL to .stow file (empty string if already opened)
-- `assetPath` - Canonical path to mesh within pack
-- `onLoad` - Optional callback when loading completes
-- `onProgress` - Optional progress callback  
-- `onError` - Optional error callback
-
-**Returns:** `THREE.Group` containing the mesh hierarchy
-
-**Example:**
-```typescript
-// Simple async/await
-const mesh = await loader.loadMesh('', 'models/character.mesh');
-scene.add(mesh);
-
-// With callbacks (Three.js style)
-loader.loadMesh('assets.stow', 'models/tree.mesh', 
-  (scene) => {
-    threeScene.add(scene);
-  },
-  (progress) => console.log('Loading...', progress),
-  (error) => console.error('Failed:', error)
-);
-```
-
-**What you get:**
-- Complete scene hierarchy with nodes
-- All geometries (vertices, normals, UVs, indices)
-- Materials with properties applied (colors, etc.)
-- Textures automatically loaded and applied to materials
-- Transforms (position, rotation, scale) preserved
-
-### Loading Textures
-
-#### `loadTexture(url: string, assetPath: string, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>`
-
-Load a texture asset (KTX2 format).
-
-```typescript
-const texture = await loader.loadTexture('', 'textures/wood.ktx2');
-material.map = texture;
-material.needsUpdate = true;
-```
-
-#### `loadTextureByIndex(index: number, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>`
-
-Load a texture by its asset index (when you don't have the path).
-
-```typescript
-const texture = await loader.loadTextureByIndex(5);
-```
-
-### Loading Audio
-
-#### `loadAudio(url: string, assetPath: string, listener: THREE.AudioListener, onLoad?, onProgress?, onError?): Promise<THREE.Audio>`
-
-Load an audio asset as a Three.js Audio object.
-
-```typescript
-const listener = new THREE.AudioListener();
-camera.add(listener);
-
-const audio = await loader.loadAudio('', 'sounds/bgm.ogg', listener);
-audio.setLoop(true);
-audio.play();
-```
-
-#### `createAudioPreview(index: number): Promise<HTMLAudioElement>`
-
-Create an HTML5 audio element for previewing audio (simpler than Three.js Audio).
-
-```typescript
-const audioElement = await loader.createAudioPreview(index);
-audioElement.autoplay = true;
-container.appendChild(audioElement);
-```
-
-### Material Information
-
-#### `loadMaterialSchema(assetPath: string): object | null`
-
-Load material schema definition.
-
-```typescript
-const schema = loader.loadMaterialSchema('shaders/DefaultShader.stowschema');
-
-console.log(schema.schemaName);  // "Default Shader"
-console.log(schema.fields);      // Array of field definitions
-
-schema.fields.forEach(field => {
-  console.log(`${field.name}: ${field.type}`);
-  // mainTex: Texture
-  // tint: Color
-  // roughness: Float
-});
-```
-
-#### `loadMaterialSchemaByIndex(index: number): object | null`
-
-Load material schema by asset index.
-
-```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`
-
-Get material information from a mesh (properties and texture references).
-
-```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]
-    }
-  });
-});
-```
-
-### Metadata Helpers
-
-#### `getTextureMetadata(assetPath: string): object | null`
-
-Get texture metadata (dimensions, format, etc.).
-
-```typescript
-const info = loader.getTextureMetadata('textures/wood.ktx2');
-
-console.log(`${info.width}x${info.height}`);  // 1024x1024
-console.log(`Channels: ${info.channels}`);    // 3 (RGB) or 4 (RGBA)
-console.log(`KTX2: ${info.isKtx2}`);          // true
-```
-
-#### `getAudioMetadata(assetPath: string): object | null`
-
-Get audio metadata (sample rate, duration, etc.).
-
-```typescript
-const info = loader.getAudioMetadata('sounds/bgm.ogg');
-
-console.log(`Sample Rate: ${info.sampleRate} Hz`);
-console.log(`Channels: ${info.channels}`);
-console.log(`Duration: ${info.durationMs / 1000}s`);
-```
-
-### Asset Listing
-
-#### `listAssets(): array`
-
-List all assets in the opened pack.
-
-```typescript
-const assets = loader.listAssets();
-
-assets.forEach(asset => {
-  console.log(`[${asset.index}] ${asset.name}`);
-  console.log(`  Type: ${asset.type}, Size: ${asset.dataSize} bytes`);
-});
-```
-
-#### `getAssetCount(): number`
-
-Get total number of assets.
-
-```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.
-
-```typescript
-const metadata = loader.readAssetMetadata(5);
-```
-
-#### `dispose(): void`
-
-Clean up resources and free memory.
-
-```typescript
-loader.dispose();
-```
-
-## Complete Example
-
-```typescript
-import * as THREE from 'three';
-import { StowKitLoader } from '@stowkit/three-loader';
-
-// Setup Three.js scene
-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);
-
-// 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
-
-### Multiple Assets from Same Pack
-
-```typescript
-// Open once
-await loader.openPack('assets.stow');
-
-// Load many (no URL needed)
-const mesh1 = await loader.loadMesh('', 'models/char1.mesh');
-const mesh2 = await loader.loadMesh('', 'models/char2.mesh');
-const tex1 = await loader.loadTexture('', 'textures/t1.ktx2');
-const tex2 = await loader.loadTexture('', 'textures/t2.ktx2');
-```
-
-### Inspect Before Loading
-
-```typescript
-await loader.openPack('assets.stow');
-
-// List all assets
-const assets = loader.listAssets();
-const meshes = assets.filter(a => a.type === 1);  // Type 1 = Static Mesh
-const textures = assets.filter(a => a.type === 2); // Type 2 = Texture
-
-// Get material info before loading
-const materials = loader.getMeshMaterials('models/character.mesh');
-materials.forEach(mat => {
-  console.log(`Material "${mat.name}" needs:`, mat.properties.map(p => p.textureId).filter(Boolean));
-});
-
-// Preload textures
-for (const mat of materials) {
-  for (const prop of mat.properties) {
-    if (prop.textureId) {
-      await loader.loadTexture('', prop.textureId);
-    }
-  }
-}
-
-// Now load the mesh (textures already cached)
-const mesh = await loader.loadMesh('', 'models/character.mesh');
-```
-
-### Error Handling
-
-```typescript
-try {
-  const mesh = await loader.loadMesh('assets.stow', 'models/character.mesh');
-  scene.add(mesh);
-} catch (error) {
-  console.error('Failed to load mesh:', error.message);
-}
-
-// Or with callbacks
-loader.loadMesh('assets.stow', 'models/tree.mesh',
-  (scene) => threeScene.add(scene),
-  undefined,
-  (error) => console.error('Error:', error)
-);
-```
-
-## Asset Types
-
-| Type | 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 |
-
-## File Structure
-
-`.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:
-
-```
-public/
-├── stowkit_reader.wasm    # WASM reader module  
-├── basis/                 # Basis Universal transcoder (for textures)
-│   ├── basis_transcoder.js
-│   └── basis_transcoder.wasm
-└── stowkit/               # Auto-copied by @stowkit/three-loader
-    └── draco/             # Draco decoder (for meshes) - included!
-        ├── draco_decoder.js
-        ├── draco_decoder.wasm
-        └── draco_wasm_wrapper.js
-```
-
-**Setup:**
-
-The package automatically copies Draco decoder files to `public/stowkit/draco/` when you install `@stowkit/three-loader`.
-
-You only need to manually add:
-- `stowkit_reader.wasm` - Copy from `node_modules/@stowkit/reader/dist/`
-- Basis transcoder - Download from [three.js examples](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/libs/basis)
-
-### 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();
-```
-
-## Troubleshooting
-
-### Textures appear upside down
-
-The loader automatically handles UV orientation for KTX2 textures. If textures still appear flipped, check your source files.
-
-### "Missing initialization with .detectSupport()"
-
-The loader automatically calls `detectSupport()` on initialization. If you see this error, ensure you're creating the loader before loading textures.
-
-### "Asset not found"
-
-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)
-
-### 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
-
-## License
-
-MIT
-
-## Links
-
-- [npm package](https://www.npmjs.com/package/@stowkit/three-loader)
-- [Three.js documentation](https://threejs.org/docs/)
+# @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.
+
+## Installation
+
+```bash
+npm install @stowkit/three-loader three
+```
+
+## Quick Start
+
+```typescript
+import * as THREE from 'three';
+import { StowKitLoader } from '@stowkit/three-loader';
+
+// Create loader (auto-configured with defaults)
+// Basis transcoder: /stowkit/basis/ (auto-included)
+// Draco decoder: /stowkit/draco/ (auto-included)
+const loader = new StowKitLoader();
+
+// Optional: Override paths only if you have custom locations
+// loader.setTranscoderPath('/custom-basis-path/');
+// loader.setDracoDecoderPath('/custom-draco-path/');
+
+// Open a .stow pack file
+await loader.openPack('assets.stow');
+
+// Load a mesh with automatic textures and materials
+const scene = await loader.loadMesh('', 'models/character.mesh');
+threeScene.add(scene);
+```
+
+## 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
+
+## API Reference
+
+### Constructor
+
+```typescript
+new StowKitLoader(manager?: THREE.LoadingManager, parameters?: StowKitLoaderParameters)
+```
+
+**Parameters (all optional):**
+```typescript
+interface StowKitLoaderParameters {
+  transcoderPath?: string;  // Path to Basis Universal transcoder (default: '/basis/')
+  wasmPath?: string;        // Path to WASM reader module (default: '/stowkit_reader.wasm')
+  reader?: StowKitReader;   // Custom reader instance (advanced)
+}
+```
+
+**Example:**
+```typescript
+// Default configuration
+const loader = new StowKitLoader();
+
+// Custom paths
+const loader = new StowKitLoader(undefined, {
+  transcoderPath: '/my-basis-path/',
+  wasmPath: '/custom/stowkit_reader.wasm'
+});
+```
+
+### Opening Packs
+
+#### `openPack(url: string): Promise<void>`
+
+Open a .stow pack file from a URL. Call this once, then load multiple assets.
+
+```typescript
+await loader.openPack('assets.stow');
+```
+
+#### `open(fileOrBuffer: ArrayBuffer | File): Promise<boolean>`
+
+Open a pack from a File or ArrayBuffer.
+
+```typescript
+// From file input
+const file = input.files[0];
+await loader.open(file);
+
+// From fetch
+const response = await fetch('assets.stow');
+const buffer = await response.arrayBuffer();
+await loader.open(buffer);
+```
+
+### Loading Meshes
+
+#### `loadMesh(url: string, assetPath: string, onLoad?, onProgress?, onError?): Promise<THREE.Group>`
+
+Load a mesh asset with automatic texture and material loading.
+
+**Parameters:**
+- `url` - URL to .stow file (empty string if already opened)
+- `assetPath` - Canonical path to mesh within pack
+- `onLoad` - Optional callback when loading completes
+- `onProgress` - Optional progress callback  
+- `onError` - Optional error callback
+
+**Returns:** `THREE.Group` containing the mesh hierarchy
+
+**Example:**
+```typescript
+// Simple async/await
+const mesh = await loader.loadMesh('', 'models/character.mesh');
+scene.add(mesh);
+
+// With callbacks (Three.js style)
+loader.loadMesh('assets.stow', 'models/tree.mesh', 
+  (scene) => {
+    threeScene.add(scene);
+  },
+  (progress) => console.log('Loading...', progress),
+  (error) => console.error('Failed:', error)
+);
+```
+
+**What you get:**
+- Complete scene hierarchy with nodes
+- All geometries (vertices, normals, UVs, indices)
+- Materials with properties applied (colors, etc.)
+- Textures automatically loaded and applied to materials
+- Transforms (position, rotation, scale) preserved
+
+### Loading Textures
+
+#### `loadTexture(url: string, assetPath: string, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>`
+
+Load a texture asset (KTX2 format).
+
+```typescript
+const texture = await loader.loadTexture('', 'textures/wood.ktx2');
+material.map = texture;
+material.needsUpdate = true;
+```
+
+#### `loadTextureByIndex(index: number, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>`
+
+Load a texture by its asset index (when you don't have the path).
+
+```typescript
+const texture = await loader.loadTextureByIndex(5);
+```
+
+### Loading Audio
+
+#### `loadAudio(url: string, assetPath: string, listener: THREE.AudioListener, onLoad?, onProgress?, onError?): Promise<THREE.Audio>`
+
+Load an audio asset as a Three.js Audio object.
+
+```typescript
+const listener = new THREE.AudioListener();
+camera.add(listener);
+
+const audio = await loader.loadAudio('', 'sounds/bgm.ogg', listener);
+audio.setLoop(true);
+audio.play();
+```
+
+#### `createAudioPreview(index: number): Promise<HTMLAudioElement>`
+
+Create an HTML5 audio element for previewing audio (simpler than Three.js Audio).
+
+```typescript
+const audioElement = await loader.createAudioPreview(index);
+audioElement.autoplay = true;
+container.appendChild(audioElement);
+```
+
+### Material Information
+
+#### `loadMaterialSchema(assetPath: string): object | null`
+
+Load material schema definition.
+
+```typescript
+const schema = loader.loadMaterialSchema('shaders/DefaultShader.stowschema');
+
+console.log(schema.schemaName);  // "Default Shader"
+console.log(schema.fields);      // Array of field definitions
+
+schema.fields.forEach(field => {
+  console.log(`${field.name}: ${field.type}`);
+  // mainTex: Texture
+  // tint: Color
+  // roughness: Float
+});
+```
+
+#### `loadMaterialSchemaByIndex(index: number): object | null`
+
+Load material schema by asset index.
+
+```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`
+
+Get material information from a mesh (properties and texture references).
+
+```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]
+    }
+  });
+});
+```
+
+### Metadata Helpers
+
+#### `getTextureMetadata(assetPath: string): object | null`
+
+Get texture metadata (dimensions, format, etc.).
+
+```typescript
+const info = loader.getTextureMetadata('textures/wood.ktx2');
+
+console.log(`${info.width}x${info.height}`);  // 1024x1024
+console.log(`Channels: ${info.channels}`);    // 3 (RGB) or 4 (RGBA)
+console.log(`KTX2: ${info.isKtx2}`);          // true
+```
+
+#### `getAudioMetadata(assetPath: string): object | null`
+
+Get audio metadata (sample rate, duration, etc.).
+
+```typescript
+const info = loader.getAudioMetadata('sounds/bgm.ogg');
+
+console.log(`Sample Rate: ${info.sampleRate} Hz`);
+console.log(`Channels: ${info.channels}`);
+console.log(`Duration: ${info.durationMs / 1000}s`);
+```
+
+### Asset Listing
+
+#### `listAssets(): array`
+
+List all assets in the opened pack.
+
+```typescript
+const assets = loader.listAssets();
+
+assets.forEach(asset => {
+  console.log(`[${asset.index}] ${asset.name}`);
+  console.log(`  Type: ${asset.type}, Size: ${asset.dataSize} bytes`);
+});
+```
+
+#### `getAssetCount(): number`
+
+Get total number of assets.
+
+```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.
+
+```typescript
+const metadata = loader.readAssetMetadata(5);
+```
+
+#### `dispose(): void`
+
+Clean up resources and free memory.
+
+```typescript
+loader.dispose();
+```
+
+## Complete Example
+
+```typescript
+import * as THREE from 'three';
+import { StowKitLoader } from '@stowkit/three-loader';
+
+// Setup Three.js scene
+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);
+
+// 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
+
+### Multiple Assets from Same Pack
+
+```typescript
+// Open once
+await loader.openPack('assets.stow');
+
+// Load many (no URL needed)
+const mesh1 = await loader.loadMesh('', 'models/char1.mesh');
+const mesh2 = await loader.loadMesh('', 'models/char2.mesh');
+const tex1 = await loader.loadTexture('', 'textures/t1.ktx2');
+const tex2 = await loader.loadTexture('', 'textures/t2.ktx2');
+```
+
+### Inspect Before Loading
+
+```typescript
+await loader.openPack('assets.stow');
+
+// List all assets
+const assets = loader.listAssets();
+const meshes = assets.filter(a => a.type === 1);  // Type 1 = Static Mesh
+const textures = assets.filter(a => a.type === 2); // Type 2 = Texture
+
+// Get material info before loading
+const materials = loader.getMeshMaterials('models/character.mesh');
+materials.forEach(mat => {
+  console.log(`Material "${mat.name}" needs:`, mat.properties.map(p => p.textureId).filter(Boolean));
+});
+
+// Preload textures
+for (const mat of materials) {
+  for (const prop of mat.properties) {
+    if (prop.textureId) {
+      await loader.loadTexture('', prop.textureId);
+    }
+  }
+}
+
+// Now load the mesh (textures already cached)
+const mesh = await loader.loadMesh('', 'models/character.mesh');
+```
+
+### Error Handling
+
+```typescript
+try {
+  const mesh = await loader.loadMesh('assets.stow', 'models/character.mesh');
+  scene.add(mesh);
+} catch (error) {
+  console.error('Failed to load mesh:', error.message);
+}
+
+// Or with callbacks
+loader.loadMesh('assets.stow', 'models/tree.mesh',
+  (scene) => threeScene.add(scene),
+  undefined,
+  (error) => console.error('Error:', error)
+);
+```
+
+## Asset Types
+
+| Type | 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 |
+
+## File Structure
+
+`.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:
+
+```
+public/
+├── stowkit_reader.wasm    # WASM reader module (copy from node_modules/@stowkit/reader/dist/)
+└── stowkit/               # Auto-copied by @stowkit/three-loader on install
+    ├── basis/             # Basis Universal transcoder (for textures) - included!
+    │   ├── basis_transcoder.js
+    │   └── basis_transcoder.wasm
+    └── draco/             # Draco decoder (for meshes) - included!
+        ├── draco_decoder.js
+        ├── draco_decoder.wasm
+        └── draco_wasm_wrapper.js
+```
+
+**Setup:**
+
+The package automatically includes and copies all decoder files on install!
+
+You only need to:
+1. Copy `stowkit_reader.wasm` from `node_modules/@stowkit/reader/dist/` to `public/`
+2. That's it! Basis and Draco decoders are included automatically.
+
+### 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();
+```
+
+## Troubleshooting
+
+### Textures appear upside down
+
+The loader automatically handles UV orientation for KTX2 textures. If textures still appear flipped, check your source files.
+
+### "Missing initialization with .detectSupport()"
+
+The loader automatically calls `detectSupport()` on initialization. If you see this error, ensure you're creating the loader before loading textures.
+
+### "Asset not found"
+
+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)
+
+### 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
+
+## 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)