# 方案：可视化可扩展 GM 模块

> 更新日期：2026-10-16

## 1. 目标

将单文件输入型 GM（`assets/script/game/GM.ts`）重构为：

- **mx 通用壳**：快捷按钮 / 滑动开关 / 内容面板，可拷到任意 Cocos 项目
- **项目命令注册**：业务 Action + 内容面板工厂，换项目整夹替换

## 2. 分层

| 层 | 路径 | 职责 |
|----|------|------|
| 框架 | `assets/mx/module/gm/` | Registry、Host、Shell、View、内置面板；禁止依赖 `script/` |
| 项目 | `assets/script/gm/` | Host 注入、命令注册、表驱动 Picker、业务 Action |

依赖方向：`script/gm` → `mx/gm` + Manager；`mx/gm` 绝不引用 `script/`。

## 3. 三种控件

| Kind | 用途 | 示例 |
|------|------|------|
| Quick | 一键动作 | 复制存档、每日重置、发宝石 |
| Toggle | 开/关 | 广告、营地免伤、商店无限 |
| Content | 可视化子页 | 道具图标点选、关卡列表、段位步进；JSON 用 textArea |

## 4. 开发者扩展（优先用 GmEasy）

日常加功能只改 `ProjectGmBootstrap._register`，链式几行即可：

```ts
new GmEasy()
  .tab('常用')
  .btn('复制存档', () => copy())           // 快捷
  .sw('显示广告', () => on, v => set(v)) // 开关
  .num('金钱', () => get(), v => set(v)) // 数值设为+增减
  .page('道具', 'itemPicker', () => '点选') // 自定义面板
  .danger('重置', '确定？', () => reset())
  .text('存档', raw => apply(raw))
  .commit();
```

底层仍是 `IGmCommand` / `GmRegistry`；自定义面板：`GmRegistry.registerPanel(id, () => new XxxPanel())`。

内置面板 id：`numberStepper`、`confirmQuick`、`textArea`。

## 5. 换项目接入

1. 拷贝 `assets/mx/module/gm/`
2. 实现 `IGmHost`（约 30 行）
3. `new GmEasy()...commit()` 写命令；需要时 `registerPanel`
4. `GmShell.bindHost` + `GmShell.show()`

## 6. 本项目迁移

- Toggle：广告、内购、商店无限、营地免伤、快速胜利
- Quick：每日重置、复制存档、发宝石/武器、清地图、商店重置、排行测试等
- Content：道具/BUFF/关卡/段位/货币/血量/存档；武器相关可打开原 PopGM
- 删除帮助有、代码无的死条目；空实现等级命令不注册

## 7. 入口

- 设置页 `GM.show()` → 委托 `ProjectGmBootstrap.show()` → `GmShell`
- 挂载 `UILayer.DeBug`
- 显隐受 `IGmHost.isEnabled()` 约束（浏览器或 `sdkConfig.isOpenGM`）
- 旧 `gm.prefab` 已从 Boot 预载移除；武器等级/预设仍走 `PopGM` 预制体

## 8. 实现清单

| 模块 | 路径 |
|------|------|
| 类型/注册/壳/视图/内置面板 | `assets/mx/module/gm/` |
| Host / Actions / Panels / Bootstrap | `assets/script/gm/` |
| 门面 | `assets/script/game/GM.ts`（薄委托，无 EditBox/switch） |

未迁入本版（原孤儿/死代码）：玩家等级空实现、七十二变帮助项、指定背包文字（可后续加 Content）。