npm package: @stowkit/phaser-loader
Description: Phaser loader for StowKit asset packs with KTX2/Basis Universal compressed texture support
Latest version: 0.1.16

# @stowkit/phaser-loader

Phaser.js loader for StowKit asset packs. Supports loading compressed textures (KTX2/Basis Universal) and audio from .stow files.

## Features

- **Compressed Texture Support**: Automatically decodes KTX2 textures to GPU-compressed formats (BC3/DXT5, BC1/DXT1, ASTC, ETC2, etc.)
- **Audio Loading**: Loads audio assets as Web Audio buffers or HTML5 audio elements
- **Multiple Packs**: Load multiple .stow files simultaneously with isolated state
- **Phaser Integration**: Textures are registered with Phaser's texture manager and work with all Phaser game objects
- **Efficient**: Textures remain compressed on the GPU, reducing memory usage

## Installation

```bash
npm install @stowkit/phaser-loader
```

## Quick Start

```typescript
import Phaser from 'phaser';
import { StowKitPhaserLoader } from '@stowkit/phaser-loader';

class GameScene extends Phaser.Scene {
    constructor() {
        super('GameScene');
    }

    async create() {
        // Load the .stow pack
        const pack = await StowKitPhaserLoader.load('/assets/game.stow', {
            basisPath: '/basis/',
            wasmPath: '/stowkit_reader.wasm'
        });
        
        // Load textures into Phaser
        await pack.loadTexture('characters/player', this);
        await pack.loadTexture('ui/button', this);
        
        // Use textures with Phaser game objects
        const player = this.add.sprite(400, 300, 'characters/player');
        const button = this.add.image(100, 50, 'ui/button');
        
        // Load audio
        const bgmBuffer = await pack.loadAudio('sounds/bgm');
        // Use with Web Audio API or convert to Phaser sound
    }
}

const config = {
    type: Phaser.WEBGL,
    width: 800,
    height: 600,
    scene: GameScene
};

const game = new Phaser.Game(config);
```

## API Reference

### StowKitPhaserLoader

Static loader class for opening .stow pack files.

#### `StowKitPhaserLoader.load(url, options?)`

Loads a .stow pack from a URL.

**Parameters:**
- `url` (string): Path to the .stow file
- `options` (object, optional):
  - `basisPath` (string): Path to Basis Universal transcoder files (default: `/basis/`)
  - `wasmPath` (string): Path to StowKit WASM module (default: `/stowkit/stowkit_reader.wasm`)

**Returns:** `Promise<StowKitPhaserPack>`

### StowKitPhaserPack

Represents an opened .stow pack file.

#### `pack.loadTexture(assetPath, scene)`

Loads a texture by its canonical path and registers it with Phaser's texture manager.

**Parameters:**
- `assetPath` (string): The canonical path of the texture (e.g., `"characters/player"`)
- `scene` (Phaser.Scene): The Phaser scene instance

**Returns:** `Promise<Phaser.Textures.Texture>`

**Important:** Must be called after the Phaser scene is initialized (in or after `create()`).

```typescript
await pack.loadTexture('textures/player', this);
this.add.sprite(100, 100, 'textures/player');
```

#### `pack.getPhaserTexture(index, scene)`

Loads a texture by index (useful for asset browsing/previews).

**Parameters:**
- `index` (number): Asset index
- `scene` (Phaser.Scene): The Phaser scene instance

**Returns:** `Promise<Phaser.Textures.Texture>`

#### `pack.loadAudio(assetPath, audioContext?)`

Loads audio by path as an AudioBuffer.

**Parameters:**
- `assetPath` (string): The canonical path of the audio asset
- `audioContext` (AudioContext, optional): Web Audio context to use

**Returns:** `Promise<AudioBuffer>`

#### `pack.loadAudioByIndex(index, audioContext?)`

Loads audio by index.

#### `pack.createAudioPreview(index)`

Creates an HTML5 audio element for preview.

**Returns:** `Promise<HTMLAudioElement>`

#### `pack.listAssets()`

Returns array of all assets in the pack.

#### `pack.getAssetCount()`

Returns total number of assets.

#### `pack.getAssetInfo(index)`

Get asset info by index.

#### `pack.getTextureMetadata(index)`

Get texture metadata (dimensions, format, tags, etc.).

#### `pack.getAudioMetadata(index)`

Get audio metadata.

#### `pack.dispose()`

Closes the pack and frees resources.

## Loading Multiple Packs

Each pack is fully isolated with its own state. You can load multiple packs simultaneously:

```typescript
class GameScene extends Phaser.Scene {
    async create() {
        // Load multiple packs at once
        const [uiPack, levelPack, characterPack] = await Promise.all([
            StowKitPhaserLoader.load('/assets/ui.stow'),
            StowKitPhaserLoader.load('/assets/level1.stow'),
            StowKitPhaserLoader.load('/assets/characters.stow')
        ]);
        
        // Load textures from different packs
        await uiPack.loadTexture('button', this);
        await levelPack.loadTexture('background', this);
        await characterPack.loadTexture('player', this);
        
        // Use textures as normal
        this.add.image(100, 50, 'button');
        this.add.image(0, 0, 'background');
        this.add.sprite(400, 300, 'player');
        
        // Each pack maintains its own asset catalog
        console.log(`UI Pack: ${uiPack.getAssetCount()} assets`);
        console.log(`Level Pack: ${levelPack.getAssetCount()} assets`);
        console.log(`Character Pack: ${characterPack.getAssetCount()} assets`);
    }
}
```

**Note:** Each pack creates its own WASM instance for isolated state. Dispose packs when no longer needed:

```typescript
uiPack.dispose();
```

## Compressed Texture Formats

The loader automatically transcodes KTX2 textures to the best format supported by the device:

**Desktop (DXT/BC formats):**
- BC7 (BPTC) - Highest quality for UASTC textures with alpha (requires WebGL2 + `EXT_texture_compression_bptc`)
- BC3 (DXT5) - High quality for textures with alpha
- BC1 (DXT1) - For textures without alpha or ETC1S encoded textures

**Mobile:**
- ASTC 4x4 - Highest quality (iOS, Android with GPU support)
- ETC2 - Good quality (WebGL2 required)
- ETC1 - Legacy Android support
- PVRTC - iOS fallback

**Fallback:**
- RGBA32 - Uncompressed fallback if no compressed formats are supported

## Limitations

- **No 3D Model Support**: This loader only handles 2D textures and audio. For 3D models, use `@stowkit/three-loader`
- **Phaser 3.60+**: Compressed texture support requires Phaser 3.60 or later
- **Scene Required**: Textures must be loaded within or after a Phaser scene is initialized

## License

MIT