refactor(platform): complete decoupled vertical runtime
This commit is contained in:
@@ -1,6 +1,71 @@
|
||||
# framework — 框架真源（唯一权威副本）
|
||||
|
||||
各子游戏工程的 `assets/framework` 是指向**本目录**的 junction（见 `scripts/setup-links.mjs`）。
|
||||
六层结构（依赖严格单向，详见 spec §3）：core / net / protocol / platform / ui / sdk。
|
||||
协议相关实现以 `docs/protocol/` 为权威，远程配置与原生接口也必须复刻原工程。服务器、配置服务和原生侧均零改动。
|
||||
|
||||
协议相关实现一律以 `docs/protocol/` 为唯一信息源（spec §0.1），不在代码或注释中内联复制协议字段。
|
||||
## 现代运行时的唯一组合路径
|
||||
|
||||
```text
|
||||
game CompositionRoot -> bootstrapPlatform(single GameEntry)
|
||||
game implementation -> framework/sdk only
|
||||
WireClient -> PlatformRuntime -> Router exactly once
|
||||
PlatformStore -> selectors -> GameHost/UI read-only consumers
|
||||
```
|
||||
|
||||
这里的 `bootstrapPlatform(single GameEntry)` 是组合设计记号，当前没有同名函数。
|
||||
已实现的构造入口是 `new PlatformRuntime(options)`：`gameEntry` 由构建期固定提供一个，
|
||||
`resolveRuntimeConfig` 使用 `config/runtime-config.ts` 的解析器，
|
||||
`createWireClient(config)` 用最终 `config.servers` 构造 `WireClient`，注入实际 Transport 工厂。
|
||||
组合方还提供 `ScenePort`、资源加载、最短展示等待和登录设备快照能力，然后调用 `start()`；
|
||||
界面取得账号后显式调用 `login(account)`，socket open 本身不会发送登录。
|
||||
`integration/platform-vertical-slice.test.ts` 展示了这一组合的完整无界面回放。
|
||||
|
||||
Runtime 内部创建唯一 Router、RuntimeSession、PlatformStore、平台命令和 GameSessionHost。
|
||||
游戏实现只通过 `framework/sdk/index.ts` 导入公开契约；该入口只重导出 `sdk/contracts`，
|
||||
不再公开旧 Store、EventBus 或任意路由发包能力。SDK contracts 不导入内部框架模块或 `cc`；
|
||||
SDK runtime 也不导入框架实现层，平台适配由 `platform/game-host-adapter.ts` 承担。
|
||||
|
||||
不提供 GameRegistry、运行时 API 协商、多个游戏的包、游戏直接访问 Store/EventBus 的路径。
|
||||
每次房间会话创建新的 GameModule 和 Host lease，旧 lease 不能读取或操纵新房间。
|
||||
平台先原子提交房间和玩家快照，再创建游戏、发布平台事件；truthy `deskinfo` 在房间场景就绪后
|
||||
按原对象引用交给 `restore`，不进入 PlatformStore，falsey/缺失值不触发恢复。
|
||||
连接事件也提交到同一个 Store；重连只更换 app 连接状态，保留 room/players 引用。
|
||||
切服先发送原始 `connect_*server` 信封，进房成功再原子标记已登录；普通重连才重新发送已保存的登录信封。
|
||||
|
||||
远程地址唯一取自 `data.urlserver`。配置请求使用空 body 的 POST，沿用无条件 `?` 缓存参数拼接。
|
||||
原生 settings 方法名称、调用次序和 WVJB 初始化/handler 名称由 `config/sources`、
|
||||
`adapters/native` 实现，`framework-tests/config` 与 `framework-tests/native` 验证。
|
||||
|
||||
## 仍被 Cocos 脚本使用的兼容隔离区
|
||||
|
||||
以下是 `LEGACY_RUNTIME` 的完整文件清单，路径相对本目录；现代框架文件禁止直接或传递依赖它们：
|
||||
|
||||
- `net/net-client.ts`
|
||||
- `platform/session.ts`
|
||||
- `platform/startup.ts`
|
||||
- `platform/room-rpc-bus.ts`
|
||||
- `platform/readonly.ts`
|
||||
- `platform/stores/app-store.ts`
|
||||
- `platform/stores/player-store.ts`
|
||||
- `platform/stores/room-store.ts`
|
||||
- `platform/stores/types.ts`
|
||||
- `protocol/room-handlers.ts`
|
||||
|
||||
当前 `YouleNexus/assets/scripts/LoginFlow.ts`、`RoomEventProbe.ts`、`RoomSceneStart.ts`
|
||||
仍直接引用上述兼容文件。因此它们继续保留；阶段 3 必须由 Presenter 和真正的游戏 Composition Root
|
||||
接管这些脚本的调用后，阶段 6 才能删除兼容区。当前无界面现代回放通过，不表示 Cocos UI 已接入现代运行时。
|
||||
|
||||
保留的兼容逻辑测试（相对 `framework-tests/`）是 `net/net-client.test.ts`、
|
||||
`platform/app-store.test.ts`、`platform/player-store.test.ts`、`platform/room-store.test.ts`、
|
||||
`platform/session.test.ts`、`platform/startup.test.ts`、`platform/room-rpc-bus.test.ts`、
|
||||
`protocol/room-handlers.test.ts`。它们测试旧脚本仍需使用的行为，不属于现代运行时的依赖图。
|
||||
旧 SDK 的完整标识符盘点仅允许 `architecture/import-boundaries.test.mjs` 中的负例，
|
||||
以及 `protocol/room-handlers.ts` 内一处历史说明。名称子串 `requireActiveGame` 是现代处理器的局部状态检查方法，
|
||||
不是已移除的旧类型；自动盘点按完整标识符匹配。
|
||||
|
||||
`scripts/check-import-boundaries.mjs` 不再给 SDK 入口任何内部依赖豁免，也不给旧活动游戏文件名称检查豁免。
|
||||
`framework-tests/architecture/import-boundaries.test.mjs` 对全部现代框架 TypeScript 文件检查传递依赖，
|
||||
并验证重导出、别名、动态导入、CommonJS 和 import type 的负例；无法静态判断的传递加载直接拒绝。
|
||||
|
||||
阶段 3 的 Presenter/Composition Root 接管、theme/Prefab binding、首个真实子游戏迁移及 ZIP 发布均属于后续独立计划。
|
||||
本次逻辑验收不改动 Cocos 序列化资源或现有 UI 迁移产物。
|
||||
|
||||
Reference in New Issue
Block a user