keytops-game-framework

2.0 Analytics 迁移

从 2.0.0 开始，App.launch() 不再自动启用统计。游戏必须在框架启动完成后、首次访问 analytics.launch、analytics.level、analytics.ad、analytics.session 或 analytics.social 前显式初始化：

await App.launch(true, { injects: [] });
analytics.enable(true, [sender]);

IAnalyticsSender.userPropertyMode 默认为 event，原有 Sender 会继续将用户属性合并到事件。需要使用平台原生用户属性能力的 Sender 应设置为 sender，并实现 setUserProperty()；这类用户属性不会再重复写入事件参数。

2.0.0 同时将 Analytics 内部公共字段改为可跨平台使用的合法名称，例如 _dt_ 改为 duration、_av_ 改为 app_version。本版本不再双写旧字段，依赖旧字段的报表和查询需要同步迁移。

keytops-game-framework 是面向 Cocos Creator 项目的游戏开发框架，提供应用生命周期、网络通信、平台能力、存储、计时器、ECS、FSM、任务、埋点、视图、资源和音频等基础设施。这个包定位于框架层，适合需要直接使用底层模块和引擎适配能力的项目，不是精简 facade SDK。

适用场景

• 使用 Cocos Creator 构建完整游戏项目
• 需要统一的应用启动、平台接入和模块化基础设施
• 需要网络、ECS、FSM、埋点、视图和资源管理能力
• 需要在框架层扩展自定义注入或平台能力

安装

npm install keytops-game-framework

快速开始

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

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

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*

import { publisher } from 'keytops-game-framework';

publisher.enable();

const appId = publisher.appId;
const deviceInfo = publisher.device.deviceInfo;

存储与计时器

• storage
• Storage
• StorageImpl
• timer
• Timer
• TimerImpl

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
• 关卡、广告、社交、会话等统计能力

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 方向的界面、资源和音频能力。

扩展方式

追加自定义注入

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 中把它表述为“现成支持多引擎发布”的通用产品。

构建

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
• 引擎特定实现应依赖框架接口，不应反向耦合业务层