7.7 KiB

Raw Blame History

Pixi 框架重构设计（DX 优先，性能其次）

背景与目标

本设计用于指导 pixi-demo 的新一轮框架重构。重构范围聚焦两部分：

核心运行时（Game + Scene + 生命周期 + 插件机制）
资源系统（AssetManager + manifest + 预加载/引用追踪/调试信息）

约束和原则：

目标平台：Web H5 优先
兼容策略：彻底升级（允许批量改场景代码，换取更干净的架构）
优先级：开发者体验第一，性能第二
允许任意重构
需要内置一组服务开发流程的 UI 能力

设计原则

可观测优先：所有关键行为都能在开发态被看见和解释。
状态可证明：场景与资源都由明确状态机驱动，不依赖隐式约定。
边界清晰：运行时、场景、资源、开发工具分层解耦，减少跨层直接访问。
失败可恢复：切换和加载过程默认考虑失败与回滚，不把异常当特例。
渐进性能：先构建可测量基础，再做高收益优化，避免盲目微调。

总体架构

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）

切换流程固定为：

beginTransition(from, to)
freezeInput(from)
prepare(to)（setup + assetsLoading）
commit()（舞台替换 + entering）
finalize(from)（leave + dispose/unmount）
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 组件库建设
多端宿主统一适配层（小程序/小游戏）
高级渲染性能专项（需在可观测基础稳定后进行）

结论

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

7.7 KiB Raw Blame History