@energy8platform/game-engine 0.2.0 → 0.3.0

package/dist/core.cjs.js

@@ -32,6 +32,9 @@ var TransitionType;
 /**
  * Minimal typed event emitter.
  * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 class EventEmitter {
@@ -54,7 +57,8 @@ class EventEmitter {
         this.listeners.get(event)?.delete(handler);
         return this;
     }
-    emit(event, data) {
+    emit(...args) {
+        const [event, data] = args;
         const handlers = this.listeners.get(event);
         if (handlers) {
             for (const handler of handlers) {
@@ -157,9 +161,20 @@ class Tween {
     }
     /**
      * Wait for a given duration (useful in timelines).
+     * Uses PixiJS Ticker for consistent timing with other tweens.
      */
     static delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            const onTick = (ticker) => {
+                elapsed += ticker.deltaMS;
+                if (elapsed >= ms) {
+                    pixi_js.Ticker.shared.remove(onTick);
+                    resolve();
+                }
+            };
+            pixi_js.Ticker.shared.add(onTick);
+        });
     }
     /**
      * Kill all tweens on a target.
@@ -186,6 +201,20 @@ class Tween {
     static get activeTweens() {
         return Tween._tweens.length;
     }
+    /**
+     * Reset the tween system — kill all tweens and remove the ticker.
+     * Useful for cleanup between game instances, tests, or hot-reload.
+     */
+    static reset() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+        if (Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    }
     // ─── Internal ──────────────────────────────────────────
     static ensureTicker() {
         if (Tween._tickerAdded)
@@ -388,8 +417,9 @@ class SceneManager extends EventEmitter {
         }
         // Transition in
         await this.transitionIn(scene.container, transition);
-        await scene.onEnter?.(data);
+        // Push to stack BEFORE onEnter so currentKey is correct during initialization
         this.stack.push({ scene, key });
+        await scene.onEnter?.(data);
         this._transitioning = false;
     }
     async popInternal(showTransition, transition) {
@@ -688,26 +718,51 @@ class AudioManager {
         if (!this._initialized || !this._soundModule)
             return;
         const { sound } = this._soundModule;
-        // Stop current music
-        if (this._currentMusic) {
+        // Stop current music with fade-out, start new music with fade-in
+        if (this._currentMusic && fadeDuration > 0) {
+            const prevAlias = this._currentMusic;
+            this._currentMusic = alias;
+            if (this._globalMuted || this._categories.music.muted)
+                return;
+            // Fade out the previous track
+            this.fadeVolume(prevAlias, this._categories.music.volume, 0, fadeDuration, () => {
+                try {
+                    sound.stop(prevAlias);
+                }
+                catch { /* ignore */ }
+            });
+            // Start new track at zero volume, fade in
             try {
-                sound.stop(this._currentMusic);
+                sound.play(alias, {
+                    volume: 0,
+                    loop: true,
+                });
+                this.fadeVolume(alias, 0, this._categories.music.volume, fadeDuration);
             }
-            catch {
-                // ignore
+            catch (e) {
+                console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
             }
         }
-        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);
+        else {
+            // No crossfade — instant switch
+            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);
+            }
         }
     }
     /**
@@ -849,6 +904,31 @@ class AudioManager {
         this._initialized = false;
     }
     // ─── Private ───────────────────────────────────────────
+    /**
+     * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
+     */
+    fadeVolume(alias, fromVol, toVol, durationMs, onComplete) {
+        if (!this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        const startTime = Date.now();
+        const tick = () => {
+            const elapsed = Date.now() - startTime;
+            const t = Math.min(elapsed / durationMs, 1);
+            const vol = fromVol + (toVol - fromVol) * t;
+            try {
+                sound.volume(alias, vol);
+            }
+            catch { /* ignore */ }
+            if (t < 1) {
+                requestAnimationFrame(tick);
+            }
+            else {
+                onComplete?.();
+            }
+        };
+        requestAnimationFrame(tick);
+    }
     applyVolumes() {
         if (!this._soundModule)
             return;
@@ -953,6 +1033,10 @@ class InputManager extends EventEmitter {
     _locked = false;
     _keysDown = new Set();
     _destroyed = false;
+    // Viewport transform (set by ViewportManager via setViewportTransform)
+    _viewportScale = 1;
+    _viewportOffsetX = 0;
+    _viewportOffsetY = 0;
     // Gesture tracking
     _pointerStart = null;
     _swipeThreshold = 50; // minimum distance in px
@@ -979,6 +1063,25 @@ class InputManager extends EventEmitter {
     isKeyDown(key) {
         return this._keysDown.has(key.toLowerCase());
     }
+    /**
+     * Update the viewport transform used for DOM→world coordinate mapping.
+     * Called automatically by GameApplication when ViewportManager emits resize.
+     */
+    setViewportTransform(scale, offsetX, offsetY) {
+        this._viewportScale = scale;
+        this._viewportOffsetX = offsetX;
+        this._viewportOffsetY = offsetY;
+    }
+    /**
+     * Convert a DOM canvas position to game-world coordinates,
+     * accounting for viewport scaling and offset.
+     */
+    getWorldPosition(canvasX, canvasY) {
+        return {
+            x: (canvasX - this._viewportOffsetX) / this._viewportScale,
+            y: (canvasY - this._viewportOffsetY) / this._viewportScale,
+        };
+    }
     /** Destroy the input manager */
     destroy() {
         this._destroyed = true;
@@ -1234,6 +1337,8 @@ class ViewportManager extends EventEmitter {
         this._destroyed = true;
         this._resizeObserver?.disconnect();
         this._resizeObserver = null;
+        // Remove fallback window resize listener if it was used
+        window.removeEventListener('resize', this.onWindowResize);
         if (this._resizeTimeout !== null) {
             clearTimeout(this._resizeTimeout);
         }
@@ -1297,45 +1402,87 @@ class Scene {
 }
 
 /**
- * Inline SVG logo with a loader bar (clip-animated for progress).
- * The clipPath rect width is set to 0 initially, expanded as loading progresses.
+ * Shared Energy8 SVG logo with an embedded loader bar.
+ *
+ * The loader bar fill is controlled via a `<clipPath>` whose `<rect>` width
+ * is animatable. Different consumers customise gradient IDs and the clip
+ * element's ID/class to avoid collisions when both CSSPreloader and
+ * LoadingScene appear in the same DOM.
  */
-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">
+/** SVG path data for the Energy8 wordmark — reused across loaders */
+const WORDMARK_PATHS = `
+  <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(#GID0)"/>
+  <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(#GID1)"/>
+  <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(#GID2)"/>
+  <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(#GID3)"/>
+  <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(#GID4)"/>`;
+/** Gradient definitions template (gradient IDs are replaced per-consumer) */
+const GRADIENT_DEFS = `
+    <linearGradient id="GID0" 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">
+    <linearGradient id="GID1" 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">
+    <linearGradient id="GID2" 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">
+    <linearGradient id="GID3" 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">
+    <linearGradient id="GID4" 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">
+    <linearGradient id="GID5" 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>
+    </linearGradient>`;
+/** Max width of the loader bar in SVG units */
+const LOADER_BAR_MAX_WIDTH = 174;
+/**
+ * Build the Energy8 SVG logo with a loader bar, using unique IDs.
+ *
+ * @param opts - Configuration to avoid element ID collisions
+ * @returns SVG markup string
+ */
+function buildLogoSVG(opts) {
+    const { idPrefix, svgClass, svgStyle, clipRectClass, clipRectId, textId, textContent, textClass } = opts;
+    // Replace gradient ID placeholders with prefixed versions
+    const paths = WORDMARK_PATHS.replace(/GID(\d)/g, `${idPrefix}$1`);
+    const defs = GRADIENT_DEFS.replace(/GID(\d)/g, `${idPrefix}$1`);
+    const clipId = `${idPrefix}-loader-clip`;
+    const fillGradientId = `${idPrefix}5`;
+    const classAttr = svgClass ? ` class="${svgClass}"` : '';
+    const styleAttr = svgStyle ? ` style="${svgStyle}"` : '';
+    const rectClassAttr = clipRectClass ? ` class="${clipRectClass}"` : '';
+    const rectIdAttr = clipRectId ? ` id="${clipRectId}"` : '';
+    const txtIdAttr = textId ? ` id="${textId}"` : '';
+    const txtClassAttr = textClass ? ` class="${textClass}"` : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none"${classAttr}${styleAttr}>
+${paths}
+  <clipPath id="${clipId}">
+    <rect${rectIdAttr} x="37" y="148" width="0" height="20"${rectClassAttr}/>
+  </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(#${fillGradientId})" clip-path="url(#${clipId})"/>
+  <text${txtIdAttr} 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"${txtClassAttr}>${textContent ?? 'Loading...'}</text>
+  <defs>
+${defs}
   </defs>
 </svg>`;
 }
-/** Max width of the loader bar in SVG units */
-const LOADER_BAR_MAX_WIDTH = 174;
+
+/**
+ * Build the loading scene variant of the logo SVG.
+ * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
+ */
+function buildLoadingLogoSVG() {
+    return buildLogoSVG({
+        idPrefix: 'ls',
+        svgStyle: 'width:100%;height:auto;',
+        clipRectId: 'ge-loader-rect',
+        textId: 'ge-loader-pct',
+        textContent: '0%',
+    });
+}
 /**
  * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
  *
@@ -1445,7 +1592,7 @@ class LoadingScene extends Scene {
         this._overlay.id = '__ge-loading-overlay__';
         this._overlay.innerHTML = `
       <div class="ge-loading-content">
-        ${buildLogoSVG()}
+        ${buildLoadingLogoSVG()}
       </div>
     `;
         const style = document.createElement('style');
@@ -1583,8 +1730,11 @@ class LoadingScene extends Scene {
         }
         // Remove overlay
         this.removeOverlay();
-        // Navigate to the target scene
-        await this._engine.scenes.goto(this._targetScene, this._targetData);
+        // Navigate to the target scene, always passing the engine reference
+        await this._engine.scenes.goto(this._targetScene, {
+            engine: this._engine,
+            ...(this._targetData && typeof this._targetData === 'object' ? this._targetData : { data: this._targetData }),
+        });
     }
 }
 
@@ -1593,39 +1743,12 @@ 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>`;
+const LOGO_SVG = buildLogoSVG({
+    idPrefix: 'pl',
+    svgClass: 'ge-logo-svg',
+    clipRectClass: 'ge-clip-rect',
+    textClass: 'ge-preloader-svg-text',
+});
 /**
  * Creates a lightweight CSS-only preloader that appears instantly,
  * BEFORE PixiJS/WebGL is initialized.
@@ -1729,6 +1852,96 @@ function removeCSSPreloader(container) {
     });
 }
 
+/**
+ * FPS overlay for debugging performance.
+ *
+ * Shows FPS, frame time, and draw call count in the corner of the screen.
+ *
+ * @example
+ * ```ts
+ * const fps = new FPSOverlay(app);
+ * fps.show();
+ * ```
+ */
+class FPSOverlay {
+    _app;
+    _container;
+    _fpsText;
+    _visible = false;
+    _samples = [];
+    _maxSamples = 60;
+    _lastUpdate = 0;
+    _tickFn = null;
+    constructor(app) {
+        this._app = app;
+        this._container = new pixi_js.Container();
+        this._container.label = 'FPSOverlay';
+        this._container.zIndex = 99999;
+        this._fpsText = new pixi_js.Text({
+            text: 'FPS: --',
+            style: {
+                fontFamily: 'monospace',
+                fontSize: 14,
+                fill: 0x00ff00,
+                stroke: { color: 0x000000, width: 2 },
+            },
+        });
+        this._fpsText.x = 8;
+        this._fpsText.y = 8;
+        this._container.addChild(this._fpsText);
+    }
+    /** Show the FPS overlay */
+    show() {
+        if (this._visible)
+            return;
+        this._visible = true;
+        this._app.stage.addChild(this._container);
+        this._tickFn = (ticker) => {
+            this._samples.push(ticker.FPS);
+            if (this._samples.length > this._maxSamples) {
+                this._samples.shift();
+            }
+            // Update display every ~500ms
+            const now = Date.now();
+            if (now - this._lastUpdate > 500) {
+                const avg = this._samples.reduce((a, b) => a + b, 0) / this._samples.length;
+                const min = Math.min(...this._samples);
+                this._fpsText.text = [
+                    `FPS: ${Math.round(avg)} (min: ${Math.round(min)})`,
+                    `Frame: ${ticker.deltaMS.toFixed(1)}ms`,
+                ].join('\n');
+                this._lastUpdate = now;
+            }
+        };
+        this._app.ticker.add(this._tickFn);
+    }
+    /** Hide the FPS overlay */
+    hide() {
+        if (!this._visible)
+            return;
+        this._visible = false;
+        this._container.removeFromParent();
+        if (this._tickFn) {
+            this._app.ticker.remove(this._tickFn);
+            this._tickFn = null;
+        }
+    }
+    /** Toggle visibility */
+    toggle() {
+        if (this._visible) {
+            this.hide();
+        }
+        else {
+            this.show();
+        }
+    }
+    /** Destroy the overlay */
+    destroy() {
+        this.hide();
+        this._container.destroy({ children: true });
+    }
+}
+
 /**
  * The main entry point for a game built on @energy8platform/game-engine.
  *
@@ -1776,6 +1989,8 @@ class GameApplication extends EventEmitter {
     viewport;
     /** SDK instance (null in offline mode) */
     sdk = null;
+    /** FPS overlay instance (only when debug: true) */
+    fpsOverlay = null;
     /** Data received from SDK initialization */
     initData = null;
     /** Configuration */
@@ -1843,14 +2058,15 @@ class GameApplication extends EventEmitter {
             this.applySDKConfig();
             // 6. Initialize sub-systems
             this.initSubSystems();
-            this.emit('initialized', undefined);
+            this.emit('initialized');
             // 7. Remove CSS preloader, show Canvas loading screen
             removeCSSPreloader(this._container);
             // 8. Load assets with loading screen
             await this.loadAssets(firstScene, sceneData);
+            this.emit('loaded');
             // 9. Start the game loop
             this._running = true;
-            this.emit('started', undefined);
+            this.emit('started');
         }
         catch (err) {
             console.error('[GameEngine] Failed to start:', err);
@@ -1872,8 +2088,8 @@ class GameApplication extends EventEmitter {
         this.viewport?.destroy();
         this.sdk?.destroy();
         this.app?.destroy(true, { children: true, texture: true });
+        this.emit('destroyed');
         this.removeAllListeners();
-        this.emit('destroyed', undefined);
     }
     // ─── Private initialization steps ──────────────────────
     resolveContainer() {
@@ -1946,14 +2162,19 @@ class GameApplication extends EventEmitter {
         });
         // Wire SceneManager to the PixiJS stage
         this.scenes.setRoot(this.app.stage);
-        // Wire viewport resize → scene manager
-        this.viewport.on('resize', ({ width, height }) => {
+        // Wire viewport resize → scene manager + input manager
+        this.viewport.on('resize', ({ width, height, scale }) => {
             this.scenes.resize(width, height);
+            this.input.setViewportTransform(scale, this.app.stage.x, this.app.stage.y);
             this.emit('resize', { width, height });
         });
         this.viewport.on('orientationChange', (orientation) => {
             this.emit('orientationChange', orientation);
         });
+        // Wire scene changes → engine event
+        this.scenes.on('change', ({ from, to }) => {
+            this.emit('sceneChange', { from, to });
+        });
         // Connect ticker → scene updates
         this.app.ticker.add((ticker) => {
             // Always update scenes (loading screen needs onUpdate before _running=true)
@@ -1961,6 +2182,11 @@ class GameApplication extends EventEmitter {
         });
         // Trigger initial resize
         this.viewport.refresh();
+        // Enable FPS overlay in debug mode
+        if (this.config.debug) {
+            this.fpsOverlay = new FPSOverlay(this.app);
+            this.fpsOverlay.show();
+        }
     }
     async loadAssets(firstScene, sceneData) {
         // Register built-in loading scene