@series-inc/stowkit-phaser-loader 0.1.18

package/dist/stowkit-phaser-loader.esm.js

@@ -0,0 +1,623 @@
+import { PerfLogger, AssetType, StowKitReader } from '@series-inc/stowkit-reader';
+export { AssetType, PerfLogger } from '@series-inc/stowkit-reader';
+
+/**
+ * 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)) {
+            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 !== 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);
+        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);
+        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 !== 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(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(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';
+
+export { BasisTranscoder, StowKitPhaserLoader, StowKitPhaserPack };
+//# sourceMappingURL=stowkit-phaser-loader.esm.js.map