@stowkit/three-loader 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @stowkit/three-loader
 
-Three.js loader for StowKit asset packs. Provides an easy-to-use API for loading meshes, textures, and audio from `.stow` files into Three.js scenes.
+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
 
@@ -8,156 +8,624 @@ Three.js loader for StowKit asset packs. Provides an easy-to-use API for loading
 npm install @stowkit/three-loader three
 ```
 
-## Usage
-
-### Basic Mesh Loading
+## Quick Start
 
 ```typescript
 import * as THREE from 'three';
 import { StowKitLoader } from '@stowkit/three-loader';
 
+// Create loader (auto-configured with defaults)
 const loader = new StowKitLoader();
-loader.setTranscoderPath('/basis/'); // Path to Basis Universal transcoder
 
-// Load a mesh
-const scene = await loader.loadMesh('assets.stow', 'models/character.mesh');
+// Optional: Set custom decoder paths
+// 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);
 ```
 
-### Loading Multiple Assets from Same Pack
+## Features
+
+- ✅ **Zero configuration** - Works out of the box with sensible defaults
+- ✅ **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
+- ✅ **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();
-loader.setTranscoderPath('/basis/');
 
-// Open pack once
+// 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>`
 
-// Load multiple assets (no need to pass URL again)
-const character = await loader.loadMesh('', 'models/character.mesh');
-const weapon = await loader.loadMesh('', 'models/weapon.mesh');
-const texture = await loader.loadTexture('', 'textures/diffuse.ktx2');
+Open a pack from a File or ArrayBuffer.
 
-threeScene.add(character);
-threeScene.add(weapon);
+```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 Textures
+### 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
-const loader = new StowKitLoader();
-loader.setTranscoderPath('/basis/');
+// 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>`
 
-const texture = await loader.loadTexture('assets.stow', 'textures/wood.ktx2');
+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 loader = new StowKitLoader();
-const audio = await loader.loadAudio('assets.stow', 'sounds/bgm.ogg', listener);
+const audio = await loader.loadAudio('', 'sounds/bgm.ogg', listener);
+audio.setLoop(true);
 audio.play();
 ```
 
-### With Callbacks (Three.js style)
+#### `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
-loader.loadMesh(
-    'assets.stow',
-    'models/tree.mesh',
-    (scene) => {
-        // onLoad
-        threeScene.add(scene);
-    },
-    (progress) => {
-        // onProgress
-        console.log('Loading...', progress);
-    },
-    (error) => {
-        // onError
-        console.error('Failed to load:', error);
+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]
     }
-);
+  });
+});
 ```
 
-### Getting Metadata
+### Metadata Helpers
+
+#### `getTextureMetadata(assetPath: string): object | null`
+
+Get texture metadata (dimensions, format, etc.).
 
 ```typescript
-// Get texture info
-const texInfo = loader.getTextureMetadata('textures/wood.ktx2');
-console.log(`Texture: ${texInfo.width}x${texInfo.height}`);
+const info = loader.getTextureMetadata('textures/wood.ktx2');
 
-// Get audio info
-const audioInfo = loader.getAudioMetadata('sounds/bgm.ogg');
-console.log(`Duration: ${audioInfo.durationMs}ms`);
+console.log(`${info.width}x${info.height}`);  // 1024x1024
+console.log(`Channels: ${info.channels}`);    // 3 (RGB) or 4 (RGBA)
+console.log(`KTX2: ${info.isKtx2}`);          // true
 ```
 
-### Listing Assets
+#### `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
-await loader.openPack('assets.stow');
 const assets = loader.listAssets();
 
 assets.forEach(asset => {
-    console.log(`${asset.name} (${asset.type}): ${asset.dataSize} bytes`);
+  console.log(`[${asset.index}] ${asset.name}`);
+  console.log(`  Type: ${asset.type}, Size: ${asset.dataSize} bytes`);
 });
 ```
 
-## Features
+#### `getAssetCount(): number`
 
-- ✅ **Automatic texture loading** - Materials with `mainTex` properties automatically load and apply textures
-- ✅ **Material schema support** - Reads tint colors, texture references, and other material properties
-- ✅ **KTX2/Basis Universal** - Compressed texture support with GPU transcoding
-- ✅ **Scene hierarchy** - Preserves node transforms and parent-child relationships
-- ✅ **Multi-material meshes** - Supports meshes with multiple materials/submeshes
-- ✅ **Type-safe** - Full TypeScript definitions
+Get total number of assets.
 
-## API Reference
+```typescript
+const count = loader.getAssetCount();
+```
+
+#### `getAssetInfo(index: number): object`
 
-### StowKitLoader
+Get detailed info about a specific asset.
 
-#### Constructor
 ```typescript
-new StowKitLoader(manager?: THREE.LoadingManager, parameters?: StowKitLoaderParameters)
+const info = loader.getAssetInfo(0);
+console.log(info.type, info.data_size, info.metadata_size);
 ```
 
-#### Methods
+### Utility Methods
 
-##### `setTranscoderPath(path: string): this`
-Set the path to the Basis Universal transcoder (required for KTX2 textures).
+#### `readAssetData(index: number): Uint8Array | null`
 
-##### `detectSupport(renderer: THREE.WebGLRenderer): this`
-Detect GPU compressed texture format support.
+Read raw asset data by index.
 
-##### `openPack(url: string): Promise<void>`
-Open a .stow pack file. Call this once when loading multiple assets from the same pack.
+```typescript
+const data = loader.readAssetData(5);
+```
 
-##### `loadMesh(url, assetPath, onLoad?, onProgress?, onError?): Promise<THREE.Group>`
-Load a mesh asset. Returns a Three.js Group containing the mesh hierarchy.
+#### `readAssetMetadata(index: number): Uint8Array | null`
 
-##### `loadTexture(url, assetPath, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>`
-Load a texture asset. Returns a Three.js CompressedTexture.
+Read raw asset metadata by index.
 
-##### `loadAudio(url, assetPath, listener, onLoad?, onProgress?, onError?): Promise<THREE.Audio>`
-Load an audio asset. Returns a Three.js Audio object.
+```typescript
+const metadata = loader.readAssetMetadata(5);
+```
 
-##### `getTextureMetadata(assetPath): object | null`
-Get texture metadata (width, height, format, etc.).
+#### `dispose(): void`
 
-##### `getAudioMetadata(assetPath): object | null`
-Get audio metadata (sample rate, channels, duration).
+Clean up resources and free memory.
 
-##### `listAssets(): array`
-List all assets in the opened pack.
+```typescript
+loader.dispose();
+```
 
-##### `dispose(): void`
-Clean up resources and free memory.
+## 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
+└── draco/                 # Draco decoder (for meshes)
+    ├── draco_decoder.js
+    └── draco_decoder.wasm
+```
+
+**Get the files:**
+- `stowkit_reader.wasm` - Included with `@stowkit/reader` package
+- Basis transcoder - From [three.js examples](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/libs/basis)
+- Draco decoder - From [three.js examples](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/libs/draco)
+
+### 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)