@playcraft/cli 0.0.53 → 0.0.56

package/project-templates/playable-template-three/src/managers/AudioManager.ts

@@ -0,0 +1,538 @@
+/**
+ * 音频管理器（Three.js 版本）
+ * 统一管理背景音乐和音效，处理后台暂停等问题
+ */
+import { sdk } from '@playcraft/adsdk';
+
+export interface AudioManagerConfig {
+  bgmUrl?: string;          // 背景音乐 URL
+  bgmVolume?: number;       // 背景音乐音量（0-1）
+  bgmLoop?: boolean;        // 背景音乐是否循环
+  effectVolume?: number;    // 音效音量（0-1）
+  enableBackgroundPause?: boolean;  // 是否启用后台自动暂停
+  watchdogInterval?: number;        // 监控守护进程检查间隔（ms）
+}
+
+export class AudioManager {
+  // 背景音乐
+  private bgm: HTMLAudioElement | null = null;
+  private isBgmPlaying = false;
+  private bgmConfig = {
+    url: '',
+    volume: 0.5,
+    loop: true
+  };
+  
+  // 音效（使用 AudioContext）
+  private audioContext: AudioContext | null = null;
+  private audioBufferCache: Map<string, AudioBuffer> = new Map();
+  private effectVolume = 0.6;
+  
+  // 游戏状态
+  private isGameEnded = false;
+  private isGamePaused = false;
+  
+  // 事件监听器引用（用于清理）
+  private eventHandlers = {
+    visibilityChange: null as (() => void) | null,
+    pageHide: null as (() => void) | null,
+    blur: null as (() => void) | null,
+    pageShow: null as (() => void) | null,
+    focus: null as (() => void) | null,
+    volumeChange: null as ((volume: number) => void) | null
+  };
+  
+  // 后台音频监控守护进程
+  private watchdogInterval: number | null = null;
+  private watchdogIntervalTime = 500; // 默认 500ms
+  
+  // 配置
+  private enableBackgroundPause = true;
+  
+  constructor(config: AudioManagerConfig = {}) {
+    this.bgmConfig.volume = config.bgmVolume ?? 0.5;
+    this.bgmConfig.loop = config.bgmLoop ?? true;
+    this.effectVolume = config.effectVolume ?? 0.6;
+    this.enableBackgroundPause = config.enableBackgroundPause ?? true;
+    this.watchdogIntervalTime = config.watchdogInterval ?? 500;
+    
+    if (config.bgmUrl) {
+      this.bgmConfig.url = config.bgmUrl;
+    }
+    
+    console.log('🎵 AudioManager created', config);
+  }
+  
+  /**
+   * 初始化音频系统
+   */
+  public init(): void {
+    // 初始化 AudioContext（用于音效）
+    this.initAudioContext();
+    
+    // 如果启用后台暂停，设置监听器
+    if (this.enableBackgroundPause) {
+      this.setupBackgroundPauseHandlers();
+    }
+    
+    console.log('✅ AudioManager initialized');
+  }
+  
+  /**
+   * 初始化 AudioContext（用于音效播放）
+   */
+  private initAudioContext(): void {
+    try {
+      const AudioContext = window.AudioContext || (window as any).webkitAudioContext;
+      if (!AudioContext) {
+        console.warn('⚠️ AudioContext not supported');
+        return;
+      }
+      
+      this.audioContext = new AudioContext();
+      console.log('✅ AudioContext created');
+    } catch (error) {
+      console.error('❌ Failed to init AudioContext:', error);
+    }
+  }
+  
+  /**
+   * 设置后台暂停监听器
+   */
+  private setupBackgroundPauseHandlers(): void {
+    // 1. 监听页面可见性变化
+    this.eventHandlers.visibilityChange = () => {
+      console.log('👁️ Visibility changed:', document.visibilityState);
+      
+      if (document.visibilityState === 'hidden') {
+        this.pauseBgm();
+        this.suspendAudioContext();
+      } else if (document.visibilityState === 'visible') {
+        this.resumeBgm();
+        this.resumeAudioContext();
+      }
+    };
+    
+    document.addEventListener('visibilitychange', this.eventHandlers.visibilityChange);
+    
+    // 2. 监听移动端的 pagehide/pageshow
+    this.eventHandlers.pageHide = () => {
+      console.log('📱 Page hide event triggered');
+      this.pauseBgm();
+      this.suspendAudioContext();
+    };
+    
+    this.eventHandlers.pageShow = () => {
+      console.log('📱 Page show event triggered');
+      this.resumeBgm();
+      this.resumeAudioContext();
+    };
+    
+    window.addEventListener('pagehide', this.eventHandlers.pageHide);
+    window.addEventListener('pageshow', this.eventHandlers.pageShow);
+    
+    // 3. 监听窗口 blur/focus
+    this.eventHandlers.blur = () => {
+      console.log('🔍 Window blur event triggered');
+      this.pauseBgm();
+      this.suspendAudioContext();
+    };
+    
+    this.eventHandlers.focus = () => {
+      console.log('🔍 Window focus event triggered');
+      this.resumeBgm();
+      this.resumeAudioContext();
+    };
+    
+    window.addEventListener('blur', this.eventHandlers.blur);
+    window.addEventListener('focus', this.eventHandlers.focus);
+    
+    // 4. 监听 SDK 音量变化
+    this.eventHandlers.volumeChange = (volume: number) => {
+      console.log('🔊 SDK volume changed:', volume);
+      this.setVolume(volume);
+    };
+    
+    sdk.on('volume', this.eventHandlers.volumeChange);
+    
+    // 5. 启动后台音频监控守护进程
+    this.startWatchdog();
+  }
+  
+  /**
+   * 启动后台音频监控守护进程
+   */
+  private startWatchdog(): void {
+    this.watchdogInterval = window.setInterval(() => {
+      // 只在页面隐藏时检查
+      if (document.visibilityState === 'hidden' || document.hidden) {
+        // 如果背景音乐在播放，强制暂停
+        if (this.bgm && !this.bgm.paused) {
+          console.warn('⚠️ Watchdog: BGM still playing in background, force pausing!');
+          this.bgm.pause();
+        }
+        
+        // 如果 AudioContext 在运行，强制暂停
+        if (this.audioContext && this.audioContext.state === 'running') {
+          console.warn('⚠️ Watchdog: AudioContext still running in background, force suspending!');
+          this.audioContext.suspend().catch(err => {
+            console.error('Failed to suspend AudioContext:', err);
+          });
+        }
+      }
+    }, this.watchdogIntervalTime);
+    
+    console.log('✅ Background audio watchdog started');
+  }
+  
+  /**
+   * 停止后台音频监控守护进程
+   */
+  private stopWatchdog(): void {
+    if (this.watchdogInterval !== null) {
+      window.clearInterval(this.watchdogInterval);
+      this.watchdogInterval = null;
+      console.log('✅ Background audio watchdog stopped');
+    }
+  }
+  
+  /**
+   * 加载并播放背景音乐
+   */
+  public async playBgm(url?: string): Promise<void> {
+    if (url) {
+      this.bgmConfig.url = url;
+    }
+    
+    if (!this.bgmConfig.url) {
+      console.warn('⚠️ BGM URL not set');
+      return;
+    }
+    
+    if (this.isBgmPlaying) {
+      console.log('🎵 BGM already playing');
+      return;
+    }
+    
+    try {
+      console.log('🎵 Loading and playing BGM...');
+      
+      // 创建或复用 Audio 对象
+      if (!this.bgm) {
+        this.bgm = new Audio();
+        this.bgm.src = this.bgmConfig.url;
+        this.bgm.loop = this.bgmConfig.loop;
+        this.bgm.volume = this.bgmConfig.volume;
+        this.bgm.preload = 'auto';
+        
+        // 禁用媒体会话（防止某些浏览器的后台播放）
+        if ('mediaSession' in navigator) {
+          try {
+            (navigator as any).mediaSession.playbackState = 'none';
+          } catch (e) {
+            console.warn('无法设置 mediaSession:', e);
+          }
+        }
+        
+        // 监听事件
+        this.bgm.addEventListener('play', () => {
+          console.log('🎵 BGM play event triggered');
+        });
+        
+        this.bgm.addEventListener('pause', () => {
+          console.log('🎵 BGM pause event triggered');
+        });
+        
+        this.bgm.addEventListener('error', (e) => {
+          console.error('❌ BGM error:', e);
+        });
+        
+        this.bgm.addEventListener('ended', () => {
+          console.log('🎵 BGM ended');
+          if (this.isBgmPlaying && !this.isGameEnded) {
+            this.bgm?.play().catch(err => console.error('Failed to restart BGM:', err));
+          }
+        });
+      }
+      
+      // 恢复 AudioContext（如果需要）
+      if (this.audioContext && this.audioContext.state === 'suspended') {
+        await this.audioContext.resume();
+      }
+      
+      // 播放
+      await this.bgm.play();
+      this.isBgmPlaying = true;
+      console.log('✅ BGM playing');
+    } catch (error) {
+      console.error('❌ Failed to play BGM:', error);
+      throw error;
+    }
+  }
+  
+  /**
+   * 暂停背景音乐
+   */
+  public pauseBgm(): void {
+    if (this.bgm && !this.bgm.paused) {
+      this.bgm.pause();
+      console.log('✅ BGM paused');
+    }
+  }
+  
+  /**
+   * 恢复背景音乐
+   */
+  public resumeBgm(): void {
+    if (this.bgm && this.isBgmPlaying && this.bgm.paused && !this.isGameEnded && !this.isGamePaused) {
+      this.bgm.play().catch(err => {
+        console.error('❌ Failed to resume BGM:', err);
+      });
+      console.log('✅ BGM resumed');
+    }
+  }
+  
+  /**
+   * 停止背景音乐
+   */
+  public stopBgm(): void {
+    if (this.bgm) {
+      this.bgm.pause();
+      this.bgm.currentTime = 0;
+      this.isBgmPlaying = false;
+      console.log('✅ BGM stopped');
+    }
+  }
+  
+  /**
+   * 暂停 AudioContext
+   */
+  private suspendAudioContext(): void {
+    if (this.audioContext && this.audioContext.state === 'running') {
+      this.audioContext.suspend().then(() => {
+        console.log('✅ AudioContext suspended');
+      }).catch(err => {
+        console.error('❌ Failed to suspend AudioContext:', err);
+      });
+    }
+  }
+  
+  /**
+   * 恢复 AudioContext
+   */
+  private resumeAudioContext(): void {
+    if (this.audioContext && this.audioContext.state === 'suspended' && !this.isGamePaused) {
+      this.audioContext.resume().then(() => {
+        console.log('✅ AudioContext resumed');
+      }).catch(err => {
+        console.error('❌ Failed to resume AudioContext:', err);
+      });
+    }
+  }
+  
+  /**
+   * 设置音量
+   * @param volume 音量（0-1）
+   */
+  public setVolume(volume: number): void {
+    // 设置背景音乐音量
+    if (this.bgm) {
+      this.bgm.volume = volume;
+      
+      // 如果音量为 0，暂停背景音乐
+      if (volume === 0 && !this.bgm.paused) {
+        this.pauseBgm();
+      }
+      // 如果音量大于 0 且之前在播放，恢复播放
+      else if (volume > 0 && this.bgm.paused && this.isBgmPlaying && !this.isGameEnded && !this.isGamePaused) {
+        this.resumeBgm();
+      }
+    }
+    
+    // 音效音量会在播放时应用
+    this.effectVolume = volume;
+  }
+  
+  /**
+   * 预加载音效
+   * @param key 音效标识
+   * @param url 音效 URL
+   */
+  public async preloadEffect(key: string, url: string): Promise<void> {
+    if (!this.audioContext) {
+      console.warn('⚠️ AudioContext not available');
+      return;
+    }
+    
+    try {
+      console.log(`🎵 Preloading effect: ${key}`);
+      const response = await fetch(url);
+      const arrayBuffer = await response.arrayBuffer();
+      const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+      this.audioBufferCache.set(key, audioBuffer);
+      console.log(`✅ Effect loaded: ${key}`);
+    } catch (error) {
+      console.error(`❌ Failed to preload effect ${key}:`, error);
+    }
+  }
+  
+  /**
+   * 添加已解码的音效 Buffer
+   * @param key 音效标识
+   * @param buffer 音效 AudioBuffer
+   */
+  public addEffectBuffer(key: string, buffer: AudioBuffer): void {
+    this.audioBufferCache.set(key, buffer);
+    console.log(`✅ Effect buffer added: ${key}`);
+  }
+  
+  /**
+   * 播放音效
+   * @param key 音效标识
+   * @param volume 音量（可选，默认使用全局音效音量）
+   */
+  public playEffect(key: string, volume?: number): void {
+    if (this.isGameEnded) return;
+    
+    if (!this.audioContext) {
+      console.warn('⚠️ AudioContext not available');
+      return;
+    }
+    
+    const buffer = this.audioBufferCache.get(key);
+    if (!buffer) {
+      console.warn(`⚠️ Effect not loaded: ${key}`);
+      return;
+    }
+    
+    try {
+      // 恢复 AudioContext（如果被暂停）
+      if (this.audioContext.state === 'suspended') {
+        this.audioContext.resume();
+      }
+      
+      // 创建音频源节点
+      const source = this.audioContext.createBufferSource();
+      source.buffer = buffer;
+      
+      // 创建增益节点（用于控制音量）
+      const gainNode = this.audioContext.createGain();
+      gainNode.gain.value = volume ?? this.effectVolume;
+      
+      // 连接节点
+      source.connect(gainNode);
+      gainNode.connect(this.audioContext.destination);
+      
+      // 播放
+      source.start(0);
+      console.log(`🎵 Playing effect: ${key}`);
+    } catch (error) {
+      console.error(`❌ Failed to play effect ${key}:`, error);
+    }
+  }
+  
+  /**
+   * 播放音效（使用 Audio 标签，支持重叠播放）
+   * @param url 音效 URL
+   * @param volume 音量（可选）
+   */
+  public playEffectByAudio(url: string, volume?: number): void {
+    if (this.isGameEnded) return;
+    
+    try {
+      const audio = new Audio();
+      audio.src = url;
+      audio.volume = volume ?? this.effectVolume;
+      
+      // 播放完成后清理
+      audio.addEventListener('ended', () => {
+        audio.src = '';
+      }, { once: true });
+      
+      audio.play().catch(err => {
+        console.error('❌ Failed to play effect:', err);
+      });
+    } catch (error) {
+      console.error('❌ Failed to play effect by Audio:', error);
+    }
+  }
+  
+  /**
+   * 标记游戏结束（停止音频恢复）
+   */
+  public setGameEnded(ended: boolean): void {
+    this.isGameEnded = ended;
+    if (ended) {
+      this.stopBgm();
+    }
+  }
+  
+  /**
+   * 设置游戏暂停状态
+   */
+  public setGamePaused(paused: boolean): void {
+    this.isGamePaused = paused;
+    if (paused) {
+      this.pauseBgm();
+      this.suspendAudioContext();
+    } else {
+      this.resumeBgm();
+      this.resumeAudioContext();
+    }
+  }
+  
+  /**
+   * 清理资源
+   */
+  public destroy(): void {
+    console.log('🎵 Destroying AudioManager...');
+    
+    // 停止守护进程
+    this.stopWatchdog();
+    
+    // 移除 document 事件监听
+    if (this.eventHandlers.visibilityChange) {
+      document.removeEventListener('visibilitychange', this.eventHandlers.visibilityChange);
+    }
+    
+    // 移除 window 事件监听
+    if (this.eventHandlers.pageHide) {
+      window.removeEventListener('pagehide', this.eventHandlers.pageHide);
+    }
+    if (this.eventHandlers.pageShow) {
+      window.removeEventListener('pageshow', this.eventHandlers.pageShow);
+    }
+    if (this.eventHandlers.blur) {
+      window.removeEventListener('blur', this.eventHandlers.blur);
+    }
+    if (this.eventHandlers.focus) {
+      window.removeEventListener('focus', this.eventHandlers.focus);
+    }
+    
+    // 移除 SDK 事件监听
+    if (this.eventHandlers.volumeChange) {
+      sdk.off('volume', this.eventHandlers.volumeChange);
+    }
+    
+    // 清理背景音乐
+    if (this.bgm) {
+      this.bgm.pause();
+      this.bgm.currentTime = 0;
+      this.bgm.src = '';
+      this.bgm = null;
+    }
+    
+    // 清理 AudioContext
+    if (this.audioContext) {
+      this.audioContext.close().catch(err => {
+        console.warn('Failed to close AudioContext:', err);
+      });
+      this.audioContext = null;
+    }
+    
+    // 清理缓存
+    this.audioBufferCache.clear();
+    
+    console.log('✅ AudioManager destroyed');
+  }
+}