@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

npm install @stowkit/phaser-loader

Quick Start

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()).

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:

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:

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