1 changed files with 299 additions and 0 deletions
@ -0,0 +1,299 @@ |
|||||
|
# Pixi 框架重构设计（DX 优先，性能其次） |
||||
|
|
||||
|
## 背景与目标 |
||||
|
|
||||
|
本设计用于指导 `pixi-demo` 的新一轮框架重构。重构范围聚焦两部分： |
||||
|
|
||||
|
- 核心运行时（`Game + Scene + 生命周期 + 插件机制`） |
||||
|
- 资源系统（`AssetManager + manifest + 预加载/引用追踪/调试信息`） |
||||
|
|
||||
|
约束和原则： |
||||
|
|
||||
|
- 目标平台：Web H5 优先 |
||||
|
- 兼容策略：彻底升级（允许批量改场景代码，换取更干净的架构） |
||||
|
- 优先级：开发者体验第一，性能第二 |
||||
|
- 允许任意重构 |
||||
|
- 需要内置一组服务开发流程的 UI 能力 |
||||
|
|
||||
|
## 设计原则 |
||||
|
|
||||
|
1. 可观测优先：所有关键行为都能在开发态被看见和解释。 |
||||
|
2. 状态可证明：场景与资源都由明确状态机驱动，不依赖隐式约定。 |
||||
|
3. 边界清晰：运行时、场景、资源、开发工具分层解耦，减少跨层直接访问。 |
||||
|
4. 失败可恢复：切换和加载过程默认考虑失败与回滚，不把异常当特例。 |
||||
|
5. 渐进性能：先构建可测量基础，再做高收益优化，避免盲目微调。 |
||||
|
|
||||
|
## 总体架构 |
||||
|
|
||||
|
### 1) `kernel`（运行时内核） |
||||
|
|
||||
|
职责： |
||||
|
|
||||
|
- 管理 `AppRuntime`（renderer/ticker/stage） |
||||
|
- 编排生命周期与切换事务 |
||||
|
- 提供插件总线与统一错误边界 |
||||
|
|
||||
|
非职责： |
||||
|
|
||||
|
- 不承载业务场景逻辑 |
||||
|
- 不直接持有业务资源映射 |
||||
|
|
||||
|
### 2) `scene`（场景域） |
||||
|
|
||||
|
职责： |
||||
|
|
||||
|
- 场景注册（`SceneRegistry`） |
||||
|
- 场景切换（`SceneTransition`） |
||||
|
- 场景上下文（`SceneContext`） |
||||
|
|
||||
|
场景统一生命周期： |
||||
|
|
||||
|
- `created -> setup -> assetsLoading -> entering -> ready -> leaving -> disposed` |
||||
|
|
||||
|
### 3) `assets`（资源域） |
||||
|
|
||||
|
职责： |
||||
|
|
||||
|
- 资源依赖图（`AssetGraph`） |
||||
|
- 场景资源会话（`AssetSession`） |
||||
|
- 引用追踪与释放策略 |
||||
|
- 预加载与复用策略 |
||||
|
|
||||
|
### 4) `devtools`（开发体验层） |
||||
|
|
||||
|
职责： |
||||
|
|
||||
|
- 开发态 overlay |
||||
|
- 运行时事件时间线 |
||||
|
- 场景/资源检视器 |
||||
|
- 命令面板（Command Palette） |
||||
|
|
||||
|
约束： |
||||
|
|
||||
|
- 仅通过事件与快照读取状态，不直接修改业务状态 |
||||
|
|
||||
|
### 5) `ui-core`（内置 UI 基础层） |
||||
|
|
||||
|
第一阶段只服务开发工具界面，不直接扩展为完整业务 UI 框架。提供最小组件集： |
||||
|
|
||||
|
- `UiPanel` |
||||
|
- `UiText` |
||||
|
- `UiButton` |
||||
|
- `UiList` |
||||
|
|
||||
|
## 模块边界约束 |
||||
|
|
||||
|
- 场景层不得直接调用 Pixi `Assets` 全局对象，只能通过 `SceneContext.assets`。 |
||||
|
- 资源层不得感知具体场景类实现，只识别 `ownerId/sessionId`。 |
||||
|
- 运行时内核不直接 import 业务场景文件，场景通过注册机制注入。 |
||||
|
- devtools 读取运行时快照和事件流，避免写入造成调试副作用。 |
||||
|
|
||||
|
## 生命周期与数据流设计 |
||||
|
|
||||
|
## 场景状态机定义 |
||||
|
|
||||
|
### `setup` |
||||
|
|
||||
|
- 创建静态显示对象结构 |
||||
|
- 绑定事件与命令 |
||||
|
- 禁止异步资源请求 |
||||
|
|
||||
|
### `assetsLoading` |
||||
|
|
||||
|
- 通过 `AssetSession` 申请 bundle 及依赖 |
||||
|
- 记录 owner/session 关系 |
||||
|
|
||||
|
### `entering` |
||||
|
|
||||
|
- 资源就绪后的首帧布局 |
||||
|
- 进入动画和交互解锁前处理 |
||||
|
|
||||
|
### `ready` |
||||
|
|
||||
|
- 场景可交互的稳定状态 |
||||
|
|
||||
|
### `leaving` |
||||
|
|
||||
|
- 停止输入和 ticker 订阅 |
||||
|
- 准备切换和资源释放 |
||||
|
|
||||
|
### `disposed` |
||||
|
|
||||
|
- 场景彻底释放，不再允许引用 |
||||
|
- 需要复用时重新实例化 |
||||
|
|
||||
|
## 场景切换事务（Transition Transaction） |
||||
|
|
||||
|
切换流程固定为： |
||||
|
|
||||
|
1. `beginTransition(from, to)` |
||||
|
2. `freezeInput(from)` |
||||
|
3. `prepare(to)`（`setup + assetsLoading`） |
||||
|
4. `commit()`（舞台替换 + `entering`） |
||||
|
5. `finalize(from)`（`leave + dispose/unmount`） |
||||
|
6. `emitTransitionReport()` |
||||
|
|
||||
|
失败处理： |
||||
|
|
||||
|
- 任一阶段失败触发 `rollback()` |
||||
|
- 回退到 `from.ready` |
||||
|
- 记录失败阶段与异常信息 |
||||
|
- 通过 dev overlay 展示失败链路 |
||||
|
|
||||
|
## 资源会话模型（AssetSession） |
||||
|
|
||||
|
每次场景进入创建 `AssetSession(sceneId, transitionId)`，示例： |
||||
|
|
||||
|
- `session.require("bundle.home")` |
||||
|
|
||||
|
内部行为： |
||||
|
|
||||
|
- 解析 `AssetGraph` 依赖关系（如 `home -> common-ui -> common-audio`） |
||||
|
- 记录引用链：`asset <- bundle <- session <- scene` |
||||
|
- 在 `commit` 成功后再释放旧场景 session |
||||
|
|
||||
|
释放策略： |
||||
|
|
||||
|
- 支持短延迟释放窗口（例如 2s），降低快速来回切场造成的重复加载抖动 |
||||
|
|
||||
|
## 可观测事件流 |
||||
|
|
||||
|
内核输出统一事件流： |
||||
|
|
||||
|
- `scene:state-changed` |
||||
|
- `transition:started|committed|rolledback|finished` |
||||
|
- `asset:request|loaded|reused|released|orphan-detected` |
||||
|
- `runtime:error` |
||||
|
|
||||
|
该事件流同时服务日志、overlay、定位与回归验证。 |
||||
|
|
||||
|
## 开发体验能力（MVP） |
||||
|
|
||||
|
## Debug Overlay（开发态默认启用） |
||||
|
|
||||
|
至少展示： |
||||
|
|
||||
|
- 当前场景与状态 |
||||
|
- 切换耗时 |
||||
|
- 最近运行时事件（最近 20 条） |
||||
|
- FPS 和 ticker 开销 |
||||
|
- bundle 引用树（owner/session） |
||||
|
- 最近错误与 phase |
||||
|
|
||||
|
支持快捷键开关（例如 `~`）。 |
||||
|
|
||||
|
## Scene Inspector（最小版） |
||||
|
|
||||
|
展示场景树（scene id/state/mounted）并支持开发命令： |
||||
|
|
||||
|
- `reload current scene` |
||||
|
- `simulate transition failure` |
||||
|
- `force release assets(session)` |
||||
|
|
||||
|
## Asset Inspector（最小版） |
||||
|
|
||||
|
展示： |
||||
|
|
||||
|
- `bundle -> assets -> owners` |
||||
|
- orphan 资源 |
||||
|
- 高频重复加载 bundle |
||||
|
- 长驻 bundle 总量 |
||||
|
|
||||
|
## Runtime Command Palette |
||||
|
|
||||
|
支持开发命令调用，例如： |
||||
|
|
||||
|
- `scene.goto(welcome)` |
||||
|
- `asset.preload(bundle.xxx)` |
||||
|
- `dev.toggleOverlay()` |
||||
|
|
||||
|
## 性能策略（第一阶段） |
||||
|
|
||||
|
在不牺牲 DX 的前提下做低侵入优化： |
||||
|
|
||||
|
- overlay 刷新节流（例如 200ms） |
||||
|
- 通过可观测数据驱动资源预热，而非猜测 |
||||
|
- 切场资源释放使用短延迟窗口平衡内存与流畅度 |
||||
|
|
||||
|
## 测试与验收标准 |
||||
|
|
||||
|
## Definition of Done |
||||
|
|
||||
|
### 运行时稳定性 |
||||
|
|
||||
|
- 场景切换 100 次无卡死、无黑屏、无未捕获异常 |
||||
|
- 切换失败可回滚到上一场景 `ready` |
||||
|
|
||||
|
### 资源可追踪性 |
||||
|
|
||||
|
- 每个已加载 bundle 都可查看 owner/session |
||||
|
- 切场后无长期 orphan 残留（延迟释放窗口内短暂存在可接受） |
||||
|
|
||||
|
### 开发体验 |
||||
|
|
||||
|
- overlay 可一键开关且不阻断交互 |
||||
|
- 至少 8 条 runtime 命令可执行 |
||||
|
- 报错可定位到生命周期 phase |
||||
|
|
||||
|
### 可维护性 |
||||
|
|
||||
|
- 生命周期、切换事务、资源图关键路径具备单测 |
||||
|
- 新场景模板可在 5 分钟内创建并跑通 |
||||
|
|
||||
|
## 测试策略 |
||||
|
|
||||
|
### 单元测试 |
||||
|
|
||||
|
- `SceneStateMachine` 状态迁移合法性 |
||||
|
- `TransitionTransaction` 的 commit/rollback 分支 |
||||
|
- `AssetSession` 引用计数与释放顺序 |
||||
|
|
||||
|
### 集成测试 |
||||
|
|
||||
|
- 场景 A->B->A 快速切换与资源抖动 |
||||
|
- bundle 加载失败与恢复 |
||||
|
|
||||
|
### 手工验证（开发态） |
||||
|
|
||||
|
- overlay 信息正确性 |
||||
|
- command palette 链路可用性 |
||||
|
- 长时间运行资源引用稳定性 |
||||
|
|
||||
|
## 实施里程碑 |
||||
|
|
||||
|
### M1：运行时内核重构（约 1 周） |
||||
|
|
||||
|
- 新 lifecycle 与 transition transaction |
||||
|
- 插件总线 |
||||
|
- 基础 overlay（状态与耗时） |
||||
|
|
||||
|
### M2：资源系统重构（约 1 周） |
||||
|
|
||||
|
- `AssetGraph + AssetSession` |
||||
|
- `Asset Inspector` |
||||
|
- 预热与延迟释放 |
||||
|
|
||||
|
### M3：DX 强化（约 1 周） |
||||
|
|
||||
|
- command palette |
||||
|
- 场景模板与错误提示优化 |
||||
|
- 验收测试补齐 |
||||
|
|
||||
|
## 风险与应对 |
||||
|
|
||||
|
- 风险：彻底升级导致迁移期间业务场景不可用。 |
||||
|
- 应对：按里程碑提供最小迁移适配层，仅用于过渡，M3 后清理。 |
||||
|
- 风险：devtools 与运行时耦合过深。 |
||||
|
- 应对：强制事件总线和只读快照接口，禁止直接写内核状态。 |
||||
|
- 风险：资源引用关系复杂导致误释放。 |
||||
|
- 应对：`owner/session` 双维追踪 + release 日志审计 + 回归用例。 |
||||
|
|
||||
|
## 非目标（当前阶段不做） |
||||
|
|
||||
|
- 完整业务 UI 组件库建设 |
||||
|
- 多端宿主统一适配层（小程序/小游戏） |
||||
|
- 高级渲染性能专项（需在可观测基础稳定后进行） |
||||
|
|
||||
|
## 结论 |
||||
|
|
||||
|
本方案以“内核先重构、资源系统同步升级、开发工具前置落地”为主线，保证在重构初期即提升开发者体感，并通过可观测与状态机约束降低后续维护成本。第一阶段以可看见、可定位、可恢复为核心交付，性能优化作为可量化的后续迭代项推进。 |
||||
Loading…
Reference in new issue