@duyquangnvx/pixi-game-engine 0.1.5 → 0.1.7

package/README.md

@@ -1,75 +1,75 @@
-# @duyquangnvx/pixi-game-engine
-
-Full-featured PixiJS v7 game engine with TypeScript support.
-
-## Installation
-
-```bash
-pnpm add @duyquangnvx/pixi-game-engine
-```
-
-## Quick Start
-
-```typescript
-import { Engine, Scene, PIXI } from '@duyquangnvx/pixi-game-engine';
-
-class GameScene extends Scene {
-  private player!: PIXI.Sprite;
-
-  onEnter() {
-    this.player = new PIXI.Graphics();
-    this.player.beginFill(0x4ecca3);
-    this.player.drawRect(-25, -25, 50, 50);
-    this.player.x = Engine.screen.width / 2;
-    this.player.y = Engine.screen.height / 2;
-    this.addChild(this.player);
-  }
-
-  onUpdate(delta: number) {
-    const { keyboard } = Engine.input;
-
-    if (keyboard.isDown('ArrowLeft')) this.player.x -= 5 * delta;
-    if (keyboard.isDown('ArrowRight')) this.player.x += 5 * delta;
-    if (keyboard.isDown('ArrowUp')) this.player.y -= 5 * delta;
-    if (keyboard.isDown('ArrowDown')) this.player.y += 5 * delta;
-  }
-
-  onExit() {}
-}
-
-Engine.init({
-  width: 800,
-  height: 600,
-  backgroundColor: 0x1a1a2e,
-});
-
-document.body.appendChild(Engine.view as HTMLCanvasElement);
-Engine.scenes.add('game', GameScene);
-Engine.scenes.start('game');
-```
-
-## Features
-
-| Feature | Module | Description |
-|---------|--------|-------------|
-| Scenes | `SceneManager` | Scene lifecycle, transitions |
-| Input | `InputManager` | Keyboard, mouse, touch, gamepad |
-| Assets | `AssetManager` | Manifest-based loading |
-| Sound | `SoundManager` | @pixi/sound wrapper |
-| Particles | `ParticleManager` | @pixi/particle-emitter |
-| Tweens | `TweenManager` | GSAP + PixiPlugin |
-| UI | `UIManager` | @pixi/ui components |
-| Spine | `SpineManager` | pixi-spine animations |
-
-## Dependencies
-
-- pixi.js ^7.4.2
-- @pixi/sound ^5.2.3
-- @pixi/particle-emitter ^5.0.10
-- @pixi/ui ^1.2.4
-- pixi-spine ^4.0.5
-- gsap ^3.12.x
-
-## License
-
-MIT
+# @duyquangnvx/pixi-game-engine
+
+Full-featured PixiJS v7 game engine with TypeScript support.
+
+## Installation
+
+```bash
+pnpm add @duyquangnvx/pixi-game-engine
+```
+
+## Quick Start
+
+```typescript
+import { Engine, Scene, PIXI } from '@duyquangnvx/pixi-game-engine';
+
+class GameScene extends Scene {
+  private player!: PIXI.Sprite;
+
+  onEnter() {
+    this.player = new PIXI.Graphics();
+    this.player.beginFill(0x4ecca3);
+    this.player.drawRect(-25, -25, 50, 50);
+    this.player.x = Engine.screen.width / 2;
+    this.player.y = Engine.screen.height / 2;
+    this.addChild(this.player);
+  }
+
+  onUpdate(delta: number) {
+    const { keyboard } = Engine.input;
+
+    if (keyboard.isDown('ArrowLeft')) this.player.x -= 5 * delta;
+    if (keyboard.isDown('ArrowRight')) this.player.x += 5 * delta;
+    if (keyboard.isDown('ArrowUp')) this.player.y -= 5 * delta;
+    if (keyboard.isDown('ArrowDown')) this.player.y += 5 * delta;
+  }
+
+  onExit() {}
+}
+
+Engine.init({
+  width: 800,
+  height: 600,
+  backgroundColor: 0x1a1a2e,
+});
+
+document.body.appendChild(Engine.view as HTMLCanvasElement);
+Engine.scenes.add('game', GameScene);
+Engine.scenes.start('game');
+```
+
+## Features
+
+| Feature | Module | Description |
+|---------|--------|-------------|
+| Scenes | `SceneManager` | Scene lifecycle, transitions |
+| Input | `InputManager` | Keyboard, mouse, touch, gamepad |
+| Assets | `AssetManager` | Manifest-based loading |
+| Sound | `SoundManager` | @pixi/sound wrapper |
+| Particles | `ParticleManager` | @pixi/particle-emitter |
+| Tweens | `TweenManager` | GSAP + PixiPlugin |
+| UI | `UIManager` | @pixi/ui components |
+| Spine | `SpineManager` | pixi-spine animations |
+
+## Dependencies
+
+- pixi.js ^7.4.2
+- @pixi/sound ^5.2.3
+- @pixi/particle-emitter ^5.0.10
+- @pixi/ui ^1.2.4
+- pixi-spine ^4.0.5
+- gsap ^3.12.x
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1327,111 +1327,252 @@ var SceneManager = class {
 
 // src/sound/sound-manager.ts
 var import_sound = require("@pixi/sound");
+var STORAGE_KEY = "sound_settings";
 var SoundManager = class {
   volumes = {
     master: 1,
     music: 1,
     sfx: 1
   };
+  _muted = false;
   currentMusic = null;
   currentMusicAlias = null;
-  playSfx(alias, options = {}) {
-    this.play(alias, options);
+  currentMusicInstance = null;
+  /** Track active SFX instances for pause/resume/stop */
+  activeSfx = /* @__PURE__ */ new Map();
+  /** Whether the AudioContext has been unlocked by user interaction */
+  _unlocked = false;
+  constructor() {
+    this.loadSettings();
+    this.setupUnlockListener();
+  }
+  // ─── AudioContext unlock ──────────────────────────────
+  /** 
+   * Browsers block audio until first user interaction.
+   * Call this early or let the auto-listener handle it. 
+   */
+  setupUnlockListener() {
+    const unlock = () => {
+      if (this._unlocked) return;
+      const ctx = import_sound.sound.context;
+      if (ctx.audioContext.state === "suspended") {
+        ctx.audioContext.resume().then(() => {
+          this._unlocked = true;
+          Logger.info("SoundManager", "AudioContext unlocked");
+        });
+      } else {
+        this._unlocked = true;
+      }
+      if (this._unlocked) {
+        document.removeEventListener("pointerdown", unlock);
+        document.removeEventListener("keydown", unlock);
+      }
+    };
+    document.addEventListener("pointerdown", unlock, { once: false });
+    document.addEventListener("keydown", unlock, { once: false });
   }
-  /** Play a sound effect */
-  play(alias, options = {}) {
+  get isUnlocked() {
+    return this._unlocked;
+  }
+  // ─── SFX ─────────────────────────────────────────────
+  /** Play a sound effect. Returns instance for fine-grained control. */
+  playSfx(alias, options = {}) {
     const snd = import_sound.sound.find(alias);
     if (!snd) {
       Logger.warn("SoundManager", `Sound "${alias}" not found`);
-      return;
+      return null;
     }
-    snd.play({
-      volume: (options.volume ?? 1) * this.volumes.master * this.volumes.sfx,
+    const effectiveVolume = (options.volume ?? 1) * this.volumes.master * this.volumes.sfx;
+    const instance = snd.play({
+      volume: options.fadeIn ? 0 : effectiveVolume,
       loop: options.loop ?? false,
       speed: options.speed ?? 1
     });
+    if (!this.activeSfx.has(alias)) {
+      this.activeSfx.set(alias, /* @__PURE__ */ new Set());
+    }
+    this.activeSfx.get(alias).add(instance);
+    instance.on("end", () => {
+      this.activeSfx.get(alias)?.delete(instance);
+    });
+    if (options.fadeIn && options.fadeIn > 0) {
+      this.fadeInstance(instance, 0, effectiveVolume, options.fadeIn);
+    }
+    return instance;
+  }
+  /** Stop a specific SFX by alias (all instances) */
+  stopSfx(alias, fadeOut) {
+    const instances = this.activeSfx.get(alias);
+    if (!instances) return;
+    for (const inst of instances) {
+      if (fadeOut && fadeOut > 0) {
+        this.fadeInstance(inst, inst.volume, 0, fadeOut, () => {
+          inst.stop();
+        });
+      } else {
+        inst.stop();
+      }
+    }
+    this.activeSfx.delete(alias);
   }
-  /** Play background music (only one at a time) */
+  // ─── Music ───────────────────────────────────────────
+  /** Play background music with optional crossfade */
   playMusic(alias, options = {}) {
-    if (this.currentMusicAlias !== alias) {
-      this.stopMusic();
-    }
+    if (this.currentMusicAlias === alias) return;
     const snd = import_sound.sound.find(alias);
     if (!snd) {
       Logger.warn("SoundManager", `Music "${alias}" not found`);
       return;
     }
-    this.currentMusic = snd;
-    this.currentMusicAlias = alias;
-    snd.play({
-      volume: (options.volume ?? 1) * this.volumes.master * this.volumes.music,
+    const crossfade = options.crossfadeDuration ?? 0;
+    const targetVolume = (options.volume ?? 1) * this.volumes.master * this.volumes.music;
+    if (this.currentMusicInstance && crossfade > 0) {
+      const oldInstance = this.currentMusicInstance;
+      this.fadeInstance(oldInstance, oldInstance.volume, 0, crossfade, () => {
+        oldInstance.stop();
+      });
+    } else {
+      this.stopMusic();
+    }
+    const instance = snd.play({
+      volume: crossfade > 0 ? 0 : targetVolume,
       loop: options.loop ?? true,
       speed: options.speed ?? 1
     });
-  }
-  /** Stop the current music */
-  stopMusic() {
-    if (this.currentMusic) {
-      this.currentMusic.stop();
-      this.currentMusic = null;
-      this.currentMusicAlias = null;
+    this.currentMusic = snd;
+    this.currentMusicAlias = alias;
+    this.currentMusicInstance = instance;
+    if (crossfade > 0) {
+      this.fadeInstance(instance, 0, targetVolume, crossfade);
     }
   }
-  /** Stop a specific sound */
-  stop(alias) {
-    const snd = import_sound.sound.find(alias);
-    if (snd) {
-      snd.stop();
+  stopMusic(fadeOut) {
+    if (!this.currentMusicInstance) return;
+    if (fadeOut && fadeOut > 0) {
+      const inst = this.currentMusicInstance;
+      this.fadeInstance(inst, inst.volume, 0, fadeOut, () => {
+        inst.stop();
+      });
+    } else {
+      this.currentMusicInstance.stop();
     }
-  }
-  /** Stop all sounds */
-  stopAll() {
-    import_sound.sound.stopAll();
     this.currentMusic = null;
     this.currentMusicAlias = null;
+    this.currentMusicInstance = null;
   }
-  /** Pause all sounds */
-  pauseAll() {
-    import_sound.sound.pauseAll();
+  get currentMusicName() {
+    return this.currentMusicAlias;
   }
-  /** Resume all sounds */
-  resumeAll() {
-    import_sound.sound.resumeAll();
+  /** Pause only music */
+  pauseMusic() {
+    this.currentMusicInstance?.set("paused", true);
   }
-  /** Set volume for a channel */
+  /** Resume only music */
+  resumeMusic() {
+    this.currentMusicInstance?.set("paused", false);
+  }
+  // ─── Volume ──────────────────────────────────────────
   setVolume(channel, value) {
     this.volumes[channel] = Math.max(0, Math.min(1, value));
-    this.updateMusicVolume();
+    this.applyVolumes();
+    this.saveSettings();
   }
-  /** Get volume for a channel */
   getVolume(channel) {
     return this.volumes[channel];
   }
-  updateMusicVolume() {
-    if (this.currentMusic) {
-      this.currentMusic.volume = this.volumes.master * this.volumes.music;
+  /** Re-apply volume to all active sounds after a channel change */
+  applyVolumes() {
+    if (this.currentMusicInstance) {
+      this.currentMusicInstance.volume = this.volumes.master * this.volumes.music;
+    }
+    for (const instances of this.activeSfx.values()) {
+      for (const inst of instances) {
+        inst.volume = this.volumes.master * this.volumes.sfx;
+      }
     }
   }
-  /** Mute all sounds */
+  // ─── Mute ────────────────────────────────────────────
   mute() {
+    this._muted = true;
     import_sound.sound.muteAll();
+    this.saveSettings();
   }
-  /** Unmute all sounds */
   unmute() {
+    this._muted = false;
     import_sound.sound.unmuteAll();
+    this.saveSettings();
   }
-  /** Toggle mute */
   toggleMute() {
-    import_sound.sound.toggleMuteAll();
-    return import_sound.sound.context.muted;
+    if (this._muted) this.unmute();
+    else this.mute();
+    return this._muted;
   }
-  /** Check if muted */
   get isMuted() {
-    return import_sound.sound.context.muted;
+    return this._muted;
   }
-  /** Clean up */
+  // ─── Global controls ─────────────────────────────────
+  stopAll() {
+    import_sound.sound.stopAll();
+    this.currentMusic = null;
+    this.currentMusicAlias = null;
+    this.currentMusicInstance = null;
+    this.activeSfx.clear();
+  }
+  pauseAll() {
+    import_sound.sound.pauseAll();
+  }
+  resumeAll() {
+    import_sound.sound.resumeAll();
+  }
+  // ─── Persistence ─────────────────────────────────────
+  saveSettings() {
+    try {
+      const data = {
+        volumes: this.volumes,
+        muted: this._muted
+      };
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+    } catch {
+    }
+  }
+  loadSettings() {
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (!raw) return;
+      const data = JSON.parse(raw);
+      if (data.volumes) {
+        this.volumes.master = data.volumes.master ?? 1;
+        this.volumes.music = data.volumes.music ?? 1;
+        this.volumes.sfx = data.volumes.sfx ?? 1;
+      }
+      if (data.muted) {
+        this._muted = true;
+        import_sound.sound.muteAll();
+      }
+    } catch {
+    }
+  }
+  // ─── Fade utility ────────────────────────────────────
+  fadeInstance(instance, from, to, duration, onComplete) {
+    const steps = 30;
+    const interval = duration * 1e3 / steps;
+    const delta = (to - from) / steps;
+    let step = 0;
+    const timer = setInterval(() => {
+      step++;
+      instance.volume = from + delta * step;
+      if (step >= steps) {
+        clearInterval(timer);
+        instance.volume = to;
+        onComplete?.();
+      }
+    }, interval);
+  }
+  // ─── Cleanup ─────────────────────────────────────────
   destroy() {
     this.stopAll();
+    document.removeEventListener("pointerdown", this.setupUnlockListener);
+    document.removeEventListener("keydown", this.setupUnlockListener);
   }
 };
 
@@ -1453,10 +1594,32 @@ var SpineManager = class {
   fromData(skeletonData) {
     return new import_pixi_spine2.Spine(skeletonData);
   }
-  /** Play an animation on a Spine instance */
-  play(spine, animationName, loop = true, trackIndex = 0) {
+  /** Play an animation on a Spine instance.
+   *  By default skips if the same animation is already playing (avoids restart).
+   *  Pass `force: true` to restart from frame 0. */
+  play(spine, animationName, loop = true, trackIndex = 0, options) {
+    if (!options?.force) {
+      const current = spine.state.tracks[trackIndex];
+      if (current?.animation?.name === animationName) return;
+    }
     spine.state.setAnimation(trackIndex, animationName, loop);
   }
+  /** Play a non-looping animation and resolve when it completes. */
+  playOnce(spine, animationName, trackIndex = 0) {
+    return new Promise((resolve) => {
+      spine.state.setAnimation(trackIndex, animationName, false);
+      const listener = {
+        complete: (entry) => {
+          const track = entry;
+          if (track.animation?.name === animationName) {
+            spine.state.removeListener(listener);
+            resolve();
+          }
+        }
+      };
+      spine.state.addListener(listener);
+    });
+  }
   /** Add an animation to the queue */
   queue(spine, animationName, loop = false, delay = 0, trackIndex = 0) {
     spine.state.addAnimation(trackIndex, animationName, loop, delay);
@@ -1490,6 +1653,12 @@ var SpineManager = class {
   setSpeed(spine, speed) {
     spine.state.timeScale = speed;
   }
+  /** Clear tracks, remove listeners, and destroy the spine instance. */
+  destroy(spine) {
+    spine.state.clearTracks();
+    spine.state.clearListeners();
+    spine.destroy({ children: true });
+  }
 };
 
 // src/ui/toast/toast-manager.ts