# 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 组件库建设
- 多端宿主统一适配层（小程序/小游戏）
- 高级渲染性能专项（需在可观测基础稳定后进行）

## 结论

本方案以“内核先重构、资源系统同步升级、开发工具前置落地”为主线，保证在重构初期即提升开发者体感，并通过可观测与状态机约束降低后续维护成本。第一阶段以可看见、可定位、可恢复为核心交付，性能优化作为可量化的后续迭代项推进。