@ives_xxz/framework 1.4.16 → 1.5.1

package/manager/FWAudioManager.ts

@@ -1,29 +1,54 @@
 import { FWManager } from './FWManager';
-import Framework from '../Framework';
 import FWLog from '../log/FWLog';
+import { FWSystemDefine } from '../define/FWSystemDefine';
+
+class FWAudioData {
+  clip: cc.AudioClip;
+  volume: number = 1;
+  loop: boolean = false;
+  cb?: (id: number) => void;
+  tag?: string;
+}
+
+class FWAudioPoolItem {
+  constructor(public audioId: number, public startTime: number, public tag?: string) {}
+}
 
 export default class FWAudioManager extends FWManager implements FW.AudioManager {
-  /**背景音量 */
   musicVolume: number = 1;
-  /**音效音量 */
   effectsVolume: number = 1;
-  /**播放音效的音量 */
   soundVolume: number = 1;
 
-  public initialize(): void {}
+  private audioPool: Map<number, FWAudioPoolItem> = new Map();
+  private maxConcurrentAudio: number = 10;
+  private cleanupInterval: number = 5;
 
-  playMusic(path: string, volume?: number, loop?: boolean);
-  playMusic(music: cc.AudioClip, volume?: number, loop?: boolean);
-  playMusic(assetProperty: FW.AssetProperty, volume?: number, loop?: boolean);
-  async playMusic() {
+  public initialize(): void {
+    this.autoClear();
+  }
+
+  /**
+   * 播放背景音乐
+   */
+  async playMusic(path: string, volume?: number, loop?: boolean): Promise<void>;
+  async playMusic(music: cc.AudioClip, volume?: number, loop?: boolean): Promise<void>;
+  async playMusic(assetProperty: FW.AssetProperty, volume?: number, loop?: boolean): Promise<void>;
+  async playMusic(): Promise<void> {
     try {
-      const data = await this.dataProcessing(arguments[0], arguments[1], arguments[2]);
-      if (!data) return;
-      const clip = data.clip;
-      const volume = data.volume === undefined ? this.musicVolume : arguments[1];
-      const loop = data.loop === undefined ? true : arguments[2];
-      const id = cc.audioEngine.playMusic(clip, loop);
+      const audioData = await this.processAudioArguments(
+        arguments,
+        FWSystemDefine.FWAudioType.MUSIC,
+      );
+      if (!audioData.clip) return;
+
+      const volume = audioData.volume ?? this.musicVolume;
+      const loop = audioData.loop ?? true;
+
+      cc.audioEngine.stopMusic();
+      const id = cc.audioEngine.playMusic(audioData.clip, loop);
       cc.audioEngine.setVolume(id, volume);
+
+      FWLog.debug(`播放背景音乐: ${this.getAudioName(audioData.clip)}`);
     } catch (e) {
       FWLog.error('播放音乐失败:', e);
     }
@@ -32,255 +57,275 @@ export default class FWAudioManager extends FWManager implements FW.AudioManager
   stopMusic(): void {
     cc.audioEngine.stopMusic();
   }
+
   pauseMusic(): void {
     cc.audioEngine.pauseMusic();
   }
+
   resumeMusic(): void {
     cc.audioEngine.resumeMusic();
   }
-  /**设置背景音效是否静音 */
+
+  /** 设置背景音效是否静音 */
   setMusicMute(mute: boolean): void {
-    if (mute) {
-      this.musicVolume = 1;
-    } else {
-      this.musicVolume = 0;
-    }
+    this.musicVolume = mute ? 0 : 1;
     cc.audioEngine.setMusicVolume(this.musicVolume);
   }
 
+  /**
+   * 播放音效
+   */
   async play(
     path: string,
     cb?: (id: number) => void,
     volume?: number,
     loop?: boolean,
+    tag?: string,
   ): Promise<number>;
   async play(
     audio: cc.AudioClip,
     cb?: (id: number) => void,
     volume?: number,
     loop?: boolean,
+    tag?: string,
   ): Promise<number>;
   async play(
     assetProperty: FW.AssetProperty,
     cb?: (id: number) => void,
     volume?: number,
     loop?: boolean,
+    tag?: string,
   ): Promise<number>;
   async play(): Promise<number> {
     try {
-      const data = await this.dataProcessing(
-        arguments[0],
-        arguments[1],
-        arguments[2],
-        arguments[3],
+      if (this.audioPool.size >= this.maxConcurrentAudio) {
+        this.clearFinishedAudio();
+        if (this.audioPool.size >= this.maxConcurrentAudio) {
+          FWLog.warn('音频池已满，无法播放新音频');
+          return -1;
+        }
+      }
+
+      const audioData = await this.processAudioArguments(
+        arguments,
+        FWSystemDefine.FWAudioType.SOUND,
       );
-      if (!data) return;
-      const clip = data.clip;
-      const volume = data.volume === undefined ? this.soundVolume : data.volume;
-      const loop = data.loop === undefined ? false : data.loop;
-      const id = cc.audioEngine.play(clip, loop, volume);
+      if (!audioData.clip) return -1;
+
+      const volume = (audioData.volume ?? this.soundVolume) * this.effectsVolume;
+      const loop = audioData.loop ?? false;
+      const tag = audioData.tag;
+
+      const id = cc.audioEngine.play(audioData.clip, loop, volume);
+
+      this.audioPool.set(id, new FWAudioPoolItem(id, Date.now(), tag));
+
       cc.audioEngine.setFinishCallback(id, () => {
-        data.cb?.(id);
+        audioData.cb?.(id);
+        this.audioPool.delete(id);
       });
+
       return id;
     } catch (e) {
       FWLog.error('播放音效失败:', e);
+      return -1;
     }
   }
+
   /**
-   *
-   * @param id 停止
+   * 停止指定音效
    */
-  public stop(id: number) {
-    cc.audioEngine.stop(id);
+  stop(id: number): void {
+    if (this.audioPool.has(id)) {
+      cc.audioEngine.stop(id);
+      this.audioPool.delete(id);
+      FWLog.debug(`停止音效: ID ${id}`);
+    }
   }
+
   pauseAll(): void {
     cc.audioEngine.pauseAll();
+    FWLog.debug('暂停所有音效');
   }
+
   resumeAll(): void {
     cc.audioEngine.resumeAll();
+    FWLog.debug('恢复所有音效');
   }
+
   stopAll(): void {
     cc.audioEngine.stopAll();
+    this.audioPool.clear();
+    FWLog.debug('停止所有音效');
   }
-  /**设置播放音效是否静音 */
+
+  /** 设置播放音效是否静音 */
   setSoundMute(mute: boolean): void {
-    if (mute) {
-      this.soundVolume = 1;
-    } else {
-      this.soundVolume = 0;
-    }
+    this.soundVolume = mute ? 0 : 1;
+    FWLog.debug(`音效${mute ? '静音' : '取消静音'}`);
   }
 
-  /**播放音效 */
-  async playEffect(path: string, loop?: boolean): Promise<number>;
-  async playEffect(audio: cc.AudioClip, loop?: boolean): Promise<number>;
-  async playEffect(assetProperty: FW.AssetProperty, loop?: boolean): Promise<number>;
-  async playEffect(): Promise<number> {
+  /**
+   * 预加载音频资源
+   */
+  async preloadAudio(assetProperty: FW.AssetProperty): Promise<cc.AudioClip> {
     try {
-      const data = await this.dataProcessing(arguments[0], arguments[1]);
-      if (!data) return;
-      const clip = data.clip;
-      const loop = data.loop === undefined ? false : arguments[1];
-      const id = cc.audioEngine.playEffect(clip, loop);
-      return id;
+      let clip: cc.AudioClip;
+
+      if (typeof assetProperty === 'string') {
+        clip = await FW.Entry.resMgr.loadAsset<cc.AudioClip>({
+          path: assetProperty,
+          bundle: FW.Entry.bundleName,
+        });
+      } else {
+        clip = await FW.Entry.resMgr.loadAsset<cc.AudioClip>(assetProperty);
+      }
+
+      return clip;
     } catch (e) {
-      FWLog.error('播放音效失败:', e);
+      return null;
     }
   }
 
   /**
-   * 停止音效
-   * @param effectName 声音文件名
-   * @returns
+   * 释放音频资源
    */
-  stopEffect(audioID: number): void {
-    if (!audioID) return;
-    return cc.audioEngine.stopEffect(audioID);
+  releaseAudio(assetProperty: FW.AssetProperty): void {
+    FW.Entry.resMgr.releaseAsset(assetProperty);
   }
+
   /**
-   * 设置音效音量
-   * @param volume 音量
+   * 获取音频池信息
    */
-  setEffectsVolume(volume: number): void {
-    cc.audioEngine.setEffectsVolume(volume);
+  getAudioPoolInfo(): { playing: number; maxConcurrent: number } {
+    return {
+      playing: this.audioPool.size,
+      maxConcurrent: this.maxConcurrentAudio,
+    };
   }
+
   /**
-   * 停止播放所有音效
+   * 设置最大并发音频数
    */
-  stopAllEffects(): void {
-    cc.audioEngine.stopAllEffects();
+  setMaxConcurrentAudio(max: number): void {
+    this.maxConcurrentAudio = Math.max(1, max);
   }
-  /**设置音效是否静音 */
-  setEffectsMute(mute: boolean): void {
-    if (mute) {
-      this.effectsVolume = 1;
-    } else {
-      this.effectsVolume = 0;
-    }
-    cc.audioEngine.setEffectsVolume(this.effectsVolume);
+
+  /**
+   * 根据标签停止音效
+   */
+  stopByTag(tag: string): void {
+    const arr: number[] = [];
+
+    this.audioPool.forEach((item, id) => {
+      if (item.tag === tag) {
+        arr.push(id);
+      }
+    });
+
+    arr.forEach((id) => {
+      this.stop(id);
+    });
   }
 
-  private async dataProcessing(
-    path: string,
-    cb?: (id: number) => void,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-
-  private async dataProcessing(
-    audio: cc.AudioClip,
-    cb?: (id: number) => void,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-
-  private async dataProcessing(
-    assetProperty: FW.AssetProperty,
-    cb?: (id: number) => void,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-
-  private async dataProcessing(
-    path: string,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-  private async dataProcessing(
-    music: cc.AudioClip,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-  private async dataProcessing(
-    assetProperty: FW.AssetProperty,
-    volume?: number,
-    loop?: boolean,
-  ): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }>;
-  private async dataProcessing(): Promise<{
-    clip: cc.AudioClip;
-    volume: number;
-    loop: boolean;
-    cb: (id: number) => void;
-  }> {
-    let clip: cc.AudioClip;
-    if (typeof arguments[0] === 'string') {
-      const bundle = FW.Entry.bundleName;
-      const path = arguments[0];
-      clip = await FW.Entry.resMgr.loadAsset<cc.AudioClip>(<FW.AssetProperty>{
-        path: path,
-        bundle: bundle,
-      });
-    } else if (typeof arguments[0] === 'object') {
-      const bundle = (arguments[0] as FW.AssetProperty).bundle || FW.Entry.bundleName;
-      const path = (arguments[0] as FW.AssetProperty).path;
-      clip = await FW.Entry.resMgr.loadAsset<cc.AudioClip>(<FW.AssetProperty>{
-        path: path,
-        bundle: bundle,
-      });
-    } else if (arguments[0] instanceof cc.AudioClip) {
-      clip = arguments[0];
+  /**
+   * 处理音频参数
+   */
+  private async processAudioArguments(
+    args: IArguments,
+    type: FWSystemDefine.FWAudioType,
+  ): Promise<FWAudioData> {
+    const audioData = new FWAudioData();
+    const argsArray = Array.from(args);
+
+    if (argsArray[0] instanceof cc.AudioClip) {
+      audioData.clip = argsArray[0];
+    } else {
+      const assetProperty = this.normalizeAssetProperty(argsArray[0]);
+      audioData.clip = await this.loadAudioClip(assetProperty);
     }
 
-    let volume: number;
+    if (type === FWSystemDefine.FWAudioType.MUSIC) {
+      audioData.volume = argsArray[1];
+      audioData.loop = argsArray[2];
+    } else {
+      audioData.cb = argsArray[1];
+      audioData.volume = argsArray[2];
+      audioData.loop = argsArray[3];
+      audioData.tag = argsArray[4];
+    }
 
-    let loop: boolean;
+    return audioData;
+  }
 
-    let cb: (id: number) => void;
-    if (typeof arguments[1] === 'function') {
-      cb = arguments[1];
-    } else if (typeof arguments[1] === 'number') {
-      volume = arguments[1];
-    } else if (typeof arguments[1] === 'boolean') {
-      loop = arguments[1];
+  /**
+   * 标准化资源属性
+   */
+  private normalizeAssetProperty(input: any): FW.AssetProperty {
+    if (typeof input === 'string') {
+      return {
+        path: input,
+        bundle: FW.Entry.bundleName,
+      };
     }
+    return input;
+  }
 
-    if (typeof arguments[2] === 'boolean') {
-      loop = arguments[2];
-    } else if (typeof arguments[2] === 'number') {
-      volume = arguments[2];
+  /**
+   * 加载音频片段
+   */
+  private async loadAudioClip(assetProperty: FW.AssetProperty): Promise<cc.AudioClip> {
+    try {
+      return await FW.Entry.resMgr.loadAsset<cc.AudioClip>(assetProperty);
+    } catch (e) {
+      return null;
     }
+  }
 
-    if (arguments.length == 4) {
-      loop = arguments[3];
+  /**
+   * 生成缓存键
+   */
+  private getCacheKey(assetProperty: FW.AssetProperty): string {
+    if (typeof assetProperty === 'string') {
+      return `${FW.Entry.bundleName}_${assetProperty}`;
     }
+    return `${assetProperty.bundle || FW.Entry.bundleName}_${assetProperty.path}`;
+  }
 
-    return {
-      clip: clip,
-      volume: volume,
-      loop: loop,
-      cb: cb,
-    };
+  /**
+   * 获取音频名称
+   */
+  private getAudioName(clip: cc.AudioClip): string {
+    return clip.name || '未知音频';
+  }
+
+  /**
+   * 清理已完成的音频
+   */
+  private clearFinishedAudio(): void {
+    const currentTime = Date.now();
+    const maxAge = 30000;
+
+    this.audioPool.forEach((item, id) => {
+      if (!cc.audioEngine.getState(id)) {
+        this.audioPool.delete(id);
+      } else if (currentTime - item.startTime > maxAge) {
+        FWLog.warn(`强制停止超时音频: ID ${id}`);
+        this.stop(id);
+      }
+    });
+  }
+
+  /**
+   * 启动自动清理
+   */
+  private autoClear(): void {
+    FW.Entry.timeMgr.schedule(
+      this.clearFinishedAudio,
+      this.cleanupInterval,
+      cc.macro.REPEAT_FOREVER,
+      this,
+    );
   }
 
   public onDestroy(): void {

package/manager/FWBundleManager.ts

@@ -1,6 +1,7 @@
 import { FWManager } from './FWManager';
 import FWLog from '../log/FWLog';
 import Framework from '../Framework';
+import { FWSystemConfig } from '../config/FWSystemConfig';
 
 export class FWBundleManager extends FWManager implements FW.BundleManager {
   bundleMap: Map<string, cc.AssetManager.Bundle>;
@@ -31,11 +32,8 @@ export class FWBundleManager extends FWManager implements FW.BundleManager {
     if (!bundleName) return;
     if (this.bundleMap.has(bundleName)) return this.bundleMap.get(bundleName);
 
-    return new Promise(
-      (
-        resolve: (value: cc.AssetManager.Bundle | PromiseLike<cc.AssetManager.Bundle>) => void,
-        reject: (reason?: any) => void,
-      ) => {
+    return await this.invoke(
+      FW.Entry.promiseMgr.execute((resolve, reject, signal) => {
         const remote = this.remoteBundleConfigMap.get(bundleName);
         const url = remote ? remote.url : '';
         const path = `${url}${bundleName}`;
@@ -54,7 +52,8 @@ export class FWBundleManager extends FWManager implements FW.BundleManager {
             resolve(bundle);
           },
         );
-      },
+      }, FWSystemConfig.PromiseConfig.loadBundle).promise,
+      `loadBundle -> ${bundleName}`,
     );
   }
 

package/manager/FWEventManager.ts

@@ -18,6 +18,7 @@ class FWObserver implements FW.Observer {
     private readonly target: FW.TargetType,
     public readonly priority: number,
     public readonly intercept: boolean,
+    public readonly once: boolean = false,
   ) {
     this.cb = cb;
     this.target = target;
@@ -55,6 +56,7 @@ class FWObserver implements FW.Observer {
       args10,
     );
   }
+
   /**
    * 目标比较
    * @param target 目标对象
@@ -115,14 +117,31 @@ export default class FWEventManager implements FW.EventManager {
   ) {
     const observers = this.listeners[eventName];
     if (!observers) return;
+
     let shouldStopPropagation = false;
-    for (const observer of observers) {
+    const observersToRemove: FW.Observer[] = [];
+
+    const observersCopy = [...observers];
+
+    for (const observer of observersCopy) {
       if (shouldStopPropagation) break;
+
+      if (observers.indexOf(observer) === -1) continue;
+
       observer.notify(args1, args2, args3, args4, args5, args6, args7, args8, args9, args10);
+
+      if (observer.once) {
+        observersToRemove.push(observer);
+      }
+
       if (observer.intercept) {
         shouldStopPropagation = true;
       }
     }
+
+    if (observersToRemove.length > 0) {
+      this.removeObservers(eventName, observersToRemove);
+    }
   }
 
   /**
@@ -149,20 +168,26 @@ export default class FWEventManager implements FW.EventManager {
     options?: {
       priority?: FWSystemDefine.FWPriorityOrder;
       intercept?: boolean;
+      once?: boolean;
     },
   ) {
     const observers = this.listeners[eventName];
     const define = FWSystemDefine.FWPriorityOrder;
     const priority = options?.priority === undefined ? define.NORMAL : options.priority;
     const intercept = options?.intercept === undefined ? false : options.intercept;
-    const observer = new FWObserver(eventName, cb, target, priority, intercept);
+    const once = options?.once === undefined ? false : options.once;
+
+    const observer = new FWObserver(eventName, cb, target, priority, intercept, once);
+
     if (!observers) {
       this.listeners[eventName] = [];
     }
+
     const order = Object.values(define);
     const insertIndex = this.listeners[eventName].findIndex(
       (o) => order[o.priority] > order[priority],
     );
+
     if (insertIndex === -1) {
       this.listeners[eventName].push(observer);
     } else {
@@ -170,6 +195,39 @@ export default class FWEventManager implements FW.EventManager {
     }
   }
 
+  /**
+   * 注册一次性事件
+   * @param eventName 事件名
+   * @param cb 回调函数
+   * @param target 事件回调绑定目标
+   * @param options 选项
+   */
+  public registerOnce(
+    eventName: string | number,
+    cb: (
+      args1?: FW.EventManagerArgs,
+      args2?: FW.EventManagerArgs,
+      args3?: FW.EventManagerArgs,
+      args4?: FW.EventManagerArgs,
+      args5?: FW.EventManagerArgs,
+      args6?: FW.EventManagerArgs,
+      args7?: FW.EventManagerArgs,
+      args8?: FW.EventManagerArgs,
+      args9?: FW.EventManagerArgs,
+      args10?: FW.EventManagerArgs,
+    ) => void,
+    target: FW.TargetType,
+    options?: {
+      priority?: FWSystemDefine.FWPriorityOrder;
+      intercept?: boolean;
+    },
+  ) {
+    this.register(eventName, cb, target, {
+      ...options,
+      once: true, // 强制设置为一次性事件
+    });
+  }
+
   /**
    * 注销事件
    * @param eventName
@@ -268,6 +326,37 @@ export default class FWEventManager implements FW.EventManager {
     });
   }
 
+  /**
+   * 移除指定的观察者列表
+   * @param eventName 事件名
+   * @param observersToRemove 待移除的观察者列表
+   */
+  private removeObservers(eventName: string | number, observersToRemove: FW.Observer[]): void {
+    const observers = this.listeners[eventName];
+    if (!observers) return;
+
+    for (const observerToRemove of observersToRemove) {
+      const index = observers.indexOf(observerToRemove);
+      if (index !== -1) {
+        observers.splice(index, 1);
+      }
+    }
+
+    if (observers.length === 0) {
+      delete this.listeners[eventName];
+    }
+  }
+
+  /**
+   * 获取事件监听器数量
+   * @param eventName 事件名
+   * @returns 监听器数量
+   */
+  public getListenerCount(eventName: string | number): number {
+    const observers = this.listeners[eventName];
+    return observers ? observers.length : 0;
+  }
+
   /** 销毁 */
   public onDestroy(): void {
     this.listeners = cc.js.createMap();