keytops-game-framework 1.0.0

package/dist/app/module/analytics/level/GameDimension.d.ts

@@ -0,0 +1,39 @@
+import { AnalyticsData } from "../AnalyticsAble";
+import { BaseDimension } from "../BaseDimension";
+import { LevelStatsDimension } from "./LevelStatsDimension";
+import { LevelSnapshot, PlayerAbilityDimension, PropSupport } from "./PlayerAbilityDimension";
+export declare const DEFAULT_GAME_FLAG = "default";
+export type GameDimensionRuntimeState = Record<string, unknown>;
+export declare class GameDimension extends BaseDimension {
+    private readonly _gameFlag;
+    private readonly _levelStats;
+    private readonly _playerAbility;
+    private _levelHistory;
+    private _currentLevelSession;
+    private _currentEnterParams;
+    constructor(gameFlag?: string);
+    private getHistoryStorageKey;
+    private _loadLevelHistory;
+    private _saveLevelHistory;
+    private _trimHistoryWindow;
+    private _createLevelSession;
+    get gameFlag(): string;
+    get levelStats(): LevelStatsDimension;
+    get playerAbility(): PlayerAbilityDimension;
+    getLevelHistory(): LevelSnapshot[];
+    getCurrentLevelSession(): LevelSnapshot | null;
+    getCurrentBehaviorContext(): AnalyticsData | null;
+    onLevelStart(id: string, index: number, data: AnalyticsData): void;
+    private _leaveApp;
+    private _resumeApp;
+    private _onLevelPause;
+    private _onLevelResume;
+    onLevelEnd(isSuccess: boolean): void;
+    onLevelMove(progress: number, remainingResourceRatio?: number): void;
+    onPropUse(prop: PropSupport): void;
+    onPropUseCustom(weight: number): void;
+    private _onLevelFirstSuccessAction;
+    discardCurrentLevelSession(): void;
+    getMetrics(order?: string[]): number[];
+    clear(): void;
+}

package/dist/app/module/analytics/level/LevelAnalyticsAble.d.ts

@@ -0,0 +1,86 @@
+import { GameDimension } from "./GameDimension";
+import { PropSupport } from "./PlayerAbilityDimension";
+import { AnalyticsAble, AnalyticsData } from "../AnalyticsAble";
+export declare class LevelAnalyticsAble {
+    private _baseAble;
+    private _games;
+    private _gameReporters;
+    private _currentGame;
+    constructor(baseAble: AnalyticsAble);
+    get currentGame(): GameDimension;
+    /**
+     * 获取指定玩法的维度数据
+     * @param gameFlag 玩法标识
+     * @returns 玩法维度数据
+     */
+    getGameMetrics(gameFlag?: string): Record<string, number[]>;
+    /**
+     * 获取指定玩法的维度
+     * @param gameFlag 玩法标识
+     * @returns 玩法维度
+     */
+    private _game;
+    private _behaviorReporter;
+    /**
+     * 开始关卡
+     * @param id 关卡ID
+     * @param index 关卡索引
+     * @param gameFlag 关卡所属玩法标识
+     * @param params 关卡参数, 会从端口下发的配置level_config中获取, 也允许手动指定，其他未指定的字段会采用配置中的值。
+     */
+    onStart(id: string, index: number, gameFlag?: string, data?: Omit<AnalyticsData, 'id' | 'index' | 'type' | 'progress' | 'code'>): Promise<void>;
+    /**
+     * 记录用户操作(包括有效和无效操作)
+     * @param progress 关卡进度 0.0 - 1.0
+     * @param remainingResourceRatio 剩余资源百分比，比如步数、倒计时等限制性资源的剩余比例，取值范围 0.0 - 1.0
+     */
+    onMove(progress: number, remainingResourceRatio?: number): void;
+    /**
+     * 记录用户使用道具, 自动触发了手势之类的提示也需要记录`PropSupport.HINT`
+     * @param prop 道具类型或者自定义道具权重
+     */
+    onPropUse(prop: PropSupport, data?: AnalyticsData): void;
+    /**
+     * 记录用户使用自定义道具，注意自定义道具权重的合理性
+     * @param name 道具名称
+     * @param weight 道具权重
+     */
+    onPropUseCustom(name: string, weight: number, data?: AnalyticsData): void;
+    /**
+     * 关卡超时
+     * @param data 额外行为上报数据
+     */
+    onTimeout(data?: AnalyticsData): void;
+    /**
+     * 关卡结束
+     * @param leaveType 离开类型 GameLeaveType.success | GameLeaveType.fail | GameLeaveType.skip | GameLeaveType.leave
+     * @param data 额外行为上报数据
+     */
+    private onEnd;
+    onSuccess(data?: AnalyticsData): void;
+    /**
+     * 关卡跳过
+     * @param data 额外行为上报数据
+     */
+    onSkip(data?: AnalyticsData): void;
+    /**
+     * 关卡失败
+     * @param data 额外行为上报数据
+     */
+    onFail(data?: AnalyticsData): void;
+    /**
+     * 关卡复活
+     * @param data 额外行为上报数据
+     */
+    onRevive(data?: AnalyticsData): void;
+    /**
+     * 关卡返回
+     * @param data 额外行为上报数据
+     */
+    onBreak(data?: AnalyticsData): void;
+    /**
+     * 关卡重试
+     * @param data 额外行为上报数据
+     */
+    onRetry(data?: AnalyticsData): void;
+}

package/dist/app/module/analytics/level/LevelBehaviorReporter.d.ts

@@ -0,0 +1,29 @@
+import { AnalyticsAble, AnalyticsData } from "../AnalyticsAble";
+import { GameDimension } from "../level/GameDimension";
+export declare enum GameLeaveType {
+    success = "lv_success",
+    fail = "lv_fail",
+    leave = "lv_leave",
+    skip = "lv_skip",
+    revive = "lv_revive",
+    break = "lv_break",
+    retry = "lv_retry"
+}
+/**
+ * 关卡行为自动上报器
+ * 只依赖 GameDimension 的只读会话上下文，不维护独立状态。
+ */
+export declare class LevelBehaviorReporter {
+    private readonly _game;
+    private baseAble;
+    constructor(_game: GameDimension, baseAble: AnalyticsAble);
+    start(): void;
+    end(type: GameLeaveType, data?: AnalyticsData): void;
+    reportLeave(data?: AnalyticsData): void;
+    reportTimeout(data?: AnalyticsData): void;
+    reportItem(name: string, data?: AnalyticsData): void;
+    reset(): void;
+    private _leaveApp;
+    private _setTimers;
+    private _getContext;
+}

package/dist/app/module/analytics/level/LevelStatsDimension.d.ts

@@ -0,0 +1,70 @@
+import { BaseDimension } from "../BaseDimension";
+export declare const LEVEL_STATS_METRIC_ORDER_V1: readonly ["LEVEL_STATS.launch_avg_enters_ma", "LEVEL_STATS.launch_avg_completes_ma", "LEVEL_STATS.daily_avg_enters_ma", "LEVEL_STATS.daily_avg_completes_ma", "LEVEL_STATS.launch_avg_enters_trend", "LEVEL_STATS.launch_avg_completes_trend", "LEVEL_STATS.daily_avg_enters_trend", "LEVEL_STATS.daily_avg_completes_trend", "LEVEL_STATS.first_launch_enters", "LEVEL_STATS.first_launch_completes", "LEVEL_STATS.first_day_enters", "LEVEL_STATS.first_day_completes", "LEVEL_STATS.yesterday_launch_avg_enters", "LEVEL_STATS.yesterday_launch_avg_completes", "LEVEL_STATS.yesterday_total_enters", "LEVEL_STATS.yesterday_total_completes", "LEVEL_STATS.today_launch_avg_enters", "LEVEL_STATS.today_launch_avg_completes", "LEVEL_STATS.today_total_enters", "LEVEL_STATS.today_total_completes"];
+export declare class LevelStatsDimension extends BaseDimension {
+    private levelStats;
+    private readonly gameFlag;
+    constructor(gameFlag: string);
+    getMetrics(order?: string[]): number[];
+    /** 加载字符串数据 */
+    private _loadStringData;
+    /** 保存字符串数据 */
+    private _saveStringData;
+    /** 加载关卡统计数据 */
+    private _loadLevelStats;
+    /** 保存关卡统计数据 */
+    private _saveLevelStats;
+    /** 创建默认的关卡统计数据 */
+    private _createDefaultLevelStats;
+    clear(): void;
+    /** 初始化当前启动 */
+    private _initializeCurrentLaunch;
+    /** 初始化新的启动 */
+    private _initializeNewLaunch;
+    /** 获取今天开始时间 */
+    private _getTodayStart;
+    private get currentLaunchActionData();
+    private get currentLaunchEnters();
+    private set currentLaunchEnters(value);
+    private get currentLaunchCompletes();
+    private set currentLaunchCompletes(value);
+    private get todayLevelActionData();
+    private get todayTotalEnters();
+    private set todayTotalEnters(value);
+    private get todayTotalCompletes();
+    private set todayTotalCompletes(value);
+    private get todayLaunchTimes();
+    private get todayLaunchAvgCompletes();
+    private get todayLaunchAvgEnters();
+    private get yesterLevelActionData();
+    private get yesterdayLaunchTimes();
+    private get yesterdayTotalEnters();
+    private get yesterdayTotalCompletes();
+    private get yesterdayLaunchAvgEnters();
+    private get yesterdayLaunchAvgCompletes();
+    /** 记录关卡进入 */
+    recordLevelEnter(): void;
+    /** 记录关卡完成 */
+    recordLevelComplete(): void;
+    /** 计算每日平均关卡进入次数的滑动平均值 */
+    private calculateDailyAvgEntersMovingAverage;
+    /** 计算每日平均关卡完成次数的滑动平均值 */
+    private calculateDailyAvgCompletesMovingAverage;
+    /**
+     * 计算每日平均关卡进入次数的趋势斜率
+     */
+    private calculateDailyAvgEntersTrend;
+    /**
+     * 计算每日平均关卡完成次数的趋势斜率
+     */
+    private calculateDailyAvgCompletesTrend;
+    /** 计算启动次均关卡进入次数的滑动平均值 */
+    private calculateLaunchAvgEntersMovingAverage;
+    /** 计算启动次均关卡完成次数的滑动平均值 */
+    private calculateLaunchAvgCompletesMovingAverage;
+    /** 计算启动次均关卡进入次数的趋势斜率 */
+    private calculateLaunchAvgEntersTrend;
+    /** 计算启动次均关卡完成次数的趋势斜率 */
+    private calculateLaunchAvgCompletesTrend;
+    /** 从数组计算趋势斜率 */
+    private _calculateTrendSlopeFromArray;
+}

package/dist/app/module/analytics/level/PlayerAbilityDimension.d.ts

@@ -0,0 +1,147 @@
+import { BaseDimension } from "../BaseDimension";
+export declare const PLAYER_ABILITY_METRIC_ORDER_V1: readonly ["PLAYER_ABILITY.avg_redundancy_pct", "PLAYER_ABILITY.redundancy_trend_pct", "PLAYER_ABILITY.near_miss_rate_pct", "PLAYER_ABILITY.failure_slope_pct", "PLAYER_ABILITY.support_dependency_pct", "PLAYER_ABILITY.mental_load_pct", "PLAYER_ABILITY.net_skill_pct", "PLAYER_ABILITY.latest_level_fail_count", "PLAYER_ABILITY.latest_level_avg_fail_progress", "PLAYER_ABILITY.consecutive_fail_count", "PLAYER_ABILITY.effective_move_ratio_pct"];
+/** 内部定义的权重常数，避免对接人员写错 */
+export declare enum PropSupport {
+    /**
+     * 自动提示
+     */
+    HINT = "HINT",
+    /**
+     * 普通道具（锤子等）
+     */
+    ITEM_NORMAL = "ITEM_NORMAL",
+    /**
+     * 改变关卡整体难度类型的道具（全局洗牌等）
+     */
+    ITEM_SHUFFLE = "ITEM_SHUFFLE",
+    /**
+     * 复活，补充时间/步骤等道具（最高压力信号）
+     */
+    REVIVE = "REVIVE"
+}
+/** 单次关卡原始快照 */
+export interface LevelSnapshot {
+    /** 关卡ID */
+    levelId: string;
+    /** 玩家接触到关卡的顺序 */
+    levelIndex: number;
+    /** 剩余资源百分比，比如步数、倒计时等限制性资源的剩余比例，取值范围 0.0 - 1.0 */
+    remainingResourceRatio: number;
+    /** 开始时间戳 */
+    startTime: number;
+    /** 是否成功通关 */
+    isSuccess: boolean;
+    /** 玩家操作总次数 */
+    movesCount: number;
+    /** 玩家有效操作次数 */
+    stepsUsed: number;
+    /** 关卡进度 0.0 - 1.0 */
+    progress: number;
+    /** 决策耗时（总思考时间）（毫秒，需剔除切出挂机时间） 不包括广告播放时间*/
+    thinkTimeTotal: number;
+    /** 触发并跟随系统提示的次数 */
+    hintsFollowed: number;
+    /**
+     * 本局道具总权重分
+     * 含义：
+     * 代表“外部助力对通关贡献的总权重”，用于把提示、道具、复活等对真实能力的粉饰剥离掉。
+     *
+     * 推荐权重：
+     * HINT = 0.2
+     * ITEM_NORMAL = 1.0
+     * ITEM_SHUFFLE = 1.5
+     * REVIVE = 2.5
+     */
+    supportTotalWeight: number;
+    /** 是否处于暂停态 */
+    isPaused: boolean;
+    /** 最近一次有效行为时间 */
+    lastActionTime: number;
+    /** 从开局到首次有效正反馈的耗时（毫秒） */
+    timeToFirstSuccessAction: number;
+}
+/** 共享历史读取接口。GameDimension 持有原始历史时，由它实现并注入给分析器。 */
+export interface PlayerAbilityHistorySource {
+    getLevelHistory(): LevelSnapshot[];
+    getCurrentLevelSession(): LevelSnapshot | null;
+}
+export declare class PlayerAbilityDimension extends BaseDimension {
+    private readonly windowSize;
+    private readonly noiseSec;
+    private readonly gameFlag;
+    private readonly source?;
+    constructor(gameFlag: string, source: PlayerAbilityHistorySource);
+    static getSupportWeight(type: PropSupport): number | undefined;
+    static normalizeSnapshot(item: any): LevelSnapshot;
+    private getHistorySnapshots;
+    /**
+     * 计算失败趋势斜率
+     * 口径：
+     * 先按 levelIndex 聚合失败次数，再做线性回归，观察随着关卡推进失败压力是上升还是下降。
+     */
+    private calculateFailureSlope;
+    /**
+     * 计算成功关卡的平均冗余度
+     * 冗余度越高，代表玩家越“游刃有余”。
+     */
+    private calculateAvgRedundancy;
+    /**
+     * 计算最近成功关的冗余度趋势
+     * 斜率为正，表示玩家在最近几个成功关里越打越轻松。
+     */
+    private calculateRedundancyTrend;
+    /**
+     * 计算外部助力依赖度
+     * 口径：
+     * 总助力权重 / (总消耗步数 / 10)
+     * 用于描述玩家通关过程对提示、道具、复活等外部系统的依赖程度。
+     */
+    private calculateSupportDependency;
+    /**
+     * 计算惜败率
+     * 定义：
+     * 失败局中 progress > 0.8 的占比。
+     * 这个指标常用于识别“差一点就能过”的关卡压力状态。
+     */
+    private calculateNearMissRate;
+    /**
+     * 计算心智负荷
+     * 口径：
+     * (平均单步思考时长 * 0.7) + (提示依赖度 * 0.3)
+     * 用于描述玩家在关卡过程中的认知压力，而不是结果表现本身。
+     */
+    private calculateMentalLoad;
+    /**
+     * 计算净实力
+     * 口径：
+     * 冗余度 / (1 + supportTotalWeight)
+     * 含义：
+     * 尝试把“玩家本身的表现”和“外部助力带来的粉饰”拆开。
+     */
+    private calculateNetSkill;
+    /**
+     *  计算有效操作的占比
+     * 口径：
+     * stepsUsed / movesCount
+     * 含义：
+     * 描述玩家在关卡中实际使用的操作次数占总操作次数的比例。
+     **/
+    private calculateEffectiveMoveRatio;
+    /**
+     * 计算最近连续失败次数
+     * 从最新一局往前数，直到遇到最近一次成功为止。
+     */
+    private calculateConsecutiveFails;
+    /** 获取某个关卡的全部历史尝试 */
+    getLevelAttempts(levelId: string): LevelSnapshot[];
+    /** 获取某个关卡的失败次数 */
+    getLevelFailCount(levelId: string): number;
+    /** 获取某个关卡的成功次数 */
+    getLevelSuccessCount(levelId: string): number;
+    /**
+     * 输出 PLAYER_ABILITY 维度指标
+     * 注意：
+     * 这里的数组顺序要与后端 catalog 的 index 保持稳定映射，不要随意调整已有位置。
+     */
+    getMetrics(order?: string[]): number[];
+}

package/dist/app/module/analytics/session/SessionAnalyticsAble.d.ts

@@ -0,0 +1,9 @@
+import { AnalyticsAble } from "../AnalyticsAble";
+export declare class SessionAnalyticsAble {
+    private _baseAble;
+    private _dimension;
+    constructor(baseAble: AnalyticsAble);
+    recordLogin(): void;
+    updateSessionDuration(): void;
+    getMetrics(): number[];
+}

package/dist/app/module/analytics/session/SessionDimension.d.ts

@@ -0,0 +1,48 @@
+import { BaseDimension } from "../BaseDimension";
+/**
+ * 活跃维度，可以记录：
+ * - 登录次数、登录天数
+ * - 总时长、最大时长、上次记录时长、今日在线时长、每日平均在线时长
+ * - 连续天数、最大连续天数、最后登录天数
+ * - 早晨时长、下午时长、傍晚时长、夜晚时长
+ * - 活跃趋势指数（基于EMA计算，-100到100，正值表示上升趋势）
+ */
+export declare class SessionDimension extends BaseDimension {
+    private _currSessionDuration;
+    constructor();
+    recordLogin(): void;
+    /**
+     * 根据时长增量记录到对应的时间段
+     */
+    private _recordTimeSlot;
+    /**
+     * 更新当前会话的在线时长
+     */
+    updateSessionDuration(): void;
+    private get loginCount();
+    private get loginDays();
+    /**
+     * 获取今日在线时长（秒）
+     */
+    private get todayDuration();
+    /**
+     * 更新指数移动平均（EMA）
+     * 使用 α = 0.3 的平滑系数，更重视近期数据
+     */
+    private _updateEMA;
+    /**
+     * 获取每天的平均在线时长（秒）
+     */
+    private get avgDurationOfDay();
+    /**
+     * 获取活跃趋势指数（-100 到 100）
+     * 正值表示上升趋势，负值表示下降趋势，0表示稳定
+     */
+    private get trendIndex();
+    /**
+     * 获取时间分布（基于在线时长）
+     * 返回格式：早晨占比(百万位) + 下午占比(万位) + 傍晚占比(百位) + 夜晚占比(个位)
+     */
+    private _getTimeDistribution;
+    getMetrics(order?: string[]): number[];
+}

package/dist/app/module/analytics/social/SocialAnalyticsAble.d.ts

@@ -0,0 +1,14 @@
+import { AnalyticsAble } from "../AnalyticsAble";
+import { AnalyticsData } from "../AnalyticsAble";
+export declare class SocialAnalyticsAble {
+    private _baseAble;
+    private _socialDimension;
+    constructor(baseAble: AnalyticsAble);
+    recordShare(data: AnalyticsData): void;
+    recordInvite(success?: boolean): void;
+    recordFriendAdd(count?: number): void;
+    recordInteraction(): void;
+    recordSubscribeShow(name: string): void;
+    recordSubscribe(name: string, code: number): void;
+    getMetrics(): number[];
+}

package/dist/app/module/analytics/social/SocialDimension.d.ts

@@ -0,0 +1,14 @@
+import { BaseDimension } from "../BaseDimension";
+/**
+ * 社交维度
+ */
+export declare class SocialDimension extends BaseDimension {
+    constructor();
+    recordShare(): void;
+    recordInvite(success?: boolean): void;
+    recordFriendAdd(count?: number): void;
+    recordInteraction(): void;
+    get shareCount(): number;
+    get inviteSuccessRate(): number;
+    getMetrics(): number[];
+}

package/dist/app/module/bidding/Bidding.d.ts

@@ -0,0 +1,37 @@
+declare class Bidding {
+    private _enabled;
+    /**
+     * 启用
+     */
+    enable(): void;
+    /**
+     * 是否已启用
+     */
+    get enabled(): boolean;
+    /**
+     * 手动上报激励视频广告曝光行为
+     * 默认情况下会自动上报
+     * @returns
+     */
+    onAdShow(): Promise<boolean>;
+    /**
+     * 手动上报激励视频广告完播行为
+     * 默认情况下会自动上报
+     * @param isEnd 是否完整播放
+     * @returns
+     */
+    onAdComplete(isEnd: boolean): Promise<boolean>;
+    /**
+     * 上报其他自定义玩家行为
+     * 可以根据游戏投放需求自主定义行为类型编号。此编号对应投放策略中的行为类型。
+     * @param type 行为类型编号，除去内置事件（1：激励视频曝光;2：激励视频完播;3：激励视频被手动关闭）以外的行为编号。
+     * @returns
+     */
+    onEvent(type: number): Promise<boolean>;
+}
+/**
+ * 直投系统
+ * - 使用前需要调用enable()
+ */
+export declare const bidding: Bidding;
+export {};

package/dist/app/module/business/BusinessCenter.d.ts

@@ -0,0 +1,33 @@
+import { IBusiness } from "./IBusiness";
+export declare class BusinessCenter {
+    private _businessMap;
+    private static created;
+    constructor();
+    /**
+     * 同时初始化多个事务，多用在APP\Game启动时
+     * @param businessClassList
+     */
+    init(businessClassList: {
+        new (): IBusiness;
+    }[]): void;
+    start(businessClass: {
+        new (): IBusiness;
+    }, ...args: any[]): IBusiness;
+    get<T extends IBusiness>(businessClass: {
+        new (): T;
+    }): T;
+    stop(businessClass: {
+        new (): IBusiness;
+    }): void;
+    pause(businessClass: {
+        new (): IBusiness;
+    }): void;
+    release(businessClass: {
+        new (): IBusiness;
+    }): boolean;
+    destroy(): void;
+}
+/**
+ * 事务中心，用于增加常驻逻辑，例如基础网络链接的心跳，业务逻辑中服务器的消息推送等
+ */
+export declare const businessCenter: BusinessCenter;

package/dist/app/module/business/IBusiness.d.ts

@@ -0,0 +1,6 @@
+export interface IBusiness {
+    start(): IBusiness;
+    stop(): void;
+    pause(): void;
+    release(): void;
+}

package/dist/app/module/business/RewardVideoMaskBusiness.d.ts

@@ -0,0 +1,18 @@
+import { IBusiness } from "./IBusiness";
+/**
+ * 广告播放过程中的交互遮罩逻辑
+ */
+export declare class RewardVideoMaskBusiness implements IBusiness {
+    private _started;
+    start(): IBusiness;
+    private _onLoad;
+    private _onLoadComplete;
+    private _onLoadFail;
+    private _onShow;
+    private _onShowComplete;
+    private _onShowFail;
+    private _onCloseByUser;
+    stop(): void;
+    pause(): void;
+    release(): void;
+}