|
|
|
|
# 方案：预览调试工作台（零侵入）
|
|
|
|
|
|
|
|
|
|
> 日期：2026-10-14
|
|
|
|
|
> 范围：仅 `preview-template/`，不修改 `assets/**`，可拷贝到任意 Creator 3.8 项目。
|
|
|
|
|
|
|
|
|
|
## 1. 目标
|
|
|
|
|
|
|
|
|
|
浏览器预览中的运行时分析坞：可调布局、层级/属性（含点选与实时改值）、官方性能浮窗 + 历史曲线、资源缓存与内存估算、控制台。
|
|
|
|
|
|
|
|
|
|
**不做**：Prefab 编辑、序列化落盘、编辑器级 Inspector、项目内埋点。
|
|
|
|
|
|
|
|
|
|
## 2. 硬约束
|
|
|
|
|
|
|
|
|
|
- 零侵入：不新增/修改业务 TS；不要求项目调用 `mark()`。
|
|
|
|
|
- 全部代码在 `preview-template/index.ejs` + `preview-template/workbench/**`。
|
|
|
|
|
- 运行时只访问预览页引擎全局（`cc`）；在 `<%- include(cocosTemplate) %>` 之后加载并等待就绪。
|
|
|
|
|
- 可选软接口：`window.__PreviewWorkbench.mark(label)`（项目可不调用）。
|
|
|
|
|
|
|
|
|
|
## 3. 业务标记（模板侧）
|
|
|
|
|
|
|
|
|
|
| 来源 | 文案示例 | 实现 |
|
|
|
|
|
|------|----------|------|
|
|
|
|
|
| 场景启动/改名 | `scene:Main` | `Director.EVENT_AFTER_SCENE_LAUNCH` + 轮询 scene.name |
|
|
|
|
|
| 前后台 | `game:hide/show` | `Game.EVENT_HIDE/SHOW` |
|
|
|
|
|
| Bundle 新出现 | `bundle:xxx` | 轮询 `assetManager.bundles` diff |
|
|
|
|
|
| 资源跳变 | `assets:+N` | 计数增幅超阈值（可关） |
|
|
|
|
|
| 用户手动 | `user:…` | 性能面板按钮 |
|
|
|
|
|
|
|
|
|
|
无「大厅/战斗」等玩法语义；自愿 `mark('battle')` 可显示自定义标签。
|
|
|
|
|
|
|
|
|
|
## 4. 架构
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
preview-template/
|
|
|
|
|
index.ejs
|
|
|
|
|
workbench/
|
|
|
|
|
css/workbench.css
|
|
|
|
|
js/
|
|
|
|
|
host.js # 等 cc、挂 __PreviewWorkbench
|
|
|
|
|
bridge.js # 壳侧 postMessage / 同域直调
|
|
|
|
|
layout-core.js # 布局生命周期 / 停靠树重建 / 工具栏 / 持久化
|
|
|
|
|
layout-presets.js # 分析/场景/精简预设树
|
|
|
|
|
layout-render.js # split/tabs/game 渲染与分割条
|
|
|
|
|
layout-dock.js # 面板拖拽停靠
|
|
|
|
|
layout-tree.js # 停靠树查找/清理/拆分
|
|
|
|
|
layout-float.js # 悬浮窗与面板开关记忆
|
|
|
|
|
markers.js
|
|
|
|
|
perf-sampler.js
|
|
|
|
|
charts/ring-chart.js
|
|
|
|
|
panels/perf.js
|
|
|
|
|
panels/assets.js
|
|
|
|
|
panels/hierarchy.js
|
|
|
|
|
panels/inspector.js
|
|
|
|
|
panels/console.js
|
|
|
|
|
pick.js
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
游戏侧探针（`?pw=game`，见「方案-工作台性能隔离」）：
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
workbench/js/
|
|
|
|
|
agent-util.js # 节点遍历/序列化/指纹公共函数
|
|
|
|
|
agent-core.js # 探针构造、RPC、订阅、资源/游戏控制
|
|
|
|
|
agent-serialize.js # Inspector 属性读写
|
|
|
|
|
agent-pick.js # 画布点选与高亮
|
|
|
|
|
agent-console.js # console 钩子与格式化
|
|
|
|
|
agent.js # 启动入口（创建 __PW_Agent）
|
|
|
|
|
device.js / idle.js / perf-sampler.js / markers.js
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 5. 布局
|
|
|
|
|
|
|
|
|
|
- 隐藏官方预览工具栏，使用自研菜单（设备 / 旋转 / 帧率 / 暂停 / 游戏·检视 / 面板开关）。
|
|
|
|
|
- 设备选择后预览区显示手机边框（刘海可选），按逻辑分辨率缩放适配。
|
|
|
|
|
- **Desktop 停靠树（接近 Creator）**：
|
|
|
|
|
- 拖到区域**标题栏/中心** = 合并为同一区域页签
|
|
|
|
|
- 拖到区域**边沿** = 在该方向新建布局区域（递归拆分）
|
|
|
|
|
- 横排含游戏时，上/下边沿只包住**连续非游戏列**（例如层级|属性下方），不横跨游戏区；竖排含游戏时左/右同理
|
|
|
|
|
- 分割条拖拽改比例；`localStorage` 键 `preview-workbench-layout-v7`
|
|
|
|
|
- **默认分析布局**：竖屏 → 左上层级|属性、左下控制台（横跨两列）、中游戏、右性能；横屏 → 上层级|属性|游戏|性能、下控制台通栏
|
|
|
|
|
- **设备预览**：设备框仅为容器（按可用区域与设备宽高比算出真实布局尺寸，**禁止** `transform: scale`）；游戏画布 100% 铺满容器；`setFrameSize` = 容器 client 尺寸，触摸坐标与画面一致
|
|
|
|
|
- **Compact**：游戏最大化；面板互斥抽屉；底栏切换。
|
|
|
|
|
|
|
|
|
|
### 原型（Desktop 分析）
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
┌─ 官方 Toolbar ──────────────────────────────────────────┐
|
|
|
|
|
├─ WB: [Game|Inspect] [布局] [浮窗] [层级][属性][资源][性能][控制台]
|
|
|
|
|
├─ Hierarchy │ GameCanvas │ Inspector ─┤
|
|
|
|
|
├────────────┴─────────────────────┴────────────┤
|
|
|
|
|
│ BOTTOM Perf Viz（曲线 + 自动/手动标记纵线） │
|
|
|
|
|
└────────────────────────────────────────────────┘
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 6. 面板要点
|
|
|
|
|
|
|
|
|
|
- **性能**：`profiler.showStats` 浮窗 + `PerfSampler` 环缓冲多曲线；暂停/清空/导出 CSV/打标记。
|
|
|
|
|
- **资源**：仅 `assetManager`；按 Bundle/类型筛选排序；估算内存（不能算则 `n/a`）；GFX 总量对照；预览缩略图。
|
|
|
|
|
- **层级/属性**：运行时树；可写 transform/active 等；`Game`/`Inspect` 切换；Inspect 下画布点选 + 高亮。
|
|
|
|
|
- **控制台**：钩子 `console.*` 环缓冲。
|
|
|
|
|
|
|
|
|
|
## 7. 分期与验收
|
|
|
|
|
|
|
|
|
|
| 阶段 | 验收 |
|
|
|
|
|
|------|------|
|
|
|
|
|
| P0 | PC 拖拽布局持久化；手机抽屉；横竖屏画布正常；cc 就绪提示 |
|
|
|
|
|
| P1 | 浮窗与曲线同源；自动 scene/bundle 标记；导出 CSV |
|
|
|
|
|
| P2 | 分类/分包/排序/估算/预览 |
|
|
|
|
|
| P3 | 点选高亮；改属性实时生效 |
|
|
|
|
|
| P4 | 级别过滤控制台 |
|
|
|
|
|
|
|
|
|
|
## 8. 风险
|
|
|
|
|
|
|
|
|
|
- 全局名以预览注入为准，失败提示「引擎未就绪」。
|
|
|
|
|
- 单资源 GPU 内存为估算，与 `textureMemory` 总量可能不一致，UI 并排标注。
|
|
|
|
|
- Inspect 临时高亮须在退出/卸载时销毁。
|
