@series-inc/stowkit-phaser-loader 0.1.18

package/dist/stowkit-phaser-loader.js

@@ -0,0 +1,638 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@series-inc/stowkit-reader')) :
+    typeof define === 'function' && define.amd ? define(['exports', '@series-inc/stowkit-reader'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.StowKitPhaserLoader = {}, global.StowKitReader));
+})(this, (function (exports, stowkitReader) { 'use strict';
+
+    /**
+     * BasisTranscoder - Manually decode KTX2 textures to WebGL textures
+     * Used for Phaser which doesn't have built-in KTX2 support
+     */
+    // Basis transcoder formats (from Three.js KTX2Loader.TranscoderFormat)
+    const BASIS_FORMAT = {
+        ETC1: 0,
+        ETC2: 1,
+        BC1: 2, // DXT1
+        BC3: 3, // DXT5
+        BC7_M5: 7, // BC7
+        PVRTC1_4_RGB: 8,
+        PVRTC1_4_RGBA: 9,
+        ASTC_4x4: 10,
+        RGBA32: 13};
+    class BasisTranscoder {
+        constructor(basisPath = '/basis/') {
+            this.module = null;
+            this.initialized = false;
+            this.initPromise = null;
+            this.basisPath = basisPath;
+        }
+        /**
+         * Initialize the Basis Universal transcoder
+         */
+        async init() {
+            if (this.initialized)
+                return;
+            if (this.initPromise)
+                return this.initPromise;
+            this.initPromise = (async () => {
+                try {
+                    // Load the basis transcoder
+                    const scriptPath = `${this.basisPath}basis_transcoder.js`;
+                    // Import the basis module
+                    const BasisModule = await this.loadBasisModule(scriptPath);
+                    // Initialize
+                    BasisModule.initializeBasis();
+                    this.module = BasisModule;
+                    this.initialized = true;
+                }
+                catch (error) {
+                    console.error('[BasisTranscoder] Failed to initialize:', error);
+                    throw error;
+                }
+            })();
+            return this.initPromise;
+        }
+        /**
+         * Load the basis transcoder module
+         */
+        async loadBasisModule(scriptPath) {
+            return new Promise((resolve, reject) => {
+                const script = document.createElement('script');
+                script.src = scriptPath;
+                script.async = true;
+                script.onload = () => {
+                    // The basis transcoder exposes a global BASIS function
+                    if (typeof window.BASIS === 'function') {
+                        window.BASIS().then((module) => {
+                            resolve(module);
+                        }).catch(reject);
+                    }
+                    else {
+                        reject(new Error('BASIS module not found'));
+                    }
+                };
+                script.onerror = () => {
+                    reject(new Error(`Failed to load ${scriptPath}`));
+                };
+                document.head.appendChild(script);
+            });
+        }
+        /**
+         * Transcode KTX2 data to a WebGL-compatible format
+         */
+        async transcodeKTX2(data, gl) {
+            if (!this.initialized) {
+                await this.init();
+            }
+            if (!this.module) {
+                throw new Error('Basis module not initialized');
+            }
+            // Create KTX2File from data
+            const ktx2File = new this.module.KTX2File(data);
+            try {
+                // Validate file
+                if (!ktx2File.isValid()) {
+                    throw new Error('Invalid or unsupported KTX2 file');
+                }
+                // Get image dimensions
+                const width = ktx2File.getWidth();
+                const height = ktx2File.getHeight();
+                // Check if the texture has alpha
+                const hasAlpha = ktx2File.getHasAlpha();
+                // Check format type (UASTC or ETC1S)
+                const isUASTC = ktx2File.isUASTC();
+                const isETC1S = ktx2File.isETC1S();
+                // Start transcoding
+                if (!ktx2File.startTranscoding()) {
+                    throw new Error('Failed to start KTX2 transcoding');
+                }
+                // Use first mip level, first layer, first face
+                const mip = 0;
+                const layer = 0;
+                const face = 0;
+                // Detect best format for this device and file type
+                const targetFormat = this.detectBestFormat(gl, hasAlpha, isETC1S);
+                // Get transcoded size
+                const transcodedSize = ktx2File.getImageTranscodedSizeInBytes(mip, layer, face, targetFormat.basisFormat);
+                // Allocate output buffer
+                const transcodedData = new Uint8Array(transcodedSize);
+                // Transcode (parameters: dst, mip, layer, face, format, unused1, unused2, unused3)
+                const result = ktx2File.transcodeImage(transcodedData, mip, layer, face, targetFormat.basisFormat, 0, -1, -1);
+                if (result === 0) {
+                    throw new Error('KTX2 transcoding failed');
+                }
+                return {
+                    data: transcodedData,
+                    width,
+                    height,
+                    format: targetFormat.glFormat,
+                    internalFormat: targetFormat.glInternalFormat,
+                    compressed: targetFormat.compressed
+                };
+            }
+            finally {
+                ktx2File.close();
+                ktx2File.delete();
+            }
+        }
+        /**
+         * Detect the best compression format supported by the device
+         */
+        detectBestFormat(gl, hasAlpha = true, isETC1S = false) {
+            const isWebGL2 = gl instanceof WebGL2RenderingContext;
+            // Check for extensions
+            const s3tc = gl.getExtension('WEBGL_compressed_texture_s3tc') ||
+                gl.getExtension('WEBKIT_WEBGL_compressed_texture_s3tc');
+            const bptc = gl.getExtension('EXT_texture_compression_bptc');
+            const etc1 = gl.getExtension('WEBGL_compressed_texture_etc1');
+            const etc = gl.getExtension('WEBGL_compressed_texture_etc');
+            const astc = gl.getExtension('WEBGL_compressed_texture_astc');
+            const pvrtc = gl.getExtension('WEBGL_compressed_texture_pvrtc') ||
+                gl.getExtension('WEBKIT_WEBGL_compressed_texture_pvrtc');
+            // For ETC1S: Use BC1 (no alpha support in ETC1S)
+            // For UASTC with alpha: Use BC3/BC7
+            // For UASTC without alpha: Use BC1
+            // BC7 on desktop with WebGL2 (requires separate BPTC extension)
+            // Only use for UASTC with alpha
+            if (isWebGL2 && bptc && hasAlpha && !isETC1S) {
+                return {
+                    basisFormat: BASIS_FORMAT.BC7_M5,
+                    glFormat: gl.RGBA,
+                    glInternalFormat: bptc.COMPRESSED_RGBA_BPTC_UNORM_EXT,
+                    compressed: true
+                };
+            }
+            // BC3 (DXT5) on desktop - only for textures with alpha (UASTC)
+            if (s3tc && hasAlpha && !isETC1S) {
+                return {
+                    basisFormat: BASIS_FORMAT.BC3,
+                    glFormat: gl.RGBA,
+                    glInternalFormat: s3tc.COMPRESSED_RGBA_S3TC_DXT5_EXT,
+                    compressed: true
+                };
+            }
+            // BC1 (DXT1) on desktop - for ETC1S or textures without alpha
+            if (s3tc) {
+                return {
+                    basisFormat: BASIS_FORMAT.BC1,
+                    glFormat: gl.RGB,
+                    glInternalFormat: s3tc.COMPRESSED_RGB_S3TC_DXT1_EXT,
+                    compressed: true
+                };
+            }
+            // ASTC on mobile (best quality)
+            if (astc) {
+                return {
+                    basisFormat: BASIS_FORMAT.ASTC_4x4,
+                    glFormat: gl.RGBA,
+                    glInternalFormat: astc.COMPRESSED_RGBA_ASTC_4x4_KHR,
+                    compressed: true
+                };
+            }
+            // ETC2 on mobile with WebGL2
+            if (isWebGL2 && etc) {
+                return {
+                    basisFormat: BASIS_FORMAT.ETC2,
+                    glFormat: gl.RGBA,
+                    glInternalFormat: etc.COMPRESSED_RGBA8_ETC2_EAC || 0x9278,
+                    compressed: true
+                };
+            }
+            // ETC1 on mobile
+            if (etc1 || etc) {
+                return {
+                    basisFormat: BASIS_FORMAT.ETC1,
+                    glFormat: gl.RGB,
+                    glInternalFormat: etc1?.COMPRESSED_RGB_ETC1_WEBGL || 0x8D64,
+                    compressed: true
+                };
+            }
+            // PVRTC on iOS (last resort for compressed)
+            if (pvrtc) {
+                return {
+                    basisFormat: hasAlpha ? BASIS_FORMAT.PVRTC1_4_RGBA : BASIS_FORMAT.PVRTC1_4_RGB,
+                    glFormat: gl.RGBA,
+                    glInternalFormat: pvrtc.COMPRESSED_RGBA_PVRTC_4BPPV1_IMG,
+                    compressed: true
+                };
+            }
+            // Fallback to uncompressed RGBA
+            return {
+                basisFormat: BASIS_FORMAT.RGBA32,
+                glFormat: gl.RGBA,
+                glInternalFormat: gl.RGBA,
+                compressed: false
+            };
+        }
+        /**
+         * Dispose resources
+         */
+        dispose() {
+            this.module = null;
+            this.initialized = false;
+            this.initPromise = null;
+        }
+    }
+
+    /**
+     * Represents an opened StowKit pack for Phaser
+     * Supports loading images and audio only (no 3D models)
+     */
+    class StowKitPhaserPack {
+        constructor(reader, transcoder, gl) {
+            this.textureCache = new Map();
+            this.transcodedDataCache = new Map();
+            this.reader = reader;
+            this.transcoder = transcoder;
+            this.tempGl = gl;
+        }
+        /**
+         * Load a texture by its canonical path/name
+         * Returns a Phaser texture
+         */
+        async loadTexture(assetPath, scene) {
+            const totalStart = performance.now();
+            // Check cache first
+            if (this.textureCache.has(assetPath)) {
+                stowkitReader.PerfLogger.log(`[Perf] Texture cache hit: ${assetPath}`);
+                return this.textureCache.get(assetPath);
+            }
+            // Find asset by path
+            const assetIndex = this.reader.findAssetByPath(assetPath);
+            if (assetIndex < 0) {
+                throw new Error(`Texture not found: ${assetPath}`);
+            }
+            // Verify it's a texture
+            const info = this.reader.getAssetInfo(assetIndex);
+            if (!info || info.type !== stowkitReader.AssetType.TEXTURE_2D) {
+                throw new Error(`Asset is not a texture: ${assetPath}`);
+            }
+            // Use the same logic as getPhaserTexture but with custom key
+            const key = assetPath;
+            const gl = scene.sys.game.renderer.gl;
+            // Read and transcode
+            const data = this.reader.readAssetData(assetIndex);
+            if (!data) {
+                throw new Error(`Failed to read texture data for ${assetPath}`);
+            }
+            const transcodeStart = performance.now();
+            const transcoded = await this.transcoder.transcodeKTX2(data, gl);
+            stowkitReader.PerfLogger.log(`[Perf] Phaser Basis transcode: ${(performance.now() - transcodeStart).toFixed(2)}ms (${transcoded.width}x${transcoded.height})`);
+            // Format like Phaser's KTX parser
+            const compressedTextureData = {
+                mipmaps: [{
+                        data: transcoded.data,
+                        width: transcoded.width,
+                        height: transcoded.height
+                    }],
+                width: transcoded.width,
+                height: transcoded.height,
+                internalFormat: transcoded.internalFormat,
+                compressed: transcoded.compressed,
+                generateMipmap: false,
+                format: transcoded.internalFormat
+            };
+            const phaserTexture = scene.textures.addCompressedTexture(key, compressedTextureData);
+            this.textureCache.set(assetPath, phaserTexture);
+            stowkitReader.PerfLogger.log(`[Perf] ===== Total Phaser texture load: ${(performance.now() - totalStart).toFixed(2)}ms =====`);
+            return phaserTexture;
+        }
+        /**
+         * Get a Phaser texture by index (for previews/demos)
+         * Creates compressed texture directly in Phaser's GL context
+         */
+        async getPhaserTexture(index, scene) {
+            const key = `texture_${index}`;
+            // Check if already exists in Phaser's texture manager
+            if (scene.textures.exists(key)) {
+                return scene.textures.get(key);
+            }
+            // Get Phaser's GL context
+            const gl = scene.sys.game.renderer.gl;
+            // Read and transcode the KTX2 data
+            const data = this.reader.readAssetData(index);
+            if (!data) {
+                throw new Error(`Failed to read texture data for index ${index}`);
+            }
+            // Transcode to compressed format (don't create the WebGL texture yet - let Phaser do it)
+            const transcoded = await this.transcoder.transcodeKTX2(data, gl);
+            // Format the data exactly like Phaser's KTX parser output
+            const compressedTextureData = {
+                mipmaps: [{
+                        data: transcoded.data,
+                        width: transcoded.width,
+                        height: transcoded.height
+                    }],
+                width: transcoded.width,
+                height: transcoded.height,
+                internalFormat: transcoded.internalFormat,
+                compressed: transcoded.compressed,
+                generateMipmap: false,
+                format: transcoded.internalFormat // Phaser uses this for compressionAlgorithm
+            };
+            // Add to Phaser's texture manager as a compressed texture
+            const phaserTexture = scene.textures.addCompressedTexture(key, compressedTextureData);
+            // Cache it
+            this.textureCache.set(key, phaserTexture);
+            return phaserTexture;
+        }
+        /**
+         * Load texture by index into a specific GL context
+         */
+        async loadTextureInContext(index, gl) {
+            // Read texture data
+            const data = this.reader.readAssetData(index);
+            if (!data) {
+                throw new Error(`Failed to read texture data for index ${index}`);
+            }
+            // Get metadata - all textures in .stow files are KTX2 format
+            const metadata = this.reader.parseTextureMetadata(index);
+            const isKtx2 = metadata?.channelFormat !== undefined;
+            if (isKtx2) {
+                // Transcode KTX2 to WebGL texture using the provided context
+                const transcoded = await this.transcoder.transcodeKTX2(data, gl);
+                // Create WebGL texture in the provided context
+                const texture = gl.createTexture();
+                if (!texture) {
+                    throw new Error('Failed to create WebGL texture');
+                }
+                gl.bindTexture(gl.TEXTURE_2D, texture);
+                if (transcoded.compressed) {
+                    gl.compressedTexImage2D(gl.TEXTURE_2D, 0, transcoded.internalFormat, transcoded.width, transcoded.height, 0, transcoded.data);
+                }
+                else {
+                    gl.texImage2D(gl.TEXTURE_2D, 0, transcoded.internalFormat, transcoded.width, transcoded.height, 0, transcoded.format, gl.UNSIGNED_BYTE, transcoded.data);
+                }
+                gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+                gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+                gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+                gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+                gl.bindTexture(gl.TEXTURE_2D, null);
+                return {
+                    texture,
+                    width: transcoded.width,
+                    height: transcoded.height
+                };
+            }
+            else {
+                // Handle uncompressed image data
+                return await this.loadUncompressedTextureInContext(data, gl);
+            }
+        }
+        /**
+         * Load uncompressed image (PNG, JPEG) as WebGL texture in a specific context
+         */
+        async loadUncompressedTextureInContext(data, gl) {
+            return new Promise((resolve, reject) => {
+                const blob = new Blob([data.buffer]);
+                const url = URL.createObjectURL(blob);
+                const img = new Image();
+                img.onload = () => {
+                    const texture = gl.createTexture();
+                    if (!texture) {
+                        URL.revokeObjectURL(url);
+                        reject(new Error('Failed to create WebGL texture'));
+                        return;
+                    }
+                    gl.bindTexture(gl.TEXTURE_2D, texture);
+                    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+                    gl.bindTexture(gl.TEXTURE_2D, null);
+                    URL.revokeObjectURL(url);
+                    resolve({
+                        texture,
+                        width: img.width,
+                        height: img.height
+                    });
+                };
+                img.onerror = () => {
+                    URL.revokeObjectURL(url);
+                    reject(new Error('Failed to load image'));
+                };
+                img.src = url;
+            });
+        }
+        /**
+         * Load audio by its canonical path/name
+         * Returns an AudioBuffer
+         */
+        async loadAudio(assetPath, audioContext) {
+            // Find asset by path
+            const assetIndex = this.reader.findAssetByPath(assetPath);
+            if (assetIndex < 0) {
+                throw new Error(`Audio not found: ${assetPath}`);
+            }
+            // Verify it's audio
+            const info = this.reader.getAssetInfo(assetIndex);
+            if (!info || info.type !== stowkitReader.AssetType.AUDIO) {
+                throw new Error(`Asset is not audio: ${assetPath}`);
+            }
+            return await this.loadAudioByIndex(assetIndex, audioContext);
+        }
+        /**
+         * Load audio by index
+         */
+        async loadAudioByIndex(index, audioContext) {
+            const data = this.reader.readAssetData(index);
+            if (!data) {
+                throw new Error(`Failed to read audio data for index ${index}`);
+            }
+            // Use provided context or create a new one
+            const ctx = audioContext || new AudioContext();
+            // Decode audio data
+            const arrayBuffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+            const audioBuffer = await ctx.decodeAudioData(arrayBuffer);
+            return audioBuffer;
+        }
+        /**
+         * Create an HTML audio element for preview
+         */
+        async createAudioPreview(index) {
+            const data = this.reader.readAssetData(index);
+            if (!data) {
+                throw new Error(`Failed to read audio for index ${index}`);
+            }
+            const blob = new Blob([data.buffer], { type: 'audio/mp4' });
+            const url = URL.createObjectURL(blob);
+            const audio = document.createElement('audio');
+            audio.controls = true;
+            audio.src = url;
+            audio.addEventListener('ended', () => URL.revokeObjectURL(url));
+            audio.addEventListener('error', () => URL.revokeObjectURL(url));
+            return audio;
+        }
+        /**
+         * Get list of all assets in pack
+         */
+        listAssets() {
+            return this.reader.listAssets();
+        }
+        /**
+         * Get asset count
+         */
+        getAssetCount() {
+            return this.reader.getAssetCount();
+        }
+        /**
+         * Get asset info by index
+         */
+        getAssetInfo(index) {
+            return this.reader.getAssetInfo(index);
+        }
+        /**
+         * Get texture metadata
+         */
+        getTextureMetadata(index) {
+            return this.reader.parseTextureMetadata(index);
+        }
+        /**
+         * Get audio metadata
+         */
+        getAudioMetadata(index) {
+            return this.reader.parseAudioMetadata(index);
+        }
+        /**
+         * Close the pack and free resources
+         */
+        dispose() {
+            // Clear texture cache (Phaser manages texture disposal)
+            this.textureCache.clear();
+            this.transcodedDataCache.clear();
+            // Close reader
+            this.reader.close();
+        }
+    }
+
+    /**
+     * 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');
+     * ```
+     */
+    class StowKitPhaserLoader {
+        /**
+         * Load a .stow pack file from a URL
+         */
+        static async load(url, options) {
+            // Initialize loaders if needed
+            if (!this.initialized) {
+                await this.initialize(options);
+            }
+            // Fetch the pack file
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            // Create a new reader instance for this pack
+            const reader = new stowkitReader.StowKitReader(this.wasmPath);
+            await reader.init();
+            await reader.open(arrayBuffer);
+            // Return pack wrapper with its own dedicated reader
+            return new StowKitPhaserPack(reader, this.transcoder, this.gl);
+        }
+        /**
+         * Load a .stow pack from memory (ArrayBuffer, Blob, or File)
+         */
+        static async loadFromMemory(data, options) {
+            // Initialize loaders if needed
+            if (!this.initialized) {
+                await this.initialize(options);
+            }
+            // Convert to ArrayBuffer if needed
+            let arrayBuffer;
+            if (data instanceof ArrayBuffer) {
+                arrayBuffer = data;
+            }
+            else if (typeof Blob !== 'undefined' && data instanceof Blob) {
+                arrayBuffer = await data.arrayBuffer();
+            }
+            else if ('arrayBuffer' in data && typeof data.arrayBuffer === 'function') {
+                arrayBuffer = await data.arrayBuffer();
+            }
+            else {
+                throw new Error('Data must be ArrayBuffer, Blob, or File');
+            }
+            // Create a new reader instance for this pack
+            const reader = new stowkitReader.StowKitReader(this.wasmPath);
+            await reader.init();
+            await reader.open(arrayBuffer);
+            // Return pack wrapper with its own dedicated reader
+            return new StowKitPhaserPack(reader, this.transcoder, this.gl);
+        }
+        /**
+         * Initialize the loader (called automatically on first load)
+         */
+        static async initialize(options) {
+            this.wasmPath = options?.wasmPath || '/stowkit/stowkit_reader.wasm';
+            const basisPath = options?.basisPath || '/basis/';
+            // Get or create WebGL context (shared across all packs)
+            if (options?.gl) {
+                this.gl = options.gl;
+                this.ownGl = false;
+            }
+            else {
+                // Create a temporary canvas for WebGL operations
+                const canvas = document.createElement('canvas');
+                canvas.width = 1;
+                canvas.height = 1;
+                canvas.style.display = 'none';
+                document.body.appendChild(canvas);
+                this.gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
+                if (!this.gl) {
+                    throw new Error('Failed to create WebGL context');
+                }
+                this.ownGl = true;
+            }
+            // Initialize basis transcoder (shared across all packs)
+            this.transcoder = new BasisTranscoder(basisPath);
+            await this.transcoder.init();
+            this.initialized = true;
+        }
+        /**
+         * Dispose of shared resources
+         */
+        static dispose() {
+            if (this.transcoder) {
+                this.transcoder.dispose();
+                this.transcoder = null;
+            }
+            // Only dispose GL if we created it
+            if (this.gl && this.ownGl) {
+                const canvas = this.gl.canvas;
+                if (canvas && canvas.parentNode) {
+                    canvas.parentNode.removeChild(canvas);
+                }
+                this.gl = null;
+            }
+            this.initialized = false;
+        }
+    }
+    StowKitPhaserLoader.transcoder = null;
+    StowKitPhaserLoader.initialized = false;
+    StowKitPhaserLoader.gl = null;
+    StowKitPhaserLoader.ownGl = false;
+    StowKitPhaserLoader.wasmPath = '/stowkit/stowkit_reader.wasm';
+
+    Object.defineProperty(exports, "AssetType", {
+        enumerable: true,
+        get: function () { return stowkitReader.AssetType; }
+    });
+    Object.defineProperty(exports, "PerfLogger", {
+        enumerable: true,
+        get: function () { return stowkitReader.PerfLogger; }
+    });
+    exports.BasisTranscoder = BasisTranscoder;
+    exports.StowKitPhaserLoader = StowKitPhaserLoader;
+    exports.StowKitPhaserPack = StowKitPhaserPack;
+
+}));
+//# sourceMappingURL=stowkit-phaser-loader.js.map