@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

$3

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

$3

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

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

#### 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

#### pack.loadAudioByIndex(index, audioContext?)

Loads audio by index.

#### pack.createAudioPreview(index)

Creates an HTML5 audio element for preview.

Returns: Promise

#### 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