@energy8platform/game-engine 0.2.0 → 0.3.0

package/dist/vite.esm.js

@@ -1,63 +1,68 @@
+// ─── DevBridge Plugin ────────────────────────────────────
 /**
- * Vite plugin that injects the DevBridge mock host in development mode.
- *
- * In dev mode, wraps the game page to simulate the casino host environment,
- * allowing SDK communication to work without a real backend.
+ * Vite plugin that auto-injects the DevBridge script into the
+ * HTML during development, so the game can communicate with a
+ * mock casino host without manual setup.
  */
-const VIRTUAL_DEV_BRIDGE_ID = 'virtual:game-engine-dev-bridge';
-const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_DEV_BRIDGE_ID;
-function gameEngineDevPlugin(options = {}) {
+const VIRTUAL_ID = '/@dev-bridge-entry.js';
+function devBridgePlugin(configPath) {
+    let entrySrc = '';
+    let resolvedConfigPath = configPath;
     return {
-        name: 'game-engine-dev',
-        apply: 'serve',
+        name: 'game-engine:dev-bridge',
+        apply: 'serve', // dev only
+        enforce: 'pre',
+        configResolved(config) {
+            // Resolve relative config path against Vite root so the virtual
+            // module can import it with an absolute path.
+            if (configPath.startsWith('.')) {
+                resolvedConfigPath = config.root + '/' + configPath.replace(/^\.\//, '');
+            }
+        },
         resolveId(id) {
-            if (id === VIRTUAL_DEV_BRIDGE_ID)
-                return RESOLVED_VIRTUAL_ID;
+            if (id === VIRTUAL_ID)
+                return id;
         },
         load(id) {
-            if (id === RESOLVED_VIRTUAL_ID) {
-                // This module goes through Vite's transform pipeline,
-                // so bare specifiers like '@energy8platform/game-engine/debug' resolve correctly.
+            if (id === VIRTUAL_ID) {
+                // This goes through Vite's pipeline so bare imports are resolved
                 return `
 import { DevBridge } from '@energy8platform/game-engine/debug';
 
-async function initDevBridge() {
-  let config = {};
-  try {
-    const mod = await import('/dev.config.ts');
-    config = mod.default || mod.devBridgeConfig || {};
-  } catch {
-    // No dev config — use defaults
-  }
-
-  const bridge = new DevBridge(config);
-  bridge.start();
-  window.__devBridge = bridge;
-  console.log('[GameEngine] DevBridge started in development mode');
+try {
+  const mod = await import('${resolvedConfigPath}');
+  const config = mod.default ?? mod.config ?? mod;
+  new DevBridge(config).start();
+} catch (e) {
+  console.warn('[DevBridge] Failed to load config:', e);
 }
 
-initDevBridge();
+await import('${entrySrc}');
 `;
             }
         },
         transformIndexHtml(html) {
-            if (options.devBridge === false)
+            // Find the app's entry module script (skip Vite internal /@... scripts)
+            const scriptRegex = /<script\s+type="module"\s+src="((?!\/@)[^"]+)"\s*>\s*<\/script>/;
+            const match = html.match(scriptRegex);
+            if (!match) {
+                console.warn('[DevBridge] Could not find entry module script in index.html');
                 return html;
-            // Inject a script that imports the virtual module — Vite resolves it properly
-            const devScript = `<script type="module" src="/${VIRTUAL_DEV_BRIDGE_ID}"></script>`;
-            return html.replace('</head>', `${devScript}\n</head>`);
+            }
+            entrySrc = match[1];
+            return html.replace(match[0], `<script type="module" src="${VIRTUAL_ID}"></script>`);
         },
     };
 }
+// ─── defineGameConfig ────────────────────────────────────
 /**
- * Create a pre-configured Vite config for game projects.
+ * Define a Vite configuration tailored for Energy8 casino games.
  *
- * Includes:
- * - PixiJS optimization (exclude from dep optimization)
- * - DevBridge injection in dev mode
- * - HTML minification
- * - Gzip-friendly output
- * - Configurable base path for S3/CDN deploy
+ * Merges sensible defaults for iGaming projects:
+ * - Build target: ES2020+
+ * - Asset inlining threshold: 8KB
+ * - Source maps for dev, none for prod
+ * - Optional DevBridge auto-injection in dev mode
  *
  * @example
  * ```ts
@@ -65,58 +70,51 @@ initDevBridge();
  * import { defineGameConfig } from '@energy8platform/game-engine/vite';
  *
  * export default defineGameConfig({
- *   base: '/games/my-slot/',
+ *   base: '/',
  *   devBridge: true,
  * });
  * ```
  */
 function defineGameConfig(config = {}) {
-    const assetExtensions = config.assetExtensions ?? [
-        'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'svg',
-        'mp3', 'ogg', 'wav', 'webm',
-        'json', 'atlas', 'skel',
-        'fnt', 'ttf', 'otf', 'woff', 'woff2',
-        'mp4', 'm4v',
-    ];
+    const plugins = [];
+    if (config.devBridge) {
+        const configPath = config.devBridgeConfig ?? './dev.config';
+        plugins.push(devBridgePlugin(configPath));
+    }
+    const userVite = config.vite ?? {};
     return {
         base: config.base ?? '/',
         plugins: [
-            gameEngineDevPlugin({ devBridge: config.devBridge ?? true }),
-            ...(config.vite?.plugins ?? []),
+            ...plugins,
+            ...(userVite.plugins ?? []),
         ],
         build: {
-            outDir: config.outDir ?? 'dist',
-            target: 'es2022',
-            minify: 'terser',
+            target: 'es2020',
+            assetsInlineLimit: 8192,
             sourcemap: false,
-            assetsInlineLimit: 4096,
             rollupOptions: {
                 output: {
-                    assetFileNames: 'assets/[name]-[hash][extname]',
-                    chunkFileNames: 'js/[name]-[hash].js',
-                    entryFileNames: 'js/[name]-[hash].js',
+                    manualChunks: {
+                        pixi: ['pixi.js'],
+                    },
                 },
             },
-            ...(config.vite?.build ?? {}),
+            ...userVite.build,
         },
-        optimizeDeps: {
-            // Pre-bundle libs for fast dev startup
-            include: ['pixi.js'],
-            exclude: ['@esotericsoftware/spine-pixi-v8'],
-        },
-        assetsInclude: assetExtensions.map((ext) => `**/*.${ext}`),
         server: {
             port: 3000,
             open: true,
-            ...(config.vite?.server ?? {}),
+            ...userVite.server,
         },
         resolve: {
-            ...(config.vite?.resolve ?? {}),
+            ...userVite.resolve,
+        },
+        optimizeDeps: {
+            include: ['pixi.js'],
+            ...userVite.optimizeDeps,
         },
-        // Spread any additional user overrides
-        ...Object.fromEntries(Object.entries(config.vite ?? {}).filter(([key]) => !['plugins', 'build', 'server', 'resolve'].includes(key))),
     };
 }
 
-export { defineGameConfig, gameEngineDevPlugin };
+export { defineGameConfig };
 //# sourceMappingURL=vite.esm.js.map

package/dist/vite.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite.esm.js","sources":["../src/vite/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"vite.esm.js","sources":["../src/vite/index.ts"],"sourcesContent":[null],"names":[],"mappings":"AAkBA;AAEA;;;;AAIG;AACH,MAAM,UAAU,GAAG,uBAAuB;AAE1C,SAAS,eAAe,CAAC,UAAkB,EAAA;IACzC,IAAI,QAAQ,GAAG,EAAE;IACjB,IAAI,kBAAkB,GAAG,UAAU;IAEnC,OAAO;AACL,QAAA,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,OAAO;AACd,QAAA,OAAO,EAAE,KAAK;AAEd,QAAA,cAAc,CAAC,MAAM,EAAA;;;AAGnB,YAAA,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;AAC9B,gBAAA,kBAAkB,GAAG,MAAM,CAAC,IAAI,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1E;QACF,CAAC;AAED,QAAA,SAAS,CAAC,EAAE,EAAA;YACV,IAAI,EAAE,KAAK,UAAU;AAAE,gBAAA,OAAO,EAAE;QAClC,CAAC;AAED,QAAA,IAAI,CAAC,EAAE,EAAA;AACL,YAAA,IAAI,EAAE,KAAK,UAAU,EAAE;;gBAErB,OAAO;;;;8BAIe,kBAAkB,CAAA;;;;;;;gBAOhC,QAAQ,CAAA;CACvB;YACK;QACF,CAAC;AAED,QAAA,kBAAkB,CAAC,IAAI,EAAA;;YAErB,MAAM,WAAW,GAAG,iEAAiE;YACrF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YAErC,IAAI,CAAC,KAAK,EAAE;AACV,gBAAA,OAAO,CAAC,IAAI,CAAC,8DAA8D,CAAC;AAC5E,gBAAA,OAAO,IAAI;YACb;AAEA,YAAA,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC;AACnB,YAAA,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA,2BAAA,EAA8B,UAAU,CAAA,WAAA,CAAa,CAAC;QACtF,CAAC;KACF;AACH;AAEA;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,gBAAgB,CAAC,MAAA,GAAqB,EAAE,EAAA;IACtD,MAAM,OAAO,GAAa,EAAE;AAE5B,IAAA,IAAI,MAAM,CAAC,SAAS,EAAE;AACpB,QAAA,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,IAAI,cAAc;QAC3D,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;IAC3C;AAEA,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE;IAElC,OAAO;AACL,QAAA,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,GAAG;AAExB,QAAA,OAAO,EAAE;AACP,YAAA,GAAG,OAAO;AACV,YAAA,IAAK,QAAQ,CAAC,OAAoB,IAAI,EAAE,CAAC;AAC1C,SAAA;AAED,QAAA,KAAK,EAAE;AACL,YAAA,MAAM,EAAE,QAAQ;AAChB,YAAA,iBAAiB,EAAE,IAAI;AACvB,YAAA,SAAS,EAAE,KAAK;AAChB,YAAA,aAAa,EAAE;AACb,gBAAA,MAAM,EAAE;AACN,oBAAA,YAAY,EAAE;wBACZ,IAAI,EAAE,CAAC,SAAS,CAAC;AAClB,qBAAA;AACF,iBAAA;AACF,aAAA;YACD,GAAG,QAAQ,CAAC,KAAK;AAClB,SAAA;AAED,QAAA,MAAM,EAAE;AACN,YAAA,IAAI,EAAE,IAAI;AACV,YAAA,IAAI,EAAE,IAAI;YACV,GAAG,QAAQ,CAAC,MAAM;AACnB,SAAA;AAED,QAAA,OAAO,EAAE;YACP,GAAG,QAAQ,CAAC,OAAO;AACpB,SAAA;AAED,QAAA,YAAY,EAAE;YACZ,OAAO,EAAE,CAAC,SAAS,CAAC;YACpB,GAAG,QAAQ,CAAC,YAAY;AACzB,SAAA;KACF;AACH;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -50,8 +50,7 @@
   },
   "files": [
     "dist",
-    "src",
-    "loading.css"
+    "src"
   ],
   "scripts": {
     "build": "rollup -c rollup.config.mjs",
@@ -65,7 +64,7 @@
   },
   "peerDependencies": {
     "pixi.js": "^8.16.0",
-    "@energy8platform/game-sdk": "^2.5.0"
+    "@energy8platform/game-sdk": "^2.6.1"
   },
   "peerDependenciesMeta": {
     "@esotericsoftware/spine-pixi-v8": {
@@ -76,7 +75,7 @@
     }
   },
   "devDependencies": {
-    "@energy8platform/game-sdk": "file:../energy8-platform-game-sdk",
+    "@energy8platform/game-sdk": "^2.6.1",
     "@esotericsoftware/spine-pixi-v8": "~4.2.0",
     "@pixi/sound": "^6.0.0",
     "@rollup/plugin-typescript": "^12.1.0",

package/src/animation/SpriteAnimation.ts

@@ -0,0 +1,210 @@
+import { AnimatedSprite, Texture, Spritesheet } from 'pixi.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface SpriteAnimationConfig {
+  /** Frames per second (default: 24) */
+  fps?: number;
+  /** Whether to loop (default: true) */
+  loop?: boolean;
+  /** Start playing immediately (default: true) */
+  autoPlay?: boolean;
+  /** Callback when animation completes (non-looping) */
+  onComplete?: () => void;
+  /** Anchor point (default: 0.5 = center) */
+  anchor?: number | { x: number; y: number };
+}
+
+/**
+ * Helper for creating frame-based animations from spritesheets.
+ *
+ * Wraps PixiJS `AnimatedSprite` with a convenient API for
+ * common iGaming effects: coin showers, symbol animations,
+ * sparkle trails, win celebrations.
+ *
+ * Cheaper than Spine for simple frame sequences.
+ *
+ * @example
+ * ```ts
+ * // From an array of textures
+ * const coinAnim = SpriteAnimation.create(coinTextures, {
+ *   fps: 30,
+ *   loop: true,
+ * });
+ * scene.addChild(coinAnim);
+ *
+ * // From a spritesheet with a naming pattern
+ * const sheet = Assets.get('effects');
+ * const sparkle = SpriteAnimation.fromSpritesheet(sheet, 'sparkle_');
+ * sparkle.play();
+ *
+ * // From a numbered range
+ * const explosion = SpriteAnimation.fromRange(sheet, 'explosion_{i}', 0, 24, {
+ *   fps: 60,
+ *   loop: false,
+ *   onComplete: () => explosion.destroy(),
+ * });
+ * ```
+ */
+export class SpriteAnimation {
+  /**
+   * Create an animated sprite from an array of textures.
+   *
+   * @param textures - Array of PixiJS Textures
+   * @param config - Animation options
+   * @returns Configured AnimatedSprite
+   */
+  static create(textures: Texture[], config: SpriteAnimationConfig = {}): AnimatedSprite {
+    const sprite = new AnimatedSprite(textures);
+
+    // Configure
+    sprite.animationSpeed = (config.fps ?? 24) / 60; // PixiJS uses speed relative to 60fps ticker
+    sprite.loop = config.loop ?? true;
+
+    // Anchor
+    if (config.anchor !== undefined) {
+      if (typeof config.anchor === 'number') {
+        sprite.anchor.set(config.anchor);
+      } else {
+        sprite.anchor.set(config.anchor.x, config.anchor.y);
+      }
+    } else {
+      sprite.anchor.set(0.5);
+    }
+
+    // Complete callback
+    if (config.onComplete) {
+      sprite.onComplete = config.onComplete;
+    }
+
+    // Auto-play
+    if (config.autoPlay !== false) {
+      sprite.play();
+    }
+
+    return sprite;
+  }
+
+  /**
+   * Create an animated sprite from a spritesheet using a name prefix.
+   *
+   * Collects all textures whose keys start with `prefix`, sorted alphabetically.
+   *
+   * @param sheet - PixiJS Spritesheet instance
+   * @param prefix - Texture name prefix (e.g., 'coin_')
+   * @param config - Animation options
+   * @returns Configured AnimatedSprite
+   */
+  static fromSpritesheet(
+    sheet: Spritesheet,
+    prefix: string,
+    config: SpriteAnimationConfig = {},
+  ): AnimatedSprite {
+    const textures = SpriteAnimation.getTexturesByPrefix(sheet, prefix);
+
+    if (textures.length === 0) {
+      console.warn(`[SpriteAnimation] No textures found with prefix "${prefix}"`);
+    }
+
+    return SpriteAnimation.create(textures, config);
+  }
+
+  /**
+   * Create an animated sprite from a numbered range of frames.
+   *
+   * The `pattern` string should contain `{i}` as a placeholder for the frame number.
+   * Numbers are zero-padded to match the length of `start`.
+   *
+   * @param sheet - PixiJS Spritesheet instance
+   * @param pattern - Frame name pattern, e.g. 'explosion_{i}'
+   * @param start - Start frame index (inclusive)
+   * @param end - End frame index (inclusive)
+   * @param config - Animation options
+   * @returns Configured AnimatedSprite
+   */
+  static fromRange(
+    sheet: Spritesheet,
+    pattern: string,
+    start: number,
+    end: number,
+    config: SpriteAnimationConfig = {},
+  ): AnimatedSprite {
+    const textures: Texture[] = [];
+    const padLength = String(end).length;
+
+    for (let i = start; i <= end; i++) {
+      const name = pattern.replace('{i}', String(i).padStart(padLength, '0'));
+      const texture = sheet.textures[name];
+
+      if (texture) {
+        textures.push(texture);
+      } else {
+        console.warn(`[SpriteAnimation] Missing frame: "${name}"`);
+      }
+    }
+
+    if (textures.length === 0) {
+      console.warn(`[SpriteAnimation] No textures found for pattern "${pattern}" [${start}..${end}]`);
+    }
+
+    return SpriteAnimation.create(textures, config);
+  }
+
+  /**
+   * Create an AnimatedSprite from texture aliases (loaded via AssetManager).
+   *
+   * @param aliases - Array of texture aliases
+   * @param config - Animation options
+   * @returns Configured AnimatedSprite
+   */
+  static fromAliases(aliases: string[], config: SpriteAnimationConfig = {}): AnimatedSprite {
+    const textures = aliases.map((alias) => {
+      const tex = Texture.from(alias);
+      return tex;
+    });
+
+    return SpriteAnimation.create(textures, config);
+  }
+
+  /**
+   * Play a one-shot animation and auto-destroy when complete.
+   * Useful for fire-and-forget effects like coin bursts.
+   *
+   * @param textures - Array of textures
+   * @param config - Animation options (loop will be forced to false)
+   * @returns Promise that resolves when animation completes
+   */
+  static playOnce(
+    textures: Texture[],
+    config: SpriteAnimationConfig = {},
+  ): { sprite: AnimatedSprite; finished: Promise<void> } {
+    const finished = new Promise<void>((resolve) => {
+      config = {
+        ...config,
+        loop: false,
+        onComplete: () => {
+          config.onComplete?.();
+          sprite.destroy();
+          resolve();
+        },
+      };
+    });
+
+    const sprite = SpriteAnimation.create(textures, config);
+    return { sprite, finished };
+  }
+
+  // ─── Utility ───────────────────────────────────────────
+
+  /**
+   * Get all textures from a spritesheet that start with a given prefix.
+   * Results are sorted alphabetically by key.
+   */
+  static getTexturesByPrefix(sheet: Spritesheet, prefix: string): Texture[] {
+    const keys = Object.keys(sheet.textures)
+      .filter((k) => k.startsWith(prefix))
+      .sort();
+
+    return keys.map((k) => sheet.textures[k]);
+  }
+}

package/src/animation/Tween.ts

@@ -117,9 +117,20 @@ export class Tween {
 
   /**
    * Wait for a given duration (useful in timelines).
+   * Uses PixiJS Ticker for consistent timing with other tweens.
    */
   static delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve) => {
+      let elapsed = 0;
+      const onTick = (ticker: Ticker) => {
+        elapsed += ticker.deltaMS;
+        if (elapsed >= ms) {
+          Ticker.shared.remove(onTick);
+          resolve();
+        }
+      };
+      Ticker.shared.add(onTick);
+    });
   }
 
   /**
@@ -150,6 +161,21 @@ export class Tween {
     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(): void {
+    for (const tw of Tween._tweens) {
+      tw.resolve();
+    }
+    Tween._tweens.length = 0;
+    if (Tween._tickerAdded) {
+      Ticker.shared.remove(Tween.tick);
+      Tween._tickerAdded = false;
+    }
+  }
+
   // ─── Internal ──────────────────────────────────────────
 
   private static ensureTicker(): void {

package/src/animation/index.ts

@@ -2,3 +2,5 @@ export { Tween } from './Tween';
 export { Timeline } from './Timeline';
 export { Easing } from './Easing';
 export { SpineHelper } from './SpineHelper';
+export { SpriteAnimation } from './SpriteAnimation';
+export type { SpriteAnimationConfig } from './SpriteAnimation';

package/src/audio/AudioManager.ts

@@ -126,25 +126,45 @@ export class AudioManager {
 
     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);
-      } catch {
-        // ignore
+        sound.play(alias, {
+          volume: 0,
+          loop: true,
+        });
+        this.fadeVolume(alias, 0, this._categories.music.volume, fadeDuration);
+      } 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;
+      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);
+      try {
+        sound.play(alias, {
+          volume: this._categories.music.volume,
+          loop: true,
+        });
+      } catch (e) {
+        console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
+      }
     }
   }
 
@@ -293,6 +313,35 @@ export class AudioManager {
 
   // ─── Private ───────────────────────────────────────────
 
+  /**
+   * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
+   */
+  private fadeVolume(
+    alias: string,
+    fromVol: number,
+    toVol: number,
+    durationMs: number,
+    onComplete?: () => void,
+  ): void {
+    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);
+  }
+
   private applyVolumes(): void {
     if (!this._soundModule) return;
     const { sound } = this._soundModule;

package/src/core/EventEmitter.ts

@@ -1,6 +1,9 @@
 /**
  * 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
 export class EventEmitter<TEvents extends {}> {
@@ -27,7 +30,10 @@ export class EventEmitter<TEvents extends {}> {
     return this;
   }
 
-  emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void {
+  emit<K extends keyof TEvents>(
+    ...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]
+  ): void {
+    const [event, data] = args as [K, TEvents[K]];
     const handlers = this.listeners.get(event);
     if (handlers) {
       for (const handler of handlers) {