Phaser loader for StowKit asset packs with KTX2/Basis Universal compressed texture support
npm install @stowkit/phaser-loaderbash
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`