@series-inc/stowkit-phaser-loader 0.1.18

package/README.md

@@ -0,0 +1,267 @@
+# @series-inc/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 @series-inc/stowkit-phaser-loader phaser
+```
+
+## Quick Start
+
+```typescript
+import Phaser from 'phaser';
+import { StowKitPhaserLoader } from '@series-inc/stowkit-phaser-loader';
+
+class GameScene extends Phaser.Scene {
+    constructor() {
+        super('GameScene');
+    }
+
+    async create() {
+        const pack = await StowKitPhaserLoader.load('/assets/game.stow', {
+            basisPath: '/basis/',
+            wasmPath: '/stowkit/stowkit_reader.wasm'
+        });
+
+        await pack.loadTexture('characters/player', this);
+        await pack.loadTexture('ui/button', this);
+
+        const player = this.add.sprite(400, 300, 'characters/player');
+        const button = this.add.image(100, 50, 'ui/button');
+
+        const bgmBuffer = await pack.loadAudio('sounds/bgm');
+    }
+}
+
+const config = {
+    type: Phaser.WEBGL,
+    width: 800,
+    height: 600,
+    scene: GameScene
+};
+
+const game = new Phaser.Game(config);
+```
+
+## API Reference
+
+### Exports
+
+```typescript
+export { StowKitPhaserLoader } from '@series-inc/stowkit-phaser-loader';
+export { StowKitPhaserPack } from '@series-inc/stowkit-phaser-loader';
+export { BasisTranscoder } from '@series-inc/stowkit-phaser-loader';
+export { AssetType, PerfLogger } from '@series-inc/stowkit-phaser-loader';
+
+export type { StowKitPhaserLoaderOptions } from '@series-inc/stowkit-phaser-loader';
+export type { TextureData } from '@series-inc/stowkit-phaser-loader';
+```
+
+### StowKitPhaserLoader
+
+Static loader class for opening `.stow` pack files.
+
+#### `StowKitPhaserLoader.load(url, options?)`
+
+Loads a `.stow` pack from a URL.
+
+```typescript
+const pack = await StowKitPhaserLoader.load('/assets/game.stow', {
+    basisPath: '/basis/',
+    wasmPath: '/stowkit/stowkit_reader.wasm'
+});
+```
+
+**Options:**
+- `basisPath` (string) - Path to Basis Universal transcoder files (default: `'/basis/'`)
+- `wasmPath` (string) - Path to StowKit WASM module (default: `'/stowkit/stowkit_reader.wasm'`)
+- `gl` (WebGLRenderingContext | WebGL2RenderingContext) - WebGL context to use. If not provided, a temporary canvas is created.
+
+**Returns:** `Promise<StowKitPhaserPack>`
+
+#### `StowKitPhaserLoader.loadFromMemory(data, options?)`
+
+Loads a `.stow` pack from memory.
+
+```typescript
+const response = await fetch('/assets/game.stow');
+const buffer = await response.arrayBuffer();
+const pack = await StowKitPhaserLoader.loadFromMemory(buffer);
+```
+
+**Parameters:**
+- `data` (ArrayBuffer | Blob | File) - The `.stow` file data
+- `options` (StowKitPhaserLoaderOptions, optional) - Loader options
+
+**Returns:** `Promise<StowKitPhaserPack>`
+
+#### `StowKitPhaserLoader.dispose()`
+
+Dispose of shared resources (Basis transcoder and temporary WebGL context if one was created).
+
+```typescript
+StowKitPhaserLoader.dispose();
+```
+
+### 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>`
+
+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 as an AudioBuffer.
+
+**Parameters:**
+- `index` (number) - Asset index
+- `audioContext` (AudioContext, optional) - Web Audio context to use
+
+**Returns:** `Promise<AudioBuffer>`
+
+#### `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(): number`
+
+Returns total number of assets.
+
+#### `pack.getAssetInfo(index)`
+
+Get asset info by index.
+
+#### `pack.getTextureMetadata(index)`
+
+Get texture metadata (dimensions, format, tags, etc.) using WASM parsing.
+
+```typescript
+const texData = pack.getTextureMetadata(index);
+console.log(`${texData.width}x${texData.height}, ${texData.channels} channels`);
+```
+
+#### `pack.getAudioMetadata(index)`
+
+Get audio metadata using WASM parsing.
+
+```typescript
+const audioData = pack.getAudioMetadata(index);
+console.log(`${audioData.sampleRate}Hz, ${audioData.durationMs}ms`);
+```
+
+#### `pack.dispose()`
+
+Closes the pack and frees resources.
+
+```typescript
+pack.dispose();
+```
+
+## Loading Multiple Packs
+
+Each pack is fully isolated with its own WASM reader instance. You can load multiple packs simultaneously:
+
+```typescript
+class GameScene extends Phaser.Scene {
+    async create() {
+        const [uiPack, levelPack, characterPack] = await Promise.all([
+            StowKitPhaserLoader.load('/assets/ui.stow'),
+            StowKitPhaserLoader.load('/assets/level1.stow'),
+            StowKitPhaserLoader.load('/assets/characters.stow')
+        ]);
+
+        await uiPack.loadTexture('button', this);
+        await levelPack.loadTexture('background', this);
+        await characterPack.loadTexture('player', this);
+
+        this.add.image(100, 50, 'button');
+        this.add.image(0, 0, 'background');
+        this.add.sprite(400, 300, 'player');
+
+        console.log(`UI Pack: ${uiPack.getAssetCount()} assets`);
+        console.log(`Level Pack: ${levelPack.getAssetCount()} assets`);
+        console.log(`Character Pack: ${characterPack.getAssetCount()} assets`);
+    }
+}
+```
+
+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 `@series-inc/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.

package/dist/BasisTranscoder.d.ts

@@ -0,0 +1,40 @@
+/**
+ * BasisTranscoder - Manually decode KTX2 textures to WebGL textures
+ * Used for Phaser which doesn't have built-in KTX2 support
+ */
+export interface TranscodedTexture {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    format: number;
+    internalFormat?: number;
+    compressed: boolean;
+}
+export declare class BasisTranscoder {
+    private module;
+    private initialized;
+    private initPromise;
+    private basisPath;
+    constructor(basisPath?: string);
+    /**
+     * Initialize the Basis Universal transcoder
+     */
+    init(): Promise<void>;
+    /**
+     * Load the basis transcoder module
+     */
+    private loadBasisModule;
+    /**
+     * Transcode KTX2 data to a WebGL-compatible format
+     */
+    transcodeKTX2(data: Uint8Array, gl: WebGLRenderingContext | WebGL2RenderingContext): Promise<TranscodedTexture>;
+    /**
+     * Detect the best compression format supported by the device
+     */
+    private detectBestFormat;
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=BasisTranscoder.d.ts.map

package/dist/BasisTranscoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasisTranscoder.d.ts","sourceRoot":"","sources":["../src/BasisTranscoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgFH,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,eAAe;IACxB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,GAAE,MAAkB;IAIzC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B;;OAEG;YACW,eAAe;IAyB7B;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,qBAAqB,GAAG,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoFrH;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsGxB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKlB"}

package/dist/StowKitPhaserLoader.d.ts

@@ -0,0 +1,53 @@
+import { StowKitPhaserPack } from './StowKitPhaserPack';
+export interface StowKitPhaserLoaderOptions {
+    /**
+     * Path to basis transcoder for KTX2 texture loading
+     * @default '/basis/'
+     */
+    basisPath?: string;
+    /**
+     * Path to WASM reader module
+     * @default '/stowkit/stowkit_reader.wasm'
+     */
+    wasmPath?: string;
+    /**
+     * WebGL context to use for texture loading
+     * If not provided, a temporary canvas will be created
+     */
+    gl?: WebGLRenderingContext | WebGL2RenderingContext;
+}
+/**
+ * Phaser loader for StowKit asset packs
+ * Supports images and audio only (no 3D models)
+ *
+ * Usage:
+ * ```typescript
+ * const pack = await StowKitPhaserLoader.load('assets.stow');
+ * const texture = await pack.loadTexture('textures/player');
+ * const audio = await pack.loadAudio('sounds/bgm');
+ * ```
+ */
+export declare class StowKitPhaserLoader {
+    private static transcoder;
+    private static initialized;
+    private static gl;
+    private static ownGl;
+    private static wasmPath;
+    /**
+     * Load a .stow pack file from a URL
+     */
+    static load(url: string, options?: StowKitPhaserLoaderOptions): Promise<StowKitPhaserPack>;
+    /**
+     * Load a .stow pack from memory (ArrayBuffer, Blob, or File)
+     */
+    static loadFromMemory(data: ArrayBuffer | Blob | File, options?: StowKitPhaserLoaderOptions): Promise<StowKitPhaserPack>;
+    /**
+     * Initialize the loader (called automatically on first load)
+     */
+    private static initialize;
+    /**
+     * Dispose of shared resources
+     */
+    static dispose(): void;
+}
+//# sourceMappingURL=StowKitPhaserLoader.d.ts.map

package/dist/StowKitPhaserLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StowKitPhaserLoader.d.ts","sourceRoot":"","sources":["../src/StowKitPhaserLoader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,0BAA0B;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,EAAE,CAAC,EAAE,qBAAqB,GAAG,sBAAsB,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAgC;IACzD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAS;IACnC,OAAO,CAAC,MAAM,CAAC,EAAE,CAA+D;IAChF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA0C;IAEjE;;OAEG;WACU,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuBhG;;OAEG;WACU,cAAc,CACvB,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,EAC/B,OAAO,CAAC,EAAE,0BAA0B,GACrC,OAAO,CAAC,iBAAiB,CAAC;IA2B7B;;OAEG;mBACkB,UAAU;IA8B/B;;OAEG;IACH,MAAM,CAAC,OAAO,IAAI,IAAI;CAiBzB"}

package/dist/StowKitPhaserPack.d.ts

@@ -0,0 +1,75 @@
+import { StowKitReader } from '@series-inc/stowkit-reader';
+import { BasisTranscoder } from './BasisTranscoder';
+export interface TextureData {
+    texture: WebGLTexture;
+    width: number;
+    height: number;
+}
+/**
+ * Represents an opened StowKit pack for Phaser
+ * Supports loading images and audio only (no 3D models)
+ */
+export declare class StowKitPhaserPack {
+    reader: StowKitReader;
+    private transcoder;
+    private tempGl;
+    private textureCache;
+    private transcodedDataCache;
+    constructor(reader: StowKitReader, transcoder: BasisTranscoder, gl: WebGLRenderingContext | WebGL2RenderingContext);
+    /**
+     * Load a texture by its canonical path/name
+     * Returns a Phaser texture
+     */
+    loadTexture(assetPath: string, scene: any): Promise<any>;
+    /**
+     * Get a Phaser texture by index (for previews/demos)
+     * Creates compressed texture directly in Phaser's GL context
+     */
+    getPhaserTexture(index: number, scene: any): Promise<any>;
+    /**
+     * Load texture by index into a specific GL context
+     */
+    private loadTextureInContext;
+    /**
+     * Load uncompressed image (PNG, JPEG) as WebGL texture in a specific context
+     */
+    private loadUncompressedTextureInContext;
+    /**
+     * Load audio by its canonical path/name
+     * Returns an AudioBuffer
+     */
+    loadAudio(assetPath: string, audioContext?: AudioContext): Promise<AudioBuffer>;
+    /**
+     * Load audio by index
+     */
+    loadAudioByIndex(index: number, audioContext?: AudioContext): Promise<AudioBuffer>;
+    /**
+     * Create an HTML audio element for preview
+     */
+    createAudioPreview(index: number): Promise<HTMLAudioElement>;
+    /**
+     * Get list of all assets in pack
+     */
+    listAssets(): import("@series-inc/stowkit-reader").AssetListItem[];
+    /**
+     * Get asset count
+     */
+    getAssetCount(): number;
+    /**
+     * Get asset info by index
+     */
+    getAssetInfo(index: number): import("@series-inc/stowkit-reader").AssetInfo | null;
+    /**
+     * Get texture metadata
+     */
+    getTextureMetadata(index: number): any;
+    /**
+     * Get audio metadata
+     */
+    getAudioMetadata(index: number): any;
+    /**
+     * Close the pack and free resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=StowKitPhaserPack.d.ts.map

package/dist/StowKitPhaserPack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StowKitPhaserPack.d.ts","sourceRoot":"","sources":["../src/StowKitPhaserPack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyB,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IACnB,MAAM,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,MAAM,CAAiD;IAC/D,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,mBAAmB,CAA6I;gBAGpK,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,eAAe,EAC3B,EAAE,EAAE,qBAAqB,GAAG,sBAAsB;IAOtD;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAyD9D;;;OAGG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IA4C/D;;OAEG;YACW,oBAAoB;IAiElC;;OAEG;YACW,gCAAgC;IAiD9C;;;OAGG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBrF;;OAEG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBxF;;OAEG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBlE;;OAEG;IACH,UAAU;IAIV;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM;IAI1B;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM;IAIhC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM;IAI9B;;OAEG;IACH,OAAO,IAAI,IAAI;CAQlB"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @series-inc/stowkit-phaser-loader
+ * Phaser loader for StowKit asset packs (images and audio only)
+ */
+export { StowKitPhaserLoader } from './StowKitPhaserLoader';
+export { StowKitPhaserPack } from './StowKitPhaserPack';
+export { BasisTranscoder } from './BasisTranscoder';
+export { PerfLogger } from '@series-inc/stowkit-reader';
+export type { StowKitPhaserLoaderOptions } from './StowKitPhaserLoader';
+export type { TextureData } from './StowKitPhaserPack';
+export { AssetType } from '@series-inc/stowkit-reader';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC"}