@chiyou/minigame-framework 1.3.0 → 1.3.2

package/src/Framework/Definition/UIDefinition.ts

@@ -2,4 +2,10 @@
 export enum ToastDuration {
     Duration_Short = 1,
     Duration_Long = 2,
+}
+
+export enum ToastPosition {
+    Top = 0,
+    Center = 1,
+    Bottom = 2,
 }

package/src/Framework/Manager/AnalyticsMgr.ts

@@ -0,0 +1,351 @@
+import { BaseMgr } from "./BaseMgr";
+import { LogUtils } from "../Utils/LogUtils";
+import { ServiceLocator } from "../Utils/ServiceLocator";
+import { FwkErrorCode } from "../Definition/FwkErrorDefinition";
+import { PlatformID } from "../Definition/SystemDefinition";
+import { UmengConfig, EventParams, UserProperties, AnalyticsEventId, AnalyticsParamKey } from "../Definition/AnalyticsDefinition";
+import { UmaInitConfig, UmaSDK, uma as wxUma } from "../SDK/Umeng/umtrack-wx-game";
+// 后续新增平台 SDK 在此导入，例如：
+// import { uma as ttUma } from "../SDK/Umeng/umtrack-tt-game";
+
+export class AnalyticsMgr extends BaseMgr {
+    /** 单例实例 */
+    public static Instance: AnalyticsMgr = null;
+    /** 日志标签 */
+    static TAG: string = "AnalyticsMgr";
+
+    /** 是否已初始化 */
+    private _isInited: boolean = false;
+    /** 是否启用统计 */
+    private _isEnabled: boolean = false;
+    /** 友盟配置 */
+    private _umengConfig: UmengConfig = null;
+    /** 当前平台的 appKey */
+    private _appKey: string = "";
+    /** 当前平台对应的 SDK 实例 */
+    private _sdk: UmaSDK = null;
+    /** 当前页面名称（用于 trackPageStart/End 配对） */
+    private _currentPage: string = "";
+
+    /**
+     * 平台 → SDK 实例映射
+     * 新增平台时：
+     * 1. 在 SDK/Umeng/ 下添加对应的 SDK 文件
+     * 2. 在顶部 import 并在此注册
+     */
+    private static _sdkMap: Map<PlatformID, UmaSDK> = new Map([
+        [PlatformID.ID_MiniGame_WeiXin, wxUma],
+        // 新增平台示例：
+        // [PlatformID.ID_MiniGame_DouYin, ttUma],
+    ]);
+
+    onLoad(): void {
+        super.onLoad();
+
+        if (AnalyticsMgr.Instance === null) {
+            AnalyticsMgr.Instance = this;
+        } else {
+            this.destroy();
+            return;
+        }
+
+        ServiceLocator.Instance.register("AnalyticsMgr", this);
+
+        // 注意：SDK 内部已注册 wx.onShow/onHide 自动调用 resume/pause
+        // 无需在 AnalyticsMgr 监听生命周期事件
+    }
+
+    onDestroy(): void {
+        super.onDestroy();
+    }
+
+    /**
+     * 初始化统计管理器
+     * @param umengConfig 友盟 SDK 配置
+     *
+     * 自动判断当前平台是否在 appKeyMap 中配置了 appKey：
+     * - 有配置 → 启用统计并初始化 SDK
+     * - 无配置 → 禁用统计，跳过初始化
+     */
+    public init(umengConfig: UmengConfig): void {
+        if (this._isInited) {
+            LogUtils.Instance.warn(AnalyticsMgr.TAG, "重复初始化");
+            return;
+        }
+
+        if (!umengConfig) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.ConfigError, {
+                operation: "init",
+                reason: "友盟配置缺失",
+            });
+            this._isInited = true;
+            return;
+        }
+
+        this._umengConfig = umengConfig;
+
+        // 根据当前平台是否配置了 appKey 和 SDK 来决定是否启用
+        const platformID: PlatformID = BaseMgr.Instance.getCurrentPlatformID();
+        const appKey = umengConfig.appKeyMap.get(platformID);
+        const sdk = AnalyticsMgr._sdkMap.get(platformID);
+
+        if (appKey && sdk) {
+            this._appKey = appKey;
+            this._sdk = sdk;
+            this._isEnabled = true;
+            this._initUmeng();
+        } else {
+            this._isEnabled = false;
+            if (!sdk) {
+                LogUtils.Instance.info(AnalyticsMgr.TAG, "当前平台无友盟SDK，统计功能已禁用", {
+                    platformID: PlatformID[platformID],
+                });
+            } else {
+                LogUtils.Instance.info(AnalyticsMgr.TAG, "当前平台未配置友盟appKey，统计功能已禁用", {
+                    platformID: PlatformID[platformID],
+                });
+            }
+        }
+
+        this._isInited = true;
+        LogUtils.Instance.info(AnalyticsMgr.TAG, "初始化完成", {
+            enabled: this._isEnabled,
+            platformID: PlatformID[platformID],
+        });
+    }
+
+    // ==================== 生命周期 ====================
+    // 注意：SDK 内部已自动处理 wx.onShow/onHide 的 resume/pause 调用
+
+    // ==================== 事件上报 ====================
+
+    /**
+     * 上报自定义事件
+     * @param eventId 事件 ID
+     * @param params 事件参数
+     */
+    public trackEvent(eventId: string | AnalyticsEventId, params?: EventParams): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.trackEvent(eventId, params);
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "事件上报", {
+                eventId: eventId,
+            });
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "trackEvent",
+                reason: String(e),
+                eventId: eventId,
+            });
+        }
+    }
+
+    /**
+     * 页面开始追踪
+     * @param pageName 页面名称
+     */
+    public trackPageStart(pageName: string): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.trackPageStart(pageName);
+            this._currentPage = pageName;
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "页面开始", {
+                pageName: pageName,
+            });
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "trackPageStart",
+                reason: String(e),
+                pageName: pageName,
+            });
+        }
+    }
+
+    /**
+     * 页面结束追踪
+     * @param pageName 页面名称
+     */
+    public trackPageEnd(pageName: string): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.trackPageEnd(pageName);
+            this._currentPage = "";
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "页面结束", {
+                pageName: pageName,
+            });
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "trackPageEnd",
+                reason: String(e),
+                pageName: pageName,
+            });
+        }
+    }
+
+    // ==================== 用户追踪 ====================
+
+    /**
+     * 设置用户 ID
+     * @param userId 用户 ID
+     * @param provider 提供商
+     */
+    public setUserId(userId: string, provider?: string): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.setUserid(userId, provider);
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "设置用户ID", {
+                userId: userId,
+                provider: provider,
+            });
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "setUserId",
+                reason: String(e),
+            });
+        }
+    }
+
+    /**
+     * 设置 OpenID
+     * @param openid 微信 openid
+     */
+    public setOpenId(openid: string): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.setOpenid(openid);
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "设置OpenID");
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "setOpenId",
+                reason: String(e),
+            });
+        }
+    }
+
+    /**
+     * 设置用户属性
+     * @param properties 用户属性
+     */
+    public setUserProperties(properties: UserProperties): void {
+        if (!this._isEnabled) return;
+        try {
+            this._sdk.setUserInfo(properties);
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "设置用户属性");
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "setUserProperties",
+                reason: String(e),
+            });
+        }
+    }
+
+    // ==================== 游戏特定事件 ====================
+
+    /** 关卡开始 */
+    public trackLevelStart(level: string | number, extraParams?: EventParams): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.Level]: level,
+            ...this._flattenParams(extraParams),
+        };
+        this.trackEvent(AnalyticsEventId.LevelStart, params);
+    }
+
+    /** 关卡完成 */
+    public trackLevelComplete(level: string | number, score?: number, duration?: number, extraParams?: EventParams): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.Level]: level,
+            ...(score !== undefined ? { [AnalyticsParamKey.Score]: score } : {}),
+            ...(duration !== undefined ? { [AnalyticsParamKey.Duration]: duration } : {}),
+            ...this._flattenParams(extraParams),
+        };
+        this.trackEvent(AnalyticsEventId.LevelComplete, params);
+    }
+
+    /** 关卡失败 */
+    public trackLevelFail(level: string | number, reason?: string, extraParams?: EventParams): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.Level]: level,
+            ...(reason ? { [AnalyticsParamKey.Reason]: reason } : {}),
+            ...this._flattenParams(extraParams),
+        };
+        this.trackEvent(AnalyticsEventId.LevelFail, params);
+    }
+
+    /** 广告展示 */
+    public trackAdShow(adType: string, adId: string, extraParams?: EventParams): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.AdType]: adType,
+            [AnalyticsParamKey.AdId]: adId,
+            ...this._flattenParams(extraParams),
+        };
+        this.trackEvent(AnalyticsEventId.AdShow, params);
+    }
+
+    /** 广告点击 */
+    public trackAdClick(adType: string, adId: string, extraParams?: EventParams): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.AdType]: adType,
+            [AnalyticsParamKey.AdId]: adId,
+            ...this._flattenParams(extraParams),
+        };
+        this.trackEvent(AnalyticsEventId.AdClick, params);
+    }
+
+    /** 分享 */
+    public trackShare(shareType: string, shareContent?: string): void {
+        const params: Record<string, any> = {
+            [AnalyticsParamKey.ShareType]: shareType,
+            ...(shareContent ? { [AnalyticsParamKey.ShareType]: shareContent } : {}),
+        };
+        this.trackEvent(AnalyticsEventId.Share, params);
+    }
+
+    // ==================== 状态查询 ====================
+
+    /** 是否已初始化 */
+    public get isInited(): boolean {
+        return this._isInited;
+    }
+
+    /** 是否启用 */
+    public get isEnabled(): boolean {
+        return this._isEnabled;
+    }
+
+    /** 当前页面 */
+
+    // ==================== 私有方法 ====================
+
+    /** 初始化友盟 SDK */
+    private _initUmeng(): void {
+        try {
+            const sdkConfig: UmaInitConfig = {
+                appKey: this._appKey,
+                useOpenid: this._umengConfig.useOpenid,
+                autoGetOpenid: this._umengConfig.autoGetOpenid,
+                debug: this._umengConfig.debug,
+            };
+            this._sdk.init(sdkConfig);
+            LogUtils.Instance.info(AnalyticsMgr.TAG, "友盟SDK初始化成功", {
+                appKey: this._appKey,
+                useOpenid: sdkConfig.useOpenid,
+                debug: sdkConfig.debug,
+            });
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKInitFailed, {
+                operation: "_initUmeng",
+                reason: String(e),
+                appKey: this._appKey,
+            });
+        }
+    }
+
+
+
+    /** 展开 EventParams 为普通对象 */
+    private _flattenParams(params?: EventParams): Record<string, any> {
+        if (!params) return {};
+        if (typeof params === 'string') return { value: params };
+        return params as Record<string, any>;
+    }
+}

package/src/Framework/Manager/AudioMgr.ts

@@ -1,4 +1,4 @@
-import { AudioClip, AudioSource } from "cc";
+import { AudioClip, AudioSource, Node } from "cc";
 import { LogUtils } from "../Utils/LogUtils";
 import { PlatformID } from "../Definition/SystemDefinition";
 import { FrameworkBase } from "../Definition/FrameworkBase";
@@ -15,7 +15,9 @@ export class AudioMgr extends BaseMgr {
     static TAG: string = "AudioMgr";
 
     private effectSwitch: boolean = false;
-    private effectAudioSource: AudioSource = null;
+    private effectPool: AudioSource[] = [];
+    /** 音效池最大同时播放数量 */
+    private static readonly EFFECT_POOL_SIZE: number = 8;
 
     private musicSwitch: boolean = false;
     private musicAudioSource: AudioSource = null;
@@ -39,11 +41,11 @@ export class AudioMgr extends BaseMgr {
      * 初始化音频管理器
      */
     public init(): void {
-        this.effectAudioSource = this.node.addComponent(AudioSource);
         this.musicAudioSource = this.node.addComponent(AudioSource);
 
+        this._initEffectPool();
+
         this.effectSwitch = false;
-        this.effectAudioSource.volume = 0;
 
         this.musicSwitch = false;
         this.musicAudioSource.volume = 0;
@@ -163,7 +165,9 @@ export class AudioMgr extends BaseMgr {
         LogUtils.Instance.info(AudioMgr.TAG, "开启音效");
 
         this.effectSwitch = true;
-        this.effectAudioSource.volume = 1;
+        for (let i = 0; i < this.effectPool.length; i++) {
+            this.effectPool[i].volume = 1;
+        }
     }
 
     /** 关闭音效 */
@@ -175,7 +179,52 @@ export class AudioMgr extends BaseMgr {
         LogUtils.Instance.info(AudioMgr.TAG, "关闭音效");
 
         this.effectSwitch = false;
-        this.effectAudioSource.volume = 0;
+        for (let i = 0; i < this.effectPool.length; i++) {
+            this.effectPool[i].volume = 0;
+        }
+    }
+
+    /**
+     * 初始化音效池（内部方法）
+     */
+    private _initEffectPool(): void {
+        for (let i = 0; i < AudioMgr.EFFECT_POOL_SIZE; i++) {
+            let node: Node = new Node("EffectAudio_" + i);
+            node.setParent(this.node);
+            let audioSource: AudioSource = node.addComponent(AudioSource);
+            audioSource.volume = 0;
+            // 监听 ended 事件，播完后清 clip 以便下次复用
+            audioSource.node.on(AudioSource.EventType.ENDED, () => {
+                audioSource.clip = null;
+            });
+            this.effectPool.push(audioSource);
+        }
+    }
+
+    /**
+     * 从池中找空闲 AudioSource 播放音效（内部方法）
+     */
+    private _playEffectWithPool(clip: AudioClip): void {
+        // 找一个当前未在播放的 AudioSource
+        let audioSource: AudioSource = null;
+        for (let i = 0; i < this.effectPool.length; i++) {
+            if (!this.effectPool[i].playing) {
+                audioSource = this.effectPool[i];
+                break;
+            }
+        }
+
+        // 池已满，跳过此次播放
+        if (audioSource === null) {
+            LogUtils.Instance.warn(AudioMgr.TAG, "音效池已满（8个全部占用），跳过此次播放", {
+                operation: "_playEffectWithPool",
+                poolSize: this.effectPool.length
+            });
+            return;
+        }
+
+        audioSource.clip = clip;
+        audioSource.play();
     }
 
     /**
@@ -201,7 +250,7 @@ export class AudioMgr extends BaseMgr {
                 });
                 return;
             }
-            this.effectAudioSource.playOneShot(audioClip);
+            this._playEffectWithPool(audioClip);
         }
     }
 

package/src/Framework/Manager/InputMgr.ts

@@ -625,6 +625,36 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听键盘按下（一次性）
+     * 触发一次后自动移除监听
+     * @param keyCode 按键码（KeyCode），KeyCode.NONE 表示监听所有按键
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceKeyDown(keyCode: KeyCode, callback: (event: EventKeyboard) => void, target: any): void {
+        let onceCallback = (event: EventKeyboard) => {
+            this.offKeyDown(keyCode, onceCallback, target);
+            callback.apply(target, [event]);
+        };
+        this.onKeyDown(keyCode, onceCallback, target);
+    }
+
+    /**
+     * 监听键盘抬起（一次性）
+     * 触发一次后自动移除监听
+     * @param keyCode 按键码（KeyCode），KeyCode.NONE 表示监听所有按键
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceKeyUp(keyCode: KeyCode, callback: (event: EventKeyboard) => void, target: any): void {
+        let onceCallback = (event: EventKeyboard) => {
+            this.offKeyUp(keyCode, onceCallback, target);
+            callback.apply(target, [event]);
+        };
+        this.onKeyUp(keyCode, onceCallback, target);
+    }
+
     /**
      * 判断按键是否处于按下状态
      * @param keyCode 按键码（KeyCode）
@@ -891,6 +921,22 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听按钮点击（一次性）
+     * 触发一次后自动移除监听
+     * @param button 按钮节点
+     * @param callback 回调函数
+     * @param target 回调目标
+     * @param preventAccidental 是否防误触（连续点击），默认 true
+     */
+    public onceButtonClick(button: Node, callback: () => void, target: any, preventAccidental: boolean = true): void {
+        let onceCallback = () => {
+            this.offButtonClick(button, onceCallback, target);
+            callback.apply(target);
+        };
+        this.onButtonClick(button, onceCallback, target, preventAccidental);
+    }
+
     // ==================== 节点触摸事件（对外） ====================
 
     /**
@@ -1019,6 +1065,21 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听节点触摸结束（一次性）
+     * 触发一次后自动移除监听
+     * @param node 节点
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceNodeTouchEnd(node: Node, callback: (touch: Touch) => void, target: any): void {
+        let onceCallback = (touch: Touch) => {
+            this.offNodeTouchEnd(node, onceCallback, target);
+            callback.apply(target, [touch]);
+        };
+        this.onNodeTouchEnd(node, onceCallback, target);
+    }
+
     /**
      * 移除节点触摸事件
      */

package/src/Framework/Manager/NodePoolMgr.ts

@@ -25,6 +25,8 @@ export interface IPoolStatistics {
     nowActiveCount: number;
     /** 历史最大活跃节点数 */
     maxActiveCount: number;
+    /** 当前可用节点数 */
+    availableCount: number;
     /** 最后访问时间 */
     lastAccessTime: number;
 }
@@ -49,6 +51,7 @@ export class PoolInfo {
             reusedCount: 0,
             nowActiveCount: 0,
             maxActiveCount: 0,
+            availableCount: 0,
             lastAccessTime: Date.now(),
         };
     }
@@ -229,8 +232,9 @@ export class NodePoolMgr extends BaseMgr {
                     reusedCount: 0,
                     nowActiveCount: 0,
                     maxActiveCount: 0,
+                    availableCount: 0,
                     lastAccessTime: Date.now(),
-                }
+                };
             }
         }
 
@@ -475,6 +479,13 @@ export class NodePoolMgr extends BaseMgr {
         }
 
         let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
+        if (!poolInfo) {
+            LogUtils.Instance.error(NodePoolMgr.TAG, FwkErrorCode.NodePool.NotFound, {
+                operation: "_destoryNode",
+                poolName: poolName,
+                reason: "节点池信息获取失败"
+            });
+        }
 
         if (this.uiMgr === null) {
             this.uiMgr = ServiceLocator.Instance.get<UIMgr>("UIMgr");
@@ -545,6 +556,52 @@ export class NodePoolMgr extends BaseMgr {
         node.scale = Vec3.ONE;
     }
 
+    /**
+     * 检查节点池是否存在
+     * @param poolName 节点池名称
+     */
+    public hasPool(poolName: string): boolean {
+        return this._poolInfoMap.has(poolName);
+    }
+
+    /**
+     * 获取指定节点池的统计信息
+     * @param poolName 节点池名称
+     */
+    public getPoolStats(poolName: string): IPoolStatistics | null {
+        let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
+        if (!poolInfo) {
+            return null;
+        }
+
+        return {
+            createdCount: poolInfo.statistics.createdCount,
+            reusedCount: poolInfo.statistics.reusedCount,
+            nowActiveCount: poolInfo.statistics.nowActiveCount,
+            maxActiveCount: poolInfo.statistics.maxActiveCount,
+            availableCount: poolInfo.pool.size(),
+            lastAccessTime: poolInfo.statistics.lastAccessTime,
+        };
+    }
+
+    /**
+     * 获取所有节点池的统计信息
+     */
+    public getAllPoolStats(): Map<string, IPoolStatistics> {
+        let result: Map<string, IPoolStatistics> = new Map<string, IPoolStatistics>();
+        this._poolInfoMap.forEach((poolInfo: PoolInfo, poolName: string) => {
+            result.set(poolName, {
+                createdCount: poolInfo.statistics.createdCount,
+                reusedCount: poolInfo.statistics.reusedCount,
+                nowActiveCount: poolInfo.statistics.nowActiveCount,
+                maxActiveCount: poolInfo.statistics.maxActiveCount,
+                availableCount: poolInfo.pool.size(),
+                lastAccessTime: poolInfo.statistics.lastAccessTime,
+            });
+        });
+        return result;
+    }
+
     /** 打印节点池状态（调试用） */
     private _printPoolState(poolName: string): void {
         let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
@@ -573,6 +630,7 @@ export class NodePoolMgr extends BaseMgr {
             reusedCount: poolInfo.statistics.reusedCount,
             nowActiveCount: poolInfo.statistics.nowActiveCount,
             maxActiveCount: poolInfo.statistics.maxActiveCount,
+            availableCount: poolInfo.pool.size(),
             lastAccessTime: poolInfo.statistics.lastAccessTime
         });
     }