@energy8platform/game-engine 0.1.0

package/dist/core.esm.js

@@ -0,0 +1,1827 @@
+import { Ticker, Assets, Container, Application } from 'pixi.js';
+import { CasinoGameSDK } from '@energy8platform/game-sdk';
+
+// ─── Scale Modes ───────────────────────────────────────────
+var ScaleMode;
+(function (ScaleMode) {
+    /** Fit inside container, maintain aspect ratio (letterbox/pillarbox) */
+    ScaleMode["FIT"] = "FIT";
+    /** Fill container, maintain aspect ratio (crop edges) */
+    ScaleMode["FILL"] = "FILL";
+    /** Stretch to fill (distorts) */
+    ScaleMode["STRETCH"] = "STRETCH";
+})(ScaleMode || (ScaleMode = {}));
+// ─── Orientation ───────────────────────────────────────────
+var Orientation;
+(function (Orientation) {
+    Orientation["LANDSCAPE"] = "landscape";
+    Orientation["PORTRAIT"] = "portrait";
+    Orientation["ANY"] = "any";
+})(Orientation || (Orientation = {}));
+// ─── Transition Types ──────────────────────────────────────
+var TransitionType;
+(function (TransitionType) {
+    TransitionType["NONE"] = "none";
+    TransitionType["FADE"] = "fade";
+    TransitionType["SLIDE_LEFT"] = "slide-left";
+    TransitionType["SLIDE_RIGHT"] = "slide-right";
+})(TransitionType || (TransitionType = {}));
+
+/**
+ * Minimal typed event emitter.
+ * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+class EventEmitter {
+    listeners = new Map();
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        return this;
+    }
+    once(event, handler) {
+        const wrapper = (data) => {
+            this.off(event, wrapper);
+            handler(data);
+        };
+        return this.on(event, wrapper);
+    }
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+        return this;
+    }
+    emit(event, data) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(data);
+            }
+        }
+    }
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+}
+
+/**
+ * Collection of easing functions for use with Tween and Timeline.
+ *
+ * All functions take a progress value t (0..1) and return the eased value.
+ */
+const Easing = {
+    easeOutQuad: (t) => t * (2 - t)};
+
+/**
+ * Lightweight tween system integrated with PixiJS Ticker.
+ * Zero external dependencies — no GSAP required.
+ *
+ * All tweens return a Promise that resolves on completion.
+ *
+ * @example
+ * ```ts
+ * // Fade in a sprite
+ * await Tween.to(sprite, { alpha: 1, y: 100 }, 500, Easing.easeOutBack);
+ *
+ * // Move and wait
+ * await Tween.to(sprite, { x: 500 }, 300);
+ *
+ * // From a starting value
+ * await Tween.from(sprite, { scale: 0, alpha: 0 }, 400);
+ * ```
+ */
+class Tween {
+    static _tweens = [];
+    static _tickerAdded = false;
+    /**
+     * Animate properties from current values to target values.
+     *
+     * @param target - Object to animate (Sprite, Container, etc.)
+     * @param props - Target property values
+     * @param duration - Duration in milliseconds
+     * @param easing - Easing function (default: easeOutQuad)
+     * @param onUpdate - Progress callback (0..1)
+     */
+    static to(target, props, duration, easing, onUpdate) {
+        return new Promise((resolve) => {
+            // Capture starting values
+            const from = {};
+            for (const key of Object.keys(props)) {
+                from[key] = Tween.getProperty(target, key);
+            }
+            const tween = {
+                target,
+                from,
+                to: { ...props },
+                duration: Math.max(1, duration),
+                easing: easing ?? Easing.easeOutQuad,
+                elapsed: 0,
+                delay: 0,
+                resolve,
+                onUpdate,
+            };
+            Tween._tweens.push(tween);
+            Tween.ensureTicker();
+        });
+    }
+    /**
+     * Animate properties from given values to current values.
+     */
+    static from(target, props, duration, easing, onUpdate) {
+        // Capture current values as "to"
+        const to = {};
+        for (const key of Object.keys(props)) {
+            to[key] = Tween.getProperty(target, key);
+            Tween.setProperty(target, key, props[key]);
+        }
+        return Tween.to(target, to, duration, easing, onUpdate);
+    }
+    /**
+     * Animate from one set of values to another.
+     */
+    static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        // Set starting values
+        for (const key of Object.keys(fromProps)) {
+            Tween.setProperty(target, key, fromProps[key]);
+        }
+        return Tween.to(target, toProps, duration, easing, onUpdate);
+    }
+    /**
+     * Wait for a given duration (useful in timelines).
+     */
+    static delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Kill all tweens on a target.
+     */
+    static killTweensOf(target) {
+        Tween._tweens = Tween._tweens.filter((tw) => {
+            if (tw.target === target) {
+                tw.resolve();
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Kill all active tweens.
+     */
+    static killAll() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+    }
+    /** Number of active tweens */
+    static get activeTweens() {
+        return Tween._tweens.length;
+    }
+    // ─── Internal ──────────────────────────────────────────
+    static ensureTicker() {
+        if (Tween._tickerAdded)
+            return;
+        Tween._tickerAdded = true;
+        Ticker.shared.add(Tween.tick);
+    }
+    static tick = (ticker) => {
+        const dt = ticker.deltaMS;
+        const completed = [];
+        for (const tw of Tween._tweens) {
+            tw.elapsed += dt;
+            if (tw.elapsed < tw.delay)
+                continue;
+            const raw = Math.min((tw.elapsed - tw.delay) / tw.duration, 1);
+            const t = tw.easing(raw);
+            // Interpolate each property
+            for (const key of Object.keys(tw.to)) {
+                const start = tw.from[key];
+                const end = tw.to[key];
+                const value = start + (end - start) * t;
+                Tween.setProperty(tw.target, key, value);
+            }
+            tw.onUpdate?.(raw);
+            if (raw >= 1) {
+                completed.push(tw);
+            }
+        }
+        // Remove completed tweens
+        for (const tw of completed) {
+            const idx = Tween._tweens.indexOf(tw);
+            if (idx !== -1)
+                Tween._tweens.splice(idx, 1);
+            tw.resolve();
+        }
+        // Remove ticker when no active tweens
+        if (Tween._tweens.length === 0 && Tween._tickerAdded) {
+            Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    };
+    /**
+     * Get a potentially nested property (supports 'scale.x', 'position.y', etc.)
+     */
+    static getProperty(target, key) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        return obj[parts[parts.length - 1]] ?? 0;
+    }
+    /**
+     * Set a potentially nested property.
+     */
+    static setProperty(target, key, value) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        obj[parts[parts.length - 1]] = value;
+    }
+}
+
+/**
+ * Manages the scene stack and transitions between scenes.
+ *
+ * @example
+ * ```ts
+ * const scenes = new SceneManager(app.stage);
+ * scenes.register('loading', LoadingScene);
+ * scenes.register('game', GameScene);
+ * await scenes.goto('loading');
+ * ```
+ */
+class SceneManager extends EventEmitter {
+    /** Root container that scenes are added to */
+    root;
+    registry = new Map();
+    stack = [];
+    _transitioning = false;
+    /** Current viewport dimensions — set by ViewportManager */
+    _width = 0;
+    _height = 0;
+    constructor(root) {
+        super();
+        if (root)
+            this.root = root;
+    }
+    /** @internal Set the root container (called by GameApplication after PixiJS init) */
+    setRoot(root) {
+        this.root = root;
+    }
+    /** Register a scene class by key */
+    register(key, ctor) {
+        this.registry.set(key, ctor);
+        return this;
+    }
+    /** Get the current (topmost) scene entry */
+    get current() {
+        return this.stack.length > 0 ? this.stack[this.stack.length - 1] : null;
+    }
+    /** Get the current scene key */
+    get currentKey() {
+        return this.current?.key ?? null;
+    }
+    /** Whether a scene transition is in progress */
+    get isTransitioning() {
+        return this._transitioning;
+    }
+    /**
+     * Navigate to a scene, replacing the entire stack.
+     */
+    async goto(key, data, transition) {
+        const prevKey = this.currentKey;
+        // Exit all current scenes
+        while (this.stack.length > 0) {
+            await this.popInternal(false);
+        }
+        // Enter new scene
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Push a scene onto the stack (the previous scene stays underneath).
+     * Useful for overlays, modals, pause screens.
+     */
+    async push(key, data, transition) {
+        const prevKey = this.currentKey;
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Pop the top scene from the stack.
+     */
+    async pop(transition) {
+        if (this.stack.length <= 1) {
+            console.warn('[SceneManager] Cannot pop the last scene');
+            return;
+        }
+        const prevKey = this.currentKey;
+        await this.popInternal(true, transition);
+        this.emit('change', { from: prevKey, to: this.currentKey });
+    }
+    /**
+     * Replace the top scene with a new one.
+     */
+    async replace(key, data, transition) {
+        const prevKey = this.currentKey;
+        await this.popInternal(false);
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Called every frame by GameApplication.
+     */
+    update(dt) {
+        // Update only the top scene
+        this.current?.scene.onUpdate?.(dt);
+    }
+    /**
+     * Called on viewport resize.
+     */
+    resize(width, height) {
+        this._width = width;
+        this._height = height;
+        // Notify all scenes in the stack
+        for (const entry of this.stack) {
+            entry.scene.onResize?.(width, height);
+        }
+    }
+    /**
+     * Destroy all scenes and clear the manager.
+     */
+    destroy() {
+        for (const entry of this.stack) {
+            entry.scene.onDestroy?.();
+            entry.scene.container.destroy({ children: true });
+        }
+        this.stack.length = 0;
+        this.registry.clear();
+        this.removeAllListeners();
+    }
+    // ─── Internal ──────────────────────────────────────────
+    createScene(key) {
+        const Ctor = this.registry.get(key);
+        if (!Ctor) {
+            throw new Error(`[SceneManager] Scene "${key}" is not registered`);
+        }
+        return new Ctor();
+    }
+    async pushInternal(key, data, transition) {
+        this._transitioning = true;
+        const scene = this.createScene(key);
+        this.root.addChild(scene.container);
+        // Set initial size
+        if (this._width && this._height) {
+            scene.onResize?.(this._width, this._height);
+        }
+        // Transition in
+        await this.transitionIn(scene.container, transition);
+        await scene.onEnter?.(data);
+        this.stack.push({ scene, key });
+        this._transitioning = false;
+    }
+    async popInternal(showTransition, transition) {
+        const entry = this.stack.pop();
+        if (!entry)
+            return;
+        this._transitioning = true;
+        await entry.scene.onExit?.();
+        if (showTransition) {
+            await this.transitionOut(entry.scene.container, transition);
+        }
+        entry.scene.onDestroy?.();
+        entry.scene.container.destroy({ children: true });
+        this._transitioning = false;
+    }
+    async transitionIn(container, config) {
+        const type = config?.type ?? TransitionType.NONE;
+        const duration = config?.duration ?? 300;
+        if (type === TransitionType.NONE || duration <= 0)
+            return;
+        if (type === TransitionType.FADE) {
+            container.alpha = 0;
+            await Tween.to(container, { alpha: 1 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_LEFT) {
+            container.x = this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_RIGHT) {
+            container.x = -this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+    }
+    async transitionOut(container, config) {
+        const type = config?.type ?? TransitionType.FADE;
+        const duration = config?.duration ?? 300;
+        if (type === TransitionType.NONE || duration <= 0)
+            return;
+        if (type === TransitionType.FADE) {
+            await Tween.to(container, { alpha: 0 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_LEFT) {
+            await Tween.to(container, { x: -this._width }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_RIGHT) {
+            await Tween.to(container, { x: this._width }, duration, config?.easing);
+        }
+    }
+}
+
+/**
+ * Manages game asset loading with progress tracking, bundle support, and
+ * automatic base path resolution from SDK's assetsUrl.
+ *
+ * Wraps PixiJS Assets API with a typed, game-oriented interface.
+ *
+ * @example
+ * ```ts
+ * const assets = new AssetManager('https://cdn.example.com/game/', manifest);
+ * await assets.init();
+ * await assets.loadBundle('preload', (p) => console.log(p));
+ * const texture = assets.get<Texture>('hero');
+ * ```
+ */
+class AssetManager {
+    _initialized = false;
+    _basePath;
+    _manifest;
+    _loadedBundles = new Set();
+    constructor(basePath = '', manifest) {
+        this._basePath = basePath;
+        this._manifest = manifest ?? null;
+    }
+    /** Whether the asset system has been initialized */
+    get initialized() {
+        return this._initialized;
+    }
+    /** Base path for all assets (usually from SDK's assetsUrl) */
+    get basePath() {
+        return this._basePath;
+    }
+    /** Set of loaded bundle names */
+    get loadedBundles() {
+        return this._loadedBundles;
+    }
+    /**
+     * Initialize the asset system.
+     * Must be called before loading any assets.
+     */
+    async init() {
+        if (this._initialized)
+            return;
+        await Assets.init({
+            basePath: this._basePath || undefined,
+            texturePreference: {
+                resolution: Math.min(window.devicePixelRatio, 2),
+                format: ['webp', 'png'],
+            },
+        });
+        // Register bundles from manifest
+        if (this._manifest) {
+            for (const bundle of this._manifest.bundles) {
+                Assets.addBundle(bundle.name, bundle.assets.map((a) => ({
+                    alias: a.alias,
+                    src: a.src,
+                    data: a.data,
+                })));
+            }
+        }
+        this._initialized = true;
+    }
+    /**
+     * Load a single bundle by name.
+     *
+     * @param name - Bundle name (must exist in the manifest)
+     * @param onProgress - Progress callback (0..1)
+     * @returns Loaded assets map
+     */
+    async loadBundle(name, onProgress) {
+        this.ensureInitialized();
+        const result = await Assets.loadBundle(name, onProgress);
+        this._loadedBundles.add(name);
+        return result;
+    }
+    /**
+     * Load multiple bundles simultaneously.
+     * Progress is aggregated across all bundles.
+     *
+     * @param names - Bundle names
+     * @param onProgress - Progress callback (0..1)
+     */
+    async loadBundles(names, onProgress) {
+        this.ensureInitialized();
+        const result = await Assets.loadBundle(names, onProgress);
+        for (const name of names) {
+            this._loadedBundles.add(name);
+        }
+        return result;
+    }
+    /**
+     * Load individual assets by URL or alias.
+     *
+     * @param urls - Asset URLs or aliases
+     * @param onProgress - Progress callback (0..1)
+     */
+    async load(urls, onProgress) {
+        this.ensureInitialized();
+        return Assets.load(urls, onProgress);
+    }
+    /**
+     * Get a loaded asset synchronously from cache.
+     *
+     * @param alias - Asset alias
+     * @throws if not loaded
+     */
+    get(alias) {
+        return Assets.get(alias);
+    }
+    /**
+     * Unload a bundle to free memory.
+     */
+    async unloadBundle(name) {
+        await Assets.unloadBundle(name);
+        this._loadedBundles.delete(name);
+    }
+    /**
+     * Start background loading a bundle (low-priority preload).
+     * Useful for loading bonus round assets while player is in base game.
+     */
+    async backgroundLoad(name) {
+        this.ensureInitialized();
+        await Assets.backgroundLoadBundle(name);
+    }
+    /**
+     * Get all bundle names from the manifest.
+     */
+    getBundleNames() {
+        return this._manifest?.bundles.map((b) => b.name) ?? [];
+    }
+    /**
+     * Check if a bundle is loaded.
+     */
+    isBundleLoaded(name) {
+        return this._loadedBundles.has(name);
+    }
+    ensureInitialized() {
+        if (!this._initialized) {
+            throw new Error('[AssetManager] Not initialized. Call init() first.');
+        }
+    }
+}
+
+/**
+ * Manages all game audio: music, SFX, UI sounds, ambient.
+ *
+ * Optional dependency on @pixi/sound — if not installed, AudioManager
+ * operates as a silent no-op (graceful degradation).
+ *
+ * Features:
+ * - Per-category volume control (music, sfx, ui, ambient)
+ * - Music crossfade and looping
+ * - Mobile audio unlock on first interaction
+ * - Mute state persistence in localStorage
+ * - Global mute/unmute
+ *
+ * @example
+ * ```ts
+ * const audio = new AudioManager({ music: 0.5, sfx: 0.8 });
+ * await audio.init();
+ * audio.playMusic('bg-music');
+ * audio.play('spin-click', 'sfx');
+ * ```
+ */
+class AudioManager {
+    _soundModule = null;
+    _initialized = false;
+    _globalMuted = false;
+    _persist;
+    _storageKey;
+    _categories;
+    _currentMusic = null;
+    _unlocked = false;
+    _unlockHandler = null;
+    constructor(config) {
+        this._persist = config?.persist ?? true;
+        this._storageKey = config?.storageKey ?? 'ge_audio';
+        this._categories = {
+            music: { volume: config?.music ?? 0.7, muted: false },
+            sfx: { volume: config?.sfx ?? 1.0, muted: false },
+            ui: { volume: config?.ui ?? 0.8, muted: false },
+            ambient: { volume: config?.ambient ?? 0.5, muted: false },
+        };
+        // Restore persisted state
+        if (this._persist) {
+            this.restoreState();
+        }
+    }
+    /** Whether the audio system is initialized */
+    get initialized() {
+        return this._initialized;
+    }
+    /** Whether audio is globally muted */
+    get muted() {
+        return this._globalMuted;
+    }
+    /**
+     * Initialize the audio system.
+     * Dynamically imports @pixi/sound to keep it optional.
+     */
+    async init() {
+        if (this._initialized)
+            return;
+        try {
+            this._soundModule = await import('@pixi/sound');
+            this._initialized = true;
+            this.applyVolumes();
+            this.setupMobileUnlock();
+        }
+        catch {
+            console.warn('[AudioManager] @pixi/sound not available. Audio disabled.');
+            this._initialized = false;
+        }
+    }
+    /**
+     * Play a sound effect.
+     *
+     * @param alias - Sound alias (must be loaded via AssetManager)
+     * @param category - Audio category (default: 'sfx')
+     * @param options - Additional play options
+     */
+    play(alias, category = 'sfx', options) {
+        if (!this._initialized || !this._soundModule)
+            return;
+        if (this._globalMuted || this._categories[category].muted)
+            return;
+        const { sound } = this._soundModule;
+        const vol = (options?.volume ?? 1) * this._categories[category].volume;
+        try {
+            sound.play(alias, {
+                volume: vol,
+                loop: options?.loop ?? false,
+                speed: options?.speed ?? 1,
+            });
+        }
+        catch (e) {
+            console.warn(`[AudioManager] Failed to play "${alias}":`, e);
+        }
+    }
+    /**
+     * Play background music with optional crossfade.
+     *
+     * @param alias - Music alias
+     * @param fadeDuration - Crossfade duration in ms (default: 500)
+     */
+    playMusic(alias, fadeDuration = 500) {
+        if (!this._initialized || !this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        // Stop current music
+        if (this._currentMusic) {
+            try {
+                sound.stop(this._currentMusic);
+            }
+            catch {
+                // ignore
+            }
+        }
+        this._currentMusic = alias;
+        if (this._globalMuted || this._categories.music.muted)
+            return;
+        try {
+            sound.play(alias, {
+                volume: this._categories.music.volume,
+                loop: true,
+            });
+        }
+        catch (e) {
+            console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
+        }
+    }
+    /**
+     * Stop current music.
+     */
+    stopMusic() {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        try {
+            sound.stop(this._currentMusic);
+        }
+        catch {
+            // ignore
+        }
+        this._currentMusic = null;
+    }
+    /**
+     * Stop all sounds.
+     */
+    stopAll() {
+        if (!this._initialized || !this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        sound.stopAll();
+        this._currentMusic = null;
+    }
+    /**
+     * Set volume for a category.
+     */
+    setVolume(category, volume) {
+        this._categories[category].volume = Math.max(0, Math.min(1, volume));
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Get volume for a category.
+     */
+    getVolume(category) {
+        return this._categories[category].volume;
+    }
+    /**
+     * Mute a specific category.
+     */
+    muteCategory(category) {
+        this._categories[category].muted = true;
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Unmute a specific category.
+     */
+    unmuteCategory(category) {
+        this._categories[category].muted = false;
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Toggle mute for a category.
+     */
+    toggleCategory(category) {
+        this._categories[category].muted = !this._categories[category].muted;
+        this.applyVolumes();
+        this.saveState();
+        return this._categories[category].muted;
+    }
+    /**
+     * Mute all audio globally.
+     */
+    muteAll() {
+        this._globalMuted = true;
+        if (this._soundModule) {
+            this._soundModule.sound.muteAll();
+        }
+        this.saveState();
+    }
+    /**
+     * Unmute all audio globally.
+     */
+    unmuteAll() {
+        this._globalMuted = false;
+        if (this._soundModule) {
+            this._soundModule.sound.unmuteAll();
+        }
+        this.saveState();
+    }
+    /**
+     * Toggle global mute.
+     */
+    toggleMute() {
+        if (this._globalMuted) {
+            this.unmuteAll();
+        }
+        else {
+            this.muteAll();
+        }
+        return this._globalMuted;
+    }
+    /**
+     * Duck music volume (e.g., during big win presentation).
+     *
+     * @param factor - Volume multiplier (0..1), e.g. 0.3 = 30% of normal
+     */
+    duckMusic(factor) {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        const vol = this._categories.music.volume * factor;
+        try {
+            sound.volume(this._currentMusic, vol);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /**
+     * Restore music to normal volume after ducking.
+     */
+    unduckMusic() {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        try {
+            sound.volume(this._currentMusic, this._categories.music.volume);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /**
+     * Destroy the audio manager and free resources.
+     */
+    destroy() {
+        this.stopAll();
+        this.removeMobileUnlock();
+        if (this._soundModule) {
+            this._soundModule.sound.removeAll();
+        }
+        this._initialized = false;
+    }
+    // ─── Private ───────────────────────────────────────────
+    applyVolumes() {
+        if (!this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        sound.volumeAll = this._globalMuted ? 0 : 1;
+    }
+    setupMobileUnlock() {
+        if (this._unlocked)
+            return;
+        this._unlockHandler = () => {
+            if (!this._soundModule)
+                return;
+            const { sound } = this._soundModule;
+            // Resume WebAudio context
+            if (sound.context?.audioContext?.state === 'suspended') {
+                sound.context.audioContext.resume();
+            }
+            this._unlocked = true;
+            this.removeMobileUnlock();
+        };
+        const events = ['touchstart', 'mousedown', 'pointerdown', 'keydown'];
+        for (const event of events) {
+            document.addEventListener(event, this._unlockHandler, { once: true });
+        }
+    }
+    removeMobileUnlock() {
+        if (!this._unlockHandler)
+            return;
+        const events = ['touchstart', 'mousedown', 'pointerdown', 'keydown'];
+        for (const event of events) {
+            document.removeEventListener(event, this._unlockHandler);
+        }
+        this._unlockHandler = null;
+    }
+    saveState() {
+        if (!this._persist)
+            return;
+        try {
+            const state = {
+                globalMuted: this._globalMuted,
+                categories: this._categories,
+            };
+            localStorage.setItem(this._storageKey, JSON.stringify(state));
+        }
+        catch {
+            // localStorage may not be available
+        }
+    }
+    restoreState() {
+        try {
+            const raw = localStorage.getItem(this._storageKey);
+            if (!raw)
+                return;
+            const state = JSON.parse(raw);
+            if (typeof state.globalMuted === 'boolean') {
+                this._globalMuted = state.globalMuted;
+            }
+            if (state.categories) {
+                for (const key of ['music', 'sfx', 'ui', 'ambient']) {
+                    if (state.categories[key]) {
+                        this._categories[key] = {
+                            volume: state.categories[key].volume ?? this._categories[key].volume,
+                            muted: state.categories[key].muted ?? false,
+                        };
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+
+/**
+ * Manages responsive scaling of the game canvas to fit its container.
+ *
+ * Supports three scale modes:
+ * - **FIT** — letterbox/pillarbox to maintain aspect ratio (industry standard)
+ * - **FILL** — fill container, crop edges
+ * - **STRETCH** — stretch to fill (distorts)
+ *
+ * Also handles:
+ * - Orientation detection (landscape/portrait)
+ * - Safe areas (mobile notch)
+ * - ResizeObserver for smooth container resizing
+ *
+ * @example
+ * ```ts
+ * const viewport = new ViewportManager(app, container, {
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   orientation: Orientation.LANDSCAPE,
+ * });
+ *
+ * viewport.on('resize', ({ width, height, scale }) => {
+ *   console.log(`New size: ${width}x${height} @ ${scale}x`);
+ * });
+ * ```
+ */
+class ViewportManager extends EventEmitter {
+    _app;
+    _container;
+    _config;
+    _resizeObserver = null;
+    _currentOrientation = Orientation.LANDSCAPE;
+    _currentWidth = 0;
+    _currentHeight = 0;
+    _currentScale = 1;
+    _destroyed = false;
+    _resizeTimeout = null;
+    constructor(app, container, config) {
+        super();
+        this._app = app;
+        this._container = container;
+        this._config = config;
+        this.setupObserver();
+    }
+    /** Current canvas width in game units */
+    get width() {
+        return this._currentWidth;
+    }
+    /** Current canvas height in game units */
+    get height() {
+        return this._currentHeight;
+    }
+    /** Current scale factor */
+    get scale() {
+        return this._currentScale;
+    }
+    /** Current orientation */
+    get orientation() {
+        return this._currentOrientation;
+    }
+    /** Design reference width */
+    get designWidth() {
+        return this._config.designWidth;
+    }
+    /** Design reference height */
+    get designHeight() {
+        return this._config.designHeight;
+    }
+    /**
+     * Force a resize calculation. Called automatically on container size change.
+     */
+    refresh() {
+        if (this._destroyed)
+            return;
+        const containerWidth = this._container.clientWidth || window.innerWidth;
+        const containerHeight = this._container.clientHeight || window.innerHeight;
+        if (containerWidth === 0 || containerHeight === 0)
+            return;
+        const { designWidth, designHeight, scaleMode } = this._config;
+        const designRatio = designWidth / designHeight;
+        const containerRatio = containerWidth / containerHeight;
+        let gameWidth;
+        let gameHeight;
+        let scale;
+        switch (scaleMode) {
+            case ScaleMode.FIT: {
+                if (containerRatio > designRatio) {
+                    // Container is wider → pillarbox
+                    scale = containerHeight / designHeight;
+                    gameWidth = designWidth;
+                    gameHeight = designHeight;
+                }
+                else {
+                    // Container is taller → letterbox
+                    scale = containerWidth / designWidth;
+                    gameWidth = designWidth;
+                    gameHeight = designHeight;
+                }
+                break;
+            }
+            case ScaleMode.FILL: {
+                if (containerRatio > designRatio) {
+                    // Container is wider → crop top/bottom
+                    scale = containerWidth / designWidth;
+                }
+                else {
+                    // Container is taller → crop left/right
+                    scale = containerHeight / designHeight;
+                }
+                gameWidth = containerWidth / scale;
+                gameHeight = containerHeight / scale;
+                break;
+            }
+            case ScaleMode.STRETCH: {
+                gameWidth = designWidth;
+                gameHeight = designHeight;
+                scale = 1; // stretch is handled by CSS
+                break;
+            }
+            default:
+                gameWidth = designWidth;
+                gameHeight = designHeight;
+                scale = 1;
+        }
+        // Resize the renderer
+        this._app.renderer.resize(Math.round(containerWidth), Math.round(containerHeight));
+        // Scale the stage
+        const stageScale = scaleMode === ScaleMode.STRETCH
+            ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
+            : scale;
+        this._app.stage.scale.set(stageScale);
+        // Center the stage for FIT mode
+        if (scaleMode === ScaleMode.FIT) {
+            this._app.stage.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+            this._app.stage.y = Math.round((containerHeight - designHeight * stageScale) / 2);
+        }
+        else if (scaleMode === ScaleMode.FILL) {
+            this._app.stage.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+            this._app.stage.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
+        }
+        else {
+            this._app.stage.x = 0;
+            this._app.stage.y = 0;
+        }
+        this._currentWidth = gameWidth;
+        this._currentHeight = gameHeight;
+        this._currentScale = stageScale;
+        // Check orientation
+        const newOrientation = containerWidth >= containerHeight ? Orientation.LANDSCAPE : Orientation.PORTRAIT;
+        if (newOrientation !== this._currentOrientation) {
+            this._currentOrientation = newOrientation;
+            this.emit('orientationChange', newOrientation);
+        }
+        this.emit('resize', {
+            width: gameWidth,
+            height: gameHeight,
+            scale: stageScale,
+        });
+    }
+    /**
+     * Destroy the viewport manager.
+     */
+    destroy() {
+        this._destroyed = true;
+        this._resizeObserver?.disconnect();
+        this._resizeObserver = null;
+        if (this._resizeTimeout !== null) {
+            clearTimeout(this._resizeTimeout);
+        }
+        this.removeAllListeners();
+    }
+    // ─── Private ───────────────────────────────────────────
+    setupObserver() {
+        if (typeof ResizeObserver !== 'undefined') {
+            this._resizeObserver = new ResizeObserver(() => {
+                this.debouncedRefresh();
+            });
+            this._resizeObserver.observe(this._container);
+        }
+        else {
+            // Fallback for older browsers
+            window.addEventListener('resize', this.onWindowResize);
+        }
+    }
+    onWindowResize = () => {
+        this.debouncedRefresh();
+    };
+    debouncedRefresh() {
+        if (this._resizeTimeout !== null) {
+            clearTimeout(this._resizeTimeout);
+        }
+        this._resizeTimeout = window.setTimeout(() => {
+            this.refresh();
+            this._resizeTimeout = null;
+        }, 16); // ~1 frame
+    }
+}
+
+/**
+ * Base class for all scenes.
+ * Provides a root PixiJS Container and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * class MenuScene extends Scene {
+ *   async onEnter() {
+ *     const bg = Sprite.from('menu-bg');
+ *     this.container.addChild(bg);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // per-frame logic
+ *   }
+ *
+ *   onResize(width: number, height: number) {
+ *     // reposition UI
+ *   }
+ * }
+ * ```
+ */
+class Scene {
+    container;
+    constructor() {
+        this.container = new Container();
+        this.container.label = this.constructor.name;
+    }
+}
+
+/**
+ * Inline SVG logo with a loader bar (clip-animated for progress).
+ * The clipPath rect width is set to 0 initially, expanded as loading progresses.
+ */
+function buildLogoSVG() {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" style="width:100%;height:auto;">
+  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#ls0)"/>
+  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#ls1)"/>
+  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#ls2)"/>
+  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#ls3)"/>
+  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#ls4)"/>
+  <clipPath id="ge-canvas-loader-clip">
+    <rect id="ge-loader-rect" x="37" y="148" width="0" height="20"/>
+  </clipPath>
+  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#ls5)" clip-path="url(#ge-canvas-loader-clip)"/>
+  <text id="ge-loader-pct" x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.7)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5">0%</text>
+  <defs>
+    <linearGradient id="ls0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+  </defs>
+</svg>`;
+}
+/** Max width of the loader bar in SVG units */
+const LOADER_BAR_MAX_WIDTH = 174;
+/**
+ * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
+ *
+ * Renders as an HTML overlay on top of the canvas for crisp SVG quality.
+ * The loader bar fill width is driven by asset loading progress.
+ */
+class LoadingScene extends Scene {
+    _engine;
+    _targetScene;
+    _targetData;
+    _config;
+    // HTML overlay
+    _overlay = null;
+    _loaderRect = null;
+    _percentEl = null;
+    _tapToStartEl = null;
+    // State
+    _displayedProgress = 0;
+    _targetProgress = 0;
+    _loadingComplete = false;
+    _startTime = 0;
+    async onEnter(data) {
+        const { engine, targetScene, targetData } = data;
+        this._engine = engine;
+        this._targetScene = targetScene;
+        this._targetData = targetData;
+        this._config = engine.config.loading ?? {};
+        this._startTime = Date.now();
+        // Create the HTML overlay with the SVG logo
+        this.createOverlay();
+        // Initialize asset manager
+        await this._engine.assets.init();
+        // Initialize audio manager
+        await this._engine.audio.init();
+        // Phase 1: Load preload bundle
+        const bundles = this._engine.assets.getBundleNames();
+        const hasPreload = bundles.includes('preload');
+        if (hasPreload) {
+            const preloadAssets = this._engine.config.manifest?.bundles?.find((b) => b.name === 'preload')?.assets;
+            if (preloadAssets && preloadAssets.length > 0) {
+                await this._engine.assets.loadBundle('preload', (p) => {
+                    this._targetProgress = p * 0.15;
+                });
+            }
+            else {
+                this._targetProgress = 0.15;
+            }
+        }
+        // Phase 2: Load remaining bundles
+        const remainingBundles = bundles.filter((b) => b !== 'preload' && !this._engine.assets.isBundleLoaded(b));
+        if (remainingBundles.length > 0) {
+            const hasAssets = remainingBundles.some((name) => {
+                const bundle = this._engine.config.manifest?.bundles?.find((b) => b.name === name);
+                return bundle?.assets && bundle.assets.length > 0;
+            });
+            if (hasAssets) {
+                await this._engine.assets.loadBundles(remainingBundles, (p) => {
+                    this._targetProgress = 0.15 + p * 0.85;
+                });
+            }
+        }
+        this._targetProgress = 1;
+        this._loadingComplete = true;
+        // Enforce minimum display time: spread the remaining progress fill
+        // over the remaining time so the bar fills smoothly, not abruptly
+        const minTime = this._config.minDisplayTime ?? 1500;
+        const elapsed = Date.now() - this._startTime;
+        const remaining = Math.max(0, minTime - elapsed);
+        if (remaining > 0) {
+            // Distribute fill animation over the remaining time
+            await this.animateProgressTo(1, remaining);
+        }
+        // Final snap to 100%
+        this._displayedProgress = 1;
+        this.updateLoaderBar(1);
+        // Show "Tap to Start" or transition directly
+        if (this._config.tapToStart !== false) {
+            await this.showTapToStart();
+        }
+        else {
+            await this.transitionToGame();
+        }
+    }
+    onUpdate(dt) {
+        // Smooth progress bar fill via HTML (during active loading)
+        if (!this._loadingComplete && this._displayedProgress < this._targetProgress) {
+            this._displayedProgress = Math.min(this._displayedProgress + dt * 1.5, this._targetProgress);
+            this.updateLoaderBar(this._displayedProgress);
+        }
+    }
+    onResize(_width, _height) {
+        // Overlay is CSS-based, auto-resizes
+    }
+    onDestroy() {
+        this.removeOverlay();
+    }
+    // ─── HTML Overlay ──────────────────────────────────────
+    createOverlay() {
+        const bgColor = typeof this._config.backgroundColor === 'string'
+            ? this._config.backgroundColor
+            : typeof this._config.backgroundColor === 'number'
+                ? `#${this._config.backgroundColor.toString(16).padStart(6, '0')}`
+                : '#0a0a1a';
+        const bgGradient = this._config.backgroundGradient ??
+            `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+        this._overlay = document.createElement('div');
+        this._overlay.id = '__ge-loading-overlay__';
+        this._overlay.innerHTML = `
+      <div class="ge-loading-content">
+        ${buildLogoSVG()}
+      </div>
+    `;
+        const style = document.createElement('style');
+        style.id = '__ge-loading-style__';
+        style.textContent = `
+      #__ge-loading-overlay__ {
+        position: absolute;
+        top: 0; left: 0;
+        width: 100%; height: 100%;
+        background: ${bgGradient};
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 9999;
+        transition: opacity 0.5s ease-out;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      }
+      #__ge-loading-overlay__.ge-fade-out {
+        opacity: 0;
+        pointer-events: none;
+      }
+      .ge-loading-content {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        width: 75%;
+        max-width: 650px;
+      }
+      .ge-loading-content svg {
+        filter: drop-shadow(0 0 40px rgba(121, 57, 194, 0.5));
+        cursor: default;
+      }
+
+      .ge-svg-pulse {
+        animation: ge-tap-pulse 1.2s ease-in-out infinite;
+      }
+      @keyframes ge-tap-pulse {
+        0%, 100% { opacity: 0.5; }
+        50% { opacity: 1; }
+      }
+    `;
+        // Get the container that holds the canvas
+        const container = this._engine.app?.canvas?.parentElement;
+        if (container) {
+            container.style.position = container.style.position || 'relative';
+            container.appendChild(style);
+            container.appendChild(this._overlay);
+        }
+        // Cache the SVG loader rect for progress updates
+        this._loaderRect = this._overlay.querySelector('#ge-loader-rect');
+        this._percentEl = this._overlay.querySelector('#ge-loader-pct');
+    }
+    removeOverlay() {
+        this._overlay?.remove();
+        document.getElementById('__ge-loading-style__')?.remove();
+        this._overlay = null;
+        this._loaderRect = null;
+        this._percentEl = null;
+        this._tapToStartEl = null;
+    }
+    // ─── Progress ──────────────────────────────────────────
+    updateLoaderBar(progress) {
+        if (this._loaderRect) {
+            this._loaderRect.setAttribute('width', String(LOADER_BAR_MAX_WIDTH * progress));
+        }
+        if (this._percentEl) {
+            const pct = Math.round(progress * 100);
+            this._percentEl.textContent = `${pct}%`;
+        }
+    }
+    /**
+     * Smoothly animate the displayed progress from its current value to `target`
+     * over `durationMs` using an easeOutCubic curve.
+     */
+    async animateProgressTo(target, durationMs) {
+        const startVal = this._displayedProgress;
+        const delta = target - startVal;
+        if (delta <= 0 || durationMs <= 0)
+            return;
+        const startTime = Date.now();
+        return new Promise((resolve) => {
+            const tick = () => {
+                const elapsed = Date.now() - startTime;
+                const t = Math.min(elapsed / durationMs, 1);
+                // easeOutCubic for a natural deceleration feel
+                const eased = 1 - Math.pow(1 - t, 3);
+                this._displayedProgress = startVal + delta * eased;
+                this.updateLoaderBar(this._displayedProgress);
+                if (t < 1) {
+                    requestAnimationFrame(tick);
+                }
+                else {
+                    resolve();
+                }
+            };
+            requestAnimationFrame(tick);
+        });
+    }
+    // ─── Tap to Start ─────────────────────────────────────
+    async showTapToStart() {
+        const tapText = this._config.tapToStartText ?? 'TAP TO START';
+        // Reuse the same SVG text element — replace percentage with tap text
+        if (this._percentEl) {
+            const el = this._percentEl;
+            el.textContent = tapText;
+            el.setAttribute('fill', '#ffffff');
+            el.classList.add('ge-svg-pulse');
+            this._tapToStartEl = el;
+        }
+        // Make overlay clickable
+        if (this._overlay) {
+            this._overlay.style.cursor = 'pointer';
+        }
+        // Wait for tap
+        return new Promise((resolve) => {
+            const handler = async () => {
+                this._overlay?.removeEventListener('click', handler);
+                await this.transitionToGame();
+                resolve();
+            };
+            // Listen on the full overlay for easier mobile tap
+            this._overlay?.addEventListener('click', handler);
+        });
+    }
+    // ─── Transition ────────────────────────────────────────
+    async transitionToGame() {
+        // Fade out the HTML overlay
+        if (this._overlay) {
+            this._overlay.classList.add('ge-fade-out');
+            await new Promise((resolve) => {
+                this._overlay.addEventListener('transitionend', () => resolve(), { once: true });
+                // Safety timeout
+                setTimeout(resolve, 600);
+            });
+        }
+        // Remove overlay
+        this.removeOverlay();
+        // Navigate to the target scene
+        await this._engine.scenes.goto(this._targetScene, this._targetData);
+    }
+}
+
+const PRELOADER_ID = '__ge-css-preloader__';
+/**
+ * Inline SVG logo with animated loader bar.
+ * The `#loader` path acts as the progress fill — animated via clipPath.
+ */
+const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" class="ge-logo-svg">
+  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#pl0)"/>
+  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#pl1)"/>
+  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#pl2)"/>
+  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#pl3)"/>
+  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#pl4)"/>
+  <!-- Loader fill with clip for progress animation -->
+  <clipPath id="ge-loader-clip">
+    <rect x="37" y="148" width="0" height="20" class="ge-clip-rect"/>
+  </clipPath>
+  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#pl5)" clip-path="url(#ge-loader-clip)"/>
+  <text x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.6)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5" class="ge-preloader-svg-text">Loading...</text>
+  <defs>
+    <linearGradient id="pl0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+  </defs>
+</svg>`;
+/**
+ * Creates a lightweight CSS-only preloader that appears instantly,
+ * BEFORE PixiJS/WebGL is initialized.
+ *
+ * Displays the Energy8 logo SVG with an animated loader bar.
+ */
+function createCSSPreloader(container, config) {
+    if (document.getElementById(PRELOADER_ID))
+        return;
+    const bgColor = typeof config?.backgroundColor === 'string'
+        ? config.backgroundColor
+        : typeof config?.backgroundColor === 'number'
+            ? `#${config.backgroundColor.toString(16).padStart(6, '0')}`
+            : '#0a0a1a';
+    const bgGradient = config?.backgroundGradient ?? `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+    const customHTML = config?.cssPreloaderHTML ?? '';
+    const el = document.createElement('div');
+    el.id = PRELOADER_ID;
+    el.innerHTML = customHTML || `
+    <div class="ge-preloader-content">
+      ${LOGO_SVG}
+    </div>
+  `;
+    const style = document.createElement('style');
+    style.textContent = `
+    #${PRELOADER_ID} {
+      position: absolute;
+      top: 0; left: 0;
+      width: 100%; height: 100%;
+      background: ${bgGradient};
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 10000;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      transition: opacity 0.4s ease-out;
+    }
+
+    #${PRELOADER_ID}.ge-preloader-hidden {
+      opacity: 0;
+      pointer-events: none;
+    }
+
+    .ge-preloader-content {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      width: 80%;
+      max-width: 700px;
+    }
+
+    .ge-logo-svg {
+      width: 100%;
+      height: auto;
+      filter: drop-shadow(0 0 30px rgba(121, 57, 194, 0.4));
+    }
+
+    /* Animate the loader clip-rect to shimmer while waiting */
+    .ge-clip-rect {
+      animation: ge-loader-fill 2s ease-in-out infinite;
+    }
+
+    @keyframes ge-loader-fill {
+      0%   { width: 0; }
+      50%  { width: 174; }
+      100% { width: 0; }
+    }
+
+    /* Animate the SVG text opacity */
+    .ge-preloader-svg-text {
+      animation: ge-pulse 1.5s ease-in-out infinite;
+    }
+
+    @keyframes ge-pulse {
+      0%, 100% { opacity: 0.4; }
+      50% { opacity: 1; }
+    }
+  `;
+    container.style.position = container.style.position || 'relative';
+    container.appendChild(style);
+    container.appendChild(el);
+}
+/**
+ * Remove the CSS preloader with a smooth fade-out transition.
+ */
+function removeCSSPreloader(container) {
+    const el = document.getElementById(PRELOADER_ID);
+    if (!el)
+        return;
+    el.classList.add('ge-preloader-hidden');
+    // Remove after transition
+    el.addEventListener('transitionend', () => {
+        el.remove();
+        // Also remove the style element
+        const styles = container.querySelectorAll('style');
+        for (const style of styles) {
+            if (style.textContent?.includes(PRELOADER_ID)) {
+                style.remove();
+            }
+        }
+    });
+}
+
+/**
+ * The main entry point for a game built on @energy8platform/game-engine.
+ *
+ * Orchestrates the full lifecycle:
+ * 1. Create PixiJS Application
+ * 2. Initialize SDK (or run offline)
+ * 3. Show CSS preloader → Canvas loading screen with progress bar
+ * 4. Load asset manifest
+ * 5. Transition to the first game scene
+ *
+ * @example
+ * ```ts
+ * import { GameApplication, ScaleMode } from '@energy8platform/game-engine';
+ * import { GameScene } from './scenes/GameScene';
+ *
+ * const game = new GameApplication({
+ *   container: '#game',
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   manifest: { bundles: [
+ *     { name: 'preload', assets: [{ alias: 'logo', src: 'logo.png' }] },
+ *     { name: 'game', assets: [{ alias: 'bg', src: 'background.png' }] },
+ *   ]},
+ *   loading: { tapToStart: true },
+ * });
+ *
+ * game.scenes.register('game', GameScene);
+ * await game.start('game');
+ * ```
+ */
+class GameApplication extends EventEmitter {
+    // ─── Public references ──────────────────────────────────
+    /** PixiJS Application instance */
+    app;
+    /** Scene manager */
+    scenes;
+    /** Asset manager */
+    assets;
+    /** Audio manager */
+    audio;
+    /** Viewport manager */
+    viewport;
+    /** SDK instance (null in offline mode) */
+    sdk = null;
+    /** Data received from SDK initialization */
+    initData = null;
+    /** Configuration */
+    config;
+    // ─── Private state ──────────────────────────────────────
+    _running = false;
+    _destroyed = false;
+    _container = null;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            designWidth: 1920,
+            designHeight: 1080,
+            scaleMode: ScaleMode.FIT,
+            orientation: Orientation.ANY,
+            debug: false,
+            ...config,
+        };
+        // Create SceneManager early so scenes can be registered before start()
+        this.scenes = new SceneManager();
+    }
+    // ─── Public getters ─────────────────────────────────────
+    /** Current game config from SDK (or null in offline mode) */
+    get gameConfig() {
+        return this.initData?.config ?? null;
+    }
+    /** Current session data */
+    get session() {
+        return this.initData?.session ?? null;
+    }
+    /** Current balance */
+    get balance() {
+        return this.sdk?.balance ?? 0;
+    }
+    /** Current currency */
+    get currency() {
+        return this.sdk?.currency ?? 'USD';
+    }
+    /** Whether the engine is running */
+    get isRunning() {
+        return this._running;
+    }
+    // ─── Lifecycle ──────────────────────────────────────────
+    /**
+     * Start the game engine. This is the main entry point.
+     *
+     * @param firstScene - Key of the first scene to show after loading (must be registered)
+     * @param sceneData - Optional data to pass to the first scene's onEnter
+     */
+    async start(firstScene, sceneData) {
+        if (this._running) {
+            console.warn('[GameEngine] Already running');
+            return;
+        }
+        try {
+            // 1. Resolve container element
+            this._container = this.resolveContainer();
+            // 2. Show CSS preloader immediately (before PixiJS)
+            createCSSPreloader(this._container, this.config.loading);
+            // 3. Initialize PixiJS
+            await this.initPixi();
+            // 4. Initialize SDK (if enabled)
+            await this.initSDK();
+            // 5. Merge design dimensions from SDK config
+            this.applySDKConfig();
+            // 6. Initialize sub-systems
+            this.initSubSystems();
+            this.emit('initialized', undefined);
+            // 7. Remove CSS preloader, show Canvas loading screen
+            removeCSSPreloader(this._container);
+            // 8. Load assets with loading screen
+            await this.loadAssets(firstScene, sceneData);
+            // 9. Start the game loop
+            this._running = true;
+            this.emit('started', undefined);
+        }
+        catch (err) {
+            console.error('[GameEngine] Failed to start:', err);
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+    }
+    /**
+     * Destroy the engine and free all resources.
+     */
+    destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._running = false;
+        this.scenes?.destroy();
+        this.audio?.destroy();
+        this.viewport?.destroy();
+        this.sdk?.destroy();
+        this.app?.destroy(true, { children: true, texture: true });
+        this.removeAllListeners();
+        this.emit('destroyed', undefined);
+    }
+    // ─── Private initialization steps ──────────────────────
+    resolveContainer() {
+        if (typeof this.config.container === 'string') {
+            const el = document.querySelector(this.config.container);
+            if (!el)
+                throw new Error(`[GameEngine] Container "${this.config.container}" not found`);
+            return el;
+        }
+        return this.config.container ?? document.body;
+    }
+    async initPixi() {
+        this.app = new Application();
+        const pixiOpts = {
+            background: typeof this.config.loading?.backgroundColor === 'number'
+                ? this.config.loading.backgroundColor
+                : 0x000000,
+            antialias: true,
+            resolution: Math.min(window.devicePixelRatio, 2),
+            autoDensity: true,
+            ...this.config.pixi,
+        };
+        await this.app.init(pixiOpts);
+        // Append canvas to container
+        this._container.appendChild(this.app.canvas);
+        // Set canvas style
+        this.app.canvas.style.display = 'block';
+        this.app.canvas.style.width = '100%';
+        this.app.canvas.style.height = '100%';
+    }
+    async initSDK() {
+        if (this.config.sdk === false) {
+            // Offline / development mode — no SDK
+            this.initData = null;
+            return;
+        }
+        const sdkOpts = typeof this.config.sdk === 'object' ? this.config.sdk : {};
+        this.sdk = new CasinoGameSDK(sdkOpts);
+        // Perform the handshake
+        this.initData = await this.sdk.ready();
+        // Forward SDK events
+        this.sdk.on('error', (err) => {
+            this.emit('error', err);
+        });
+    }
+    applySDKConfig() {
+        // If SDK provides viewport dimensions, use them as design reference
+        if (this.initData?.config?.viewport) {
+            const vp = this.initData.config.viewport;
+            if (!this.config.designWidth)
+                this.config.designWidth = vp.width;
+            if (!this.config.designHeight)
+                this.config.designHeight = vp.height;
+        }
+    }
+    initSubSystems() {
+        // Asset Manager
+        const basePath = this.initData?.assetsUrl ?? '';
+        this.assets = new AssetManager(basePath, this.config.manifest);
+        // Audio Manager
+        this.audio = new AudioManager(this.config.audio);
+        // Viewport Manager
+        this.viewport = new ViewportManager(this.app, this._container, {
+            designWidth: this.config.designWidth,
+            designHeight: this.config.designHeight,
+            scaleMode: this.config.scaleMode,
+            orientation: this.config.orientation,
+        });
+        // Wire SceneManager to the PixiJS stage
+        this.scenes.setRoot(this.app.stage);
+        // Wire viewport resize → scene manager
+        this.viewport.on('resize', ({ width, height }) => {
+            this.scenes.resize(width, height);
+            this.emit('resize', { width, height });
+        });
+        this.viewport.on('orientationChange', (orientation) => {
+            this.emit('orientationChange', orientation);
+        });
+        // Connect ticker → scene updates
+        this.app.ticker.add((ticker) => {
+            // Always update scenes (loading screen needs onUpdate before _running=true)
+            this.scenes.update(ticker.deltaTime / 60); // convert to seconds
+        });
+        // Trigger initial resize
+        this.viewport.refresh();
+    }
+    async loadAssets(firstScene, sceneData) {
+        // Register built-in loading scene
+        this.scenes.register('__loading__', LoadingScene);
+        // Enter loading scene
+        await this.scenes.goto('__loading__', {
+            engine: this,
+            targetScene: firstScene,
+            targetData: sceneData,
+        });
+    }
+}
+
+export { EventEmitter, GameApplication, Scene, SceneManager };
+//# sourceMappingURL=core.esm.js.map