keytops-game-framework 1.0.0

package/README.md

@@ -0,0 +1,214 @@
+# keytops-game-framework
+
+`keytops-game-framework` 是面向 Cocos Creator 项目的游戏开发框架，提供应用生命周期、网络通信、平台能力、存储、计时器、ECS、FSM、任务、埋点、视图、资源和音频等基础设施。这个包定位于框架层，适合需要直接使用底层模块和引擎适配能力的项目，不是精简 facade SDK。
+
+## 适用场景
+
+- 使用 Cocos Creator 构建完整游戏项目
+- 需要统一的应用启动、平台接入和模块化基础设施
+- 需要网络、ECS、FSM、埋点、视图和资源管理能力
+- 需要在框架层扩展自定义注入或平台能力
+
+## 安装
+
+```bash
+npm install keytops-game-framework
+```
+
+## 快速开始
+
+```ts
+import { App } from 'keytops-game-framework';
+
+await App.launch({
+    injects: [],
+});
+```
+
+`App.launch()` 会走框架入口，并通过 `cocos.ts` 自动完成 Cocos Creator 相关注入。
+
+## Cocos 注入说明
+
+包根入口会执行 `cocos.ts`，默认注入以下实现：
+
+- `Storage.KEY -> CocosStorageUtils`
+- `Timer.KEY -> TimerImpl`
+- `NativeHelper.KEY -> CocosNativeHelper`
+- `ViewManager.KEY -> CocosViewManager`
+
+这意味着在 Cocos Creator 环境中直接从包根导入并调用 `App.launch()`，即可使用默认的存储、计时器、原生桥接和视图管理实现。
+
+## 主要导出能力
+
+### 应用生命周期与基础设施
+
+- `App`
+- `Application`
+- `Injector`
+- `Event`
+- `EventDispatcher`
+- `Pool`
+
+```ts
+import { App, Injector } from 'keytops-game-framework';
+
+await App.launch({
+    injects: [],
+});
+
+const launchTimes = App.launchTimes;
+const sessionId = App.sessionId;
+```
+
+### 网络与配置
+
+- `net`
+- `NetManager`
+- `Server`
+- `SystemOnlineConfig`
+- `LevelOnlineConfig`
+- `HttpRequest`
+- `Socket`
+
+```ts
+import { net } from 'keytops-game-framework';
+
+net.logable = true;
+await net.http.sendsync('/health', {
+    method: 'get',
+    responseType: 'json',
+});
+```
+
+### Publisher 平台能力
+
+- `publisher`
+- `PublisherManager`
+- `PublisherManagerImpl`
+- `IPublisher`
+- `ILoginAble`
+- `IADAble`
+- `IShareAble`
+- `IPayAble`
+- `IDevice`
+- 平台实现：`WX*`、`TT*`、`KS*`、`MY*`、`Native*`、`TK*`
+
+```ts
+import { publisher } from 'keytops-game-framework';
+
+publisher.enable();
+
+const appId = publisher.appId;
+const deviceInfo = publisher.device.deviceInfo;
+```
+
+### 存储与计时器
+
+- `storage`
+- `Storage`
+- `StorageImpl`
+- `timer`
+- `Timer`
+- `TimerImpl`
+
+```ts
+import { storage, timer } from 'keytops-game-framework';
+
+storage.setGValue('music', true);
+timer.loop(1000, null, () => {
+    console.log('tick');
+});
+```
+
+### ECS / FSM / Task
+
+- `ECS`
+- `ECSManager`
+- `Component`
+- `Entity`
+- `System`
+- `Fsm`
+- `FsmBase`
+- `FsmManager`
+- `Task`
+- `TaskQueue`
+- `TaskSequence`
+
+这些模块适合搭建带状态管理和任务编排的业务逻辑层。
+
+### Analytics
+
+- `analytics`
+- `AnalyticsAble`
+- `KeytopsAnalyticsSender`
+- `ALiAnalyticsSender`
+- `LaunchAnalyticsAble`
+- 关卡、广告、社交、会话等统计能力
+
+```ts
+import { analytics } from 'keytops-game-framework';
+
+analytics.enable(true);
+analytics.base.report('framework_ready', {
+    name: 'boot',
+});
+```
+
+### View / Resource / Audio
+
+- `View`
+- `Scene`
+- `CocosViewManager`
+- `CCSceneLoader`
+- `CCPViewLoader`
+- `ViewControl`
+- `TipsView`
+- `ResourceManager`
+- `AudioManager`
+- `AudioBusiness`
+
+这些模块提供 Cocos Creator 方向的界面、资源和音频能力。
+
+## 扩展方式
+
+### 追加自定义注入
+
+```ts
+import { App } from 'keytops-game-framework';
+
+class CustomService {
+    static KEY = 'CustomService';
+}
+
+await App.launch({
+    injects: [CustomService],
+});
+```
+
+### 扩展新的引擎适配层
+
+如果后续要把同一套框架迁移到其他引擎，推荐参考 `cocos.ts` 的做法：
+
+1. 实现新的 `IApplication`
+2. 为存储、计时器、原生桥接、视图管理等注入对应实现
+3. 通过 `Injector.inject(Application.KEY, NewEngineApplication)` 注册入口
+
+当前这个发布包仍然是以 Cocos Creator 为中心的游戏框架，不建议在 README 中把它表述为“现成支持多引擎发布”的通用产品。
+
+## 构建
+
+```bash
+npm run build
+```
+
+构建产物：
+
+- `dist/index.js`
+- `dist/index.d.ts`
+
+## 注意事项
+
+- 推荐直接从包根导入当前已经公开导出的符号，不要依赖未声明的内部路径
+- `App.launch()` 只接受 `injects`，README 示例不再使用不存在的 `remoteConfig` 或 `enableBidding` 参数
+- 这是游戏框架层，不是 facade SDK；如果只需要 `keytops.init()`、`user`、`config`、`analytics`、`ad`、`level`，请使用 `keytops-game-sdk`
+- 引擎特定实现应依赖框架接口，不应反向耦合业务层

package/dist/app/base/RuntimeApplicationImpl.d.ts

@@ -0,0 +1,22 @@
+import { IApplication } from "./base";
+/**
+ * 通用运行时 Application 实现，不依赖特定引擎。
+ */
+export declare class RuntimeApplicationImpl implements IApplication {
+    private _launched;
+    private _showListeners;
+    private _hideListeners;
+    launch(): void;
+    onShow(call: () => void, caller?: any): void;
+    offShow(call: () => void, caller?: any): void;
+    onHide(call: () => void, caller?: any): void;
+    offHide(call: () => void, caller?: any): void;
+    private _getPublisher;
+    private _onVisibilityChange;
+    private _onFocus;
+    private _onBlur;
+    private _onPageShow;
+    private _onPageHide;
+    private _emitShow;
+    private _emitHide;
+}

package/dist/app/base/base.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 版本号
+ */
+export declare const version: string;
+export interface IApplication {
+    launch(): void;
+    onShow(call: () => void, caller?: any): void;
+    offShow(call: () => void, caller?: any): void;
+    onHide(call: () => void, caller?: any): void;
+    offHide(call: () => void, caller?: any): void;
+}
+/**
+ * 框架接口，由各个引擎实现，处理框架启动等逻辑
+ */
+export declare class Application {
+    static KEY: string;
+    private _installTime;
+    private _lastLaunchTime;
+    private _launchTime;
+    private _launchTimes;
+    private _sessionId;
+    /**
+     * 启动框架
+     * @injects?:any[]  注册类
+     * @enableBidding?:boolean  是否启用直投，默认为false
+     * @returns
+     */
+    launch(data?: {
+        injects?: any[];
+    }): Promise<void>;
+    reset(): void;
+    private _resetLaunchTimes;
+    /**
+     * 注入组件
+     * @param injects
+     */
+    protected _injects(injects: any[]): void;
+    /**
+     * 当前用户是否是登录后第一次启动
+     */
+    get isFirstLaunchOfThisUser(): boolean;
+    /**
+     * 是否是首日
+     */
+    get isFirstDay(): boolean;
+    /**
+     * 是否是第一次启动
+     */
+    get isFirstLaunch(): boolean;
+    /**
+     * 当前的启动时间戳（毫秒）
+     */
+    get launchTime(): number;
+    /**
+     * 上次启动时间戳（毫秒）
+     */
+    get lastLaunchTime(): number;
+    /**
+     * 当前的启动次数，从1开始。
+     */
+    get launchTimes(): number;
+    /**
+     * 当前启动时长（毫秒）
+     */
+    get durationOfLaunch(): number;
+    /**
+     * 安装后的时长(毫秒)
+     */
+    get durationOfInstall(): number;
+    /**
+     * 安装时间（第一次启动时间戳）（毫秒）
+     */
+    get installTime(): number;
+    /**
+     * 安装后的天数（基于24小时周期）
+     */
+    get daysInstall(): number;
+    /**
+     * 安装后经过的日历天数（基于0点，真正的"今天"概念）
+     * 例如：2月1日15:00安装，2月2日14:00时返回1（跨越了1个0点）
+     */
+    get calendarDaysSinceInstall(): number;
+    /**
+     * 安装后的小时数
+     */
+    get hoursInstall(): number;
+    /**
+     * 安装后的分钟数
+     */
+    get minutesInstall(): number;
+    /**
+     * 当前安装的匿名设备ID
+     */
+    get deviceId(): string;
+    /**
+     * 当前会话ID
+     */
+    get sessionId(): string;
+    onShow(call: (...args: any[]) => void, caller?: any): void;
+    offShow(call: (...args: any[]) => void, caller?: any): void;
+    onHide(call: (...args: any[]) => void, caller?: any): void;
+    offHide(call: (...args: any[]) => void, caller?: any): void;
+    /**
+     * 重启
+     */
+    restart(): void;
+    private _impl;
+    private get impl();
+}
+/**
+ * 框架接口
+ */
+export declare const App: Application;

package/dist/app/base/event/Event.d.ts

@@ -0,0 +1,12 @@
+export declare enum Event {
+    START = "LURE.EVENT.START",
+    PROGRESS = "LURE.EVENT.PROGRESS",
+    COMPLETE = "LURE.EVENT.COMPLETE",
+    ERROR = "LURE.EVENT.ERROR",
+    ADD = "LURE.EVENT.ADD",
+    REMOVE = "LURE.EVENT.REMOVE",
+    CLEAR = "LURE.EVENT.CLEAR",
+    OPEN = "LURE.EVENT.OPEN",
+    MESSAGE = "LURE.EVENT.MESSAGE",
+    CLOSE = "LURE.EVENT.CLOSE"
+}

package/dist/app/base/event/EventDispatcher.d.ts

@@ -0,0 +1,66 @@
+/**
+ * <code>EventDispatcher</code> 类是可调度事件的所有类的基类。
+ */
+export declare class EventDispatcher {
+    /**@private */
+    private _events;
+    /**
+     * 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。
+     * @param	type 事件的类型。
+     * @return 如果指定类型的侦听器已注册，则值为 true；否则，值为 false。
+     */
+    hasListener(type: string): boolean;
+    /**
+     * 派发事件。
+     * @param type	事件类型。
+     * @param data	（可选）回调数据。<b>注意：</b>如果是需要传递多个参数 p1,p2,p3,...可以使用数组结构如：[p1,p2,p3,...] ；如果需要回调单个参数 p ，且 p 是一个数组，则需要使用结构如：[p]，其他的单个参数 p ，可以直接传入参数 p。
+     * @return 此事件类型是否有侦听者，如果有侦听者则值为 true，否则值为 false。
+     */
+    event(type: string, data?: any): boolean;
+    /**
+     * 使用 EventDispatcher 对象注册指定类型的事件侦听器对象，以使侦听器能够接收事件通知。
+     * @param type		事件的类型。
+     * @param caller	事件侦听函数的执行域。
+     * @param listener	事件侦听函数。
+     * @param args		（可选）事件侦听函数的回调参数。
+     * @return 此 EventDispatcher 对象。
+     */
+    on(type: string, caller: any, listener: Function, args?: any[]): EventDispatcher;
+    /**
+     * 使用 EventDispatcher 对象注册指定类型的事件侦听器对象，以使侦听器能够接收事件通知，此侦听事件响应一次后自动移除。
+     * @param type		事件的类型。
+     * @param caller	事件侦听函数的执行域。
+     * @param listener	事件侦听函数。
+     * @param args		（可选）事件侦听函数的回调参数。
+     * @return 此 EventDispatcher 对象。
+     */
+    once(type: string, caller: any, listener: Function, args?: any[]): EventDispatcher;
+    /**@internal */
+    private _createListener;
+    /**
+     * 从 EventDispatcher 对象中删除侦听器。
+     * @param type		事件的类型。
+     * @param caller	事件侦听函数的执行域。
+     * @param listener	事件侦听函数。
+     * @param onceOnly	（可选）如果值为 true ,则只移除通过 once 方法添加的侦听器。
+     * @return 此 EventDispatcher 对象。
+     */
+    off(type: string, caller: any, listener: Function, onceOnly?: boolean): EventDispatcher;
+    /**
+     * 从 EventDispatcher 对象中删除指定事件类型的所有侦听器。
+     * @param type	（可选）事件类型，如果值为 null，则移除本对象所有类型的侦听器。
+     * @return 此 EventDispatcher 对象。
+     */
+    offAll(type?: string): EventDispatcher;
+    /**
+     * 移除caller为target的所有事件监听
+     * @param	caller caller对象
+     */
+    offByCaller(caller: any): void;
+    offAllEvent(): void;
+    private _recoverHandlers;
+}
+/**
+ * 全局事件中心
+ */
+export declare const eventCenter: EventDispatcher;

package/dist/app/base/pool/IRecoverable.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 可重复利用对象接口
+ */
+export interface IRecoverable {
+    /**
+     * 重置到可复用状态
+     */
+    reset(): void;
+    /**
+     * 销毁
+     */
+    destroy(): void;
+}

package/dist/app/base/pool/Pool.d.ts

@@ -0,0 +1,45 @@
+import { IRecoverable } from "./IRecoverable";
+/**
+ * 对象池
+ */
+export declare class Pool<T extends IRecoverable> {
+    /**池中闲置对象 */
+    private _cacheStack;
+    /**正在使用的对象 */
+    private _usingArray;
+    /**池中对象最大数 */
+    private _maxCount;
+    private _class;
+    constructor(clazz: {
+        new (...arg: any[]): T;
+    }, maxCount?: number);
+    /**
+    * 在池中的对象
+    */
+    get count(): number;
+    /**
+     * 使用中的数量
+     */
+    get usingCount(): number;
+    /**
+     * 分配
+     * @returns
+     */
+    allocate(createData?: any): T;
+    /**
+     * 回收到池中
+     * @param value
+     * @returns
+     */
+    recover(value: T): void;
+    /**
+     * 批量回收
+     * @param list
+     */
+    recoverList(list: Array<T>): void;
+    /**
+     * 将所有使用中的对象都回收到池中
+     */
+    recoverAll(): void;
+    destroy(): void;
+}

package/dist/app/base/utils/Handler.d.ts

@@ -0,0 +1,69 @@
+import { IRecoverable } from "../pool/IRecoverable";
+import { Pool } from "../pool/Pool";
+/**
+ * <p><code>Handler</code> 是事件处理器类。</p>
+ * <p>推荐使用 Handler.create() 方法从对象池创建，减少对象创建消耗。创建的 Handler 对象不再使用后，可以使用 Handler.recover() 将其回收到对象池，回收后不要再使用此对象，否则会导致不可预料的错误。</p>
+ * <p><b>注意：</b>由于鼠标事件也用本对象池，不正确的回收及调用，可能会影响鼠标事件的执行。</p>
+ */
+export declare class Handler implements IRecoverable {
+    /**@private handler对象池*/
+    protected static _pool: Pool<Handler>;
+    /**@private */
+    private static _gid;
+    /** 执行域(this)。*/
+    caller: Object | null;
+    /** 处理方法。*/
+    method: Function | null;
+    /** 参数。*/
+    args: any[] | null;
+    /** 表示是否只执行一次。如果为true，回调后执行recover()进行回收，回收后会被再利用，默认为false 。*/
+    once: boolean;
+    /**@private */
+    protected _id: number;
+    /**
+     * 根据指定的属性值，创建一个 <code>Handler</code> 类的实例。
+     * @param	caller 执行域。
+     * @param	method 处理函数。
+     * @param	args 函数参数。
+     * @param	once 是否只执行一次。
+     */
+    constructor(caller?: Object | null, method?: Function | null, args?: any[] | null, once?: boolean);
+    /**
+     * 设置此对象的指定属性值。
+     * @param	caller 执行域(this)。
+     * @param	method 回调方法。
+     * @param	args 携带的参数。
+     * @param	once 是否只执行一次，如果为true，执行后执行recover()进行回收。
+     * @return  返回 handler 本身。
+     */
+    setTo(caller: any, method: Function | null, args: any[] | null, once?: boolean): Handler;
+    /**
+     * 执行处理器。
+     */
+    run(): any;
+    /**
+     * 执行处理器，并携带额外数据。
+     * @param	data 附加的回调数据，可以是单数据或者Array(作为多参)。
+     */
+    runWith(data: any): any;
+    /**
+     * 清理对象引用。
+     */
+    clear(): Handler;
+    reset(): void;
+    destroy(): void;
+    /**
+     * 清理并回收到 Handler 对象池内。
+     */
+    recover(): void;
+    equal(value: Handler): boolean;
+    /**
+     * 从对象池内创建一个Handler，默认会执行一次并立即回收，如果不需要自动回收，设置once参数为false。
+     * @param	caller 执行域(this)。
+     * @param	method 回调方法。
+     * @param	args 携带的参数。
+     * @param	once 是否只执行一次，如果为true，回调后执行recover()进行回收，默认为true。
+     * @return  返回创建的handler实例。
+     */
+    static create(caller: any, method: Function | null, args?: any[] | null, once?: boolean): Handler;
+}

package/dist/app/base/utils/Injector.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 简单的注入器
+ */
+export declare class Injector {
+    /**类型字典*/
+    private static _injectedMap;
+    /**实例字典*/
+    private static _instanceMap;
+    /**
+     * 注入
+     * @param key
+     * @param clazz   类型或实例
+     */
+    static inject(customKey: string, clazz: any): void;
+    /**
+     * 获取已注入的类型实例
+     */
+    static getInject<T>(customKey: string): T;
+}

package/dist/app/base/utils/Json.d.ts

@@ -0,0 +1,14 @@
+export declare class Json {
+    /**
+     * 默认的json 转化函数，即不做任何操作
+     * @param key
+     * @param value
+     */
+    static NoneReviver(key: string, value: any): any;
+    /**
+     * json 转化函数，将字符串形式的毫秒时间戳（13字符长度）转换为纯数字。
+     * @param key
+     * @param value
+     */
+    static TimestampReviver(key: string, value: any): any;
+}

package/dist/app/base/utils/MathUtils.d.ts

@@ -0,0 +1,74 @@
+export declare class MathUtils {
+    /**
+     * 随机种子
+     */
+    static seed: number;
+    /**
+     * 唯一记录
+     */
+    private static onlyMap;
+    /**
+     * 随机
+     * @param min
+     * @param max
+     */
+    static random(min: number, max: number): number;
+    /**
+     * 随机整数值
+     * @param min
+     * @param max
+     */
+    static randomInt(min: number, max: number): number;
+    /**
+     * 随机唯一稳定值
+     * @param min
+     * @param max
+     * @param clear  是否清除唯一记录
+     */
+    static randomOnlyInt(min: number, max: number, clear?: boolean): number;
+    /**
+     * 获取两点间的角度
+     * @param p1 点1
+     * @param p2 点2
+     */
+    static getAngle(p1: {
+        x: number;
+        y: number;
+    }, p2: {
+        x: number;
+        y: number;
+    }): number;
+    /**
+     * 获取两点间的距离
+     * @param p1 点1
+     * @param p2 点2
+     */
+    static getDistance(p1: {
+        x: number;
+        y: number;
+    }, p2: {
+        x: number;
+        y: number;
+    }): number;
+    /**
+     * 将角度转为弧度
+     * @param angle 角度
+     */
+    static angleToRadian(angle: number): number;
+    /**
+     * 求旋转后的点坐标
+     * @param angle         角度
+     * @param point         旋转前的坐标点
+     * @param result
+     */
+    static getRotationPoint(angle: number, pointOrDir: {
+        x: number;
+        y: number;
+    }, result?: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+}

package/dist/app/base/utils/NativeUtils.d.ts

@@ -0,0 +1,4 @@
+export declare class NativeUtils {
+    static getArgsSig(args: any[], returnType: any): string;
+    static getValueTypeStr(value: any): string;
+}

package/dist/app/base/utils/PromiseUtils.d.ts

@@ -0,0 +1,20 @@
+export declare class PromiseUtils {
+    /**
+     * 延迟
+     * @param time 延迟时间，单位毫秒
+     */
+    static delay(time: number): Promise<void>;
+    /**
+     * 并发多个Promise，和Promise.all相同,只是实现了其中progress。完成后返回结果列表。
+     * @param promises
+     * @param progress
+     * @returns
+     */
+    static each(promises: Promise<any>[], progress: (step: number, total: number) => void): Promise<any[]>;
+    /**
+     * 队列逐个执行多个Promise。完成后返回结果列表。
+     * @param promises
+     * @returns
+     */
+    static sequence(promises: Promise<any>[], progress: (step: number, total: number) => void): Promise<any[]>;
+}