# 主站 Web 对接完整步骤（Cocos tfrh001）

## 一、在 Cocos Creator 中构建 Web Desktop

### 1. 打开工程

```
/Users/liuyufei/tfrh/cocos/tfrh001
```

确认已存在 `assets/scenes/main.scene`，且节点上挂了 **AppBootstrap**。

### 2. 设置启动场景

**项目 → 项目设置 → 项目数据 → 启动场景** → 选择 `main`。

### 3. 构建发布

1. 菜单 **项目 → 构建发布**（或顶部 **构建** 按钮）
2. **发布平台**：选 **Web Desktop**（不要选 Web Mobile，除非只做手机）
3. **构建路径**：默认 `build/web-desktop`（可保持默认）
4. **初始场景**：`main`
5. 建议勾选：
   - **内联所有 SpriteFrame**（减少请求数，可选）
   - **MD5 Cache**（按需）
6. 点击 **构建**
7. 构建成功后点击 **运行** 可先本地测一遍

### 4. 构建产物位置

```
tfrh001/build/web-desktop/
├── index.html          ← 含 Cocos 启动 script 列表
├── index.js
├── src/
│   ├── system.bundle.js
│   ├── polyfills.bundle.js
│   └── ...
├── assets/             ← 资源
└── ...
```

> 若 `build/web-desktop` 不存在，说明尚未在编辑器里点过「构建」。

---

## 二、合并到主站静态目录

### 方式 A：自动脚本（推荐）

在终端执行（先完成上一节构建）：

```bash
cd /Users/liuyufei/tfrh/cocos/tfrh001

# 部署到主站 Template 下（与 Unity 模板并列，便于对比）
bash tools/deploy-to-main.sh \
  --build build/web-desktop \
  --target "/Users/liuyufei/tfrh/主站文件/主站/Template/cocos"
```

部署后目录：

```
主站/Template/
├── index.html              ← 原 Unity 页（参考）
├── cocos-bridge.js         ← 新增：JS 桥
├── cocos-demo.html         ← 新增：联调页
└── cocos/                  ← Cocos 构建产物
    ├── index.html
    └── src/ ...
```

### 方式 B：手动复制

| 复制源 | 复制到 |
|--------|--------|
| `build/web-desktop/*` | 主站静态目录下的 `cocos/` |
| `web-template/cocos-bridge.js` | 与主站 `index.html` **同级** |

---

## 三、修改主站 index.html

### 1. 引入 cocos-bridge（在 Unity 脚本之前）

```html
<script src="cocos-bridge.js"></script>
```

`cocos-bridge.js` 会注册：

- `processData` / `processVehicleData` / `externalResult` / `externalLevelInfo` / `coinsData`
- 等待 `window.unityInstance` 就绪

### 2. 删除 Unity 加载段

删除类似内容：

```html
<script src="Build/build.loader.js"></script>
<script>
  createUnityInstance(canvas, config, ...).then((unityInstance) => {
    window.unityInstance = unityInstance;
  });
</script>
```

### 3. 粘贴 Cocos 启动脚本

构建完成后运行（自动生成粘贴清单）：

```bash
node tools/patch-main-index.js build/web-desktop
```

将输出的 `<script src="cocos/...">` 按主站实际路径写入 `index.html`。

**路径规则**：

- 主站页面与 `cocos/` 同级 → `src="cocos/src/system.bundle.js"`
- 游戏在根目录 → 不加 `cocos/` 前缀

### 4. 游戏容器

保留或添加 Cocos 构建页中的结构：

```html
<div id="GameDiv">
  <div id="Cocos3dGameContainer">
    <canvas id="GameCanvas"></canvas>
  </div>
</div>
```

若主站原用 `#unity-canvas`，可只改 id 为 `GameCanvas`，或保留原 id 并在构建模板里改 canvas id（需改构建配置，一般直接用 Cocos 默认即可）。

### 5. unityInstance 无需手写

游戏启动后 `GameController` 会自动执行：

```javascript
window.unityInstance = { SendMessage: ... };
window.cocosIns = 同上;
```

主站 Blockly 代码 **不用改**：

```javascript
unityInstance.SendMessage("Player", "CallMove", n);
unityInstance.SendMessage("GameController", "SwitchLevel", levelId);
```

---

## 四、本地预览

### 仅预览 Cocos 构建（未合并主站）

用 Cocos 构建面板里的 **运行**，或：

```bash
cd build/web-desktop
npx --yes serve . -p 8080
# 打开 http://localhost:8080
```

### 预览合并后的主站目录

```bash
cd "/Users/liuyufei/tfrh/主站文件/主站/Template"
npx --yes serve . -p 8080
```

- 联调页：`http://localhost:8080/cocos-demo.html`
- 若已改主站 index：`http://localhost:8080/index.html`

---

## 五、联调自检清单

| 步骤 | 期望 |
|------|------|
| 打开页面 | 控制台无 404（检查 cocos/*.js 路径） |
| 加载完成 | `[GameController] unityInstance.SendMessage 已就绪` |
| | `[tfrh] Cocos bridge ready` |
| `SwitchLevel(1)` | 日志 `externalLevelInfo` |
| `CallMove(2)` | 角色移动 |
| `CallPlayerInfo` | 日志 `processData` |

---

## 六、CDN 整包发布（对标 Unity mstest5）

与 Unity 把 `mstest5/` 整目录上传 CDN 一样，Cocos 也支持**单目录静态部署**，无需 Node 服务器。

### 1. 构建 + 打 CDN 包（与 Unity 参考包文件树 100% 一致）

参考 Unity 包：`/Users/liuyufei/tfrh/竞赛/mstest5`

```bash
cd /Users/liuyufei/tfrh/cocos/tfrh001

# ① Cocos Creator：项目 → 构建发布 → Web Desktop → 构建
# ② 打成与 Unity 完全相同的目录/文件名
bash tools/package-for-cdn.sh --build build/web-desktop-001

# 输出到竞赛目录旁（便于对比）
bash tools/package-for-cdn.sh --build build/web-desktop-001 --out "/Users/liuyufei/tfrh/竞赛/mstest5-cocos"
```

### 2. 产物结构（与 Unity 参考逐文件对齐）

```
mstest5/
├── index.html
├── Build/
│   ├── mstest5.loader.js
│   ├── mstest5.data.br
│   ├── mstest5.framework.js.br
│   └── mstest5.wasm.br
├── StreamingAssets/aa/
│   ├── catalog.json
│   ├── settings.json
│   ├── AddressablesLink/link.xml
│   └── WebGL/
│       ├── 3a39a2f..._unitybuiltinshaders_....bundle
│       ├── defaultlocalgroup_assets_all_1baf4413....bundle  ← Cocos 资源 zip
│       └── defaultlocalgroup_scenes_all_44c83ead....bundle ← Cocos 引擎 zip
└── TemplateData/（11 个文件，与 Unity 相同）
```

`index.html` / `TemplateData` / `catalog.json` / `settings.json` / `link.xml` / `unitybuiltinshaders.bundle` **直接复制 Unity 参考包**；Cocos 运行时打进两个 `defaultlocalgroup_*.bundle`，由自定义 `mstest5.loader.js` 解压并启动。

### 3. 上传与访问

1. 将 `mstest5/` 内**全部文件**上传到 CDN 的 **mstest5** 目录（覆盖原 Unity 包）
2. 浏览器打开 `https://你的CDN域名/mstest5/index.html`
3. 主站 iframe 嵌入（URL 与 Unity 时代相同，只换引擎）：

```html
<iframe src="https://cdn.example.com/mstest5/index.html" width="960" height="600"></iframe>
```

### 4. 构建面板建议（CDN 场景）

| 选项 | 建议 |
|------|------|
| 发布平台 | **Web Desktop** |
| 资源服务器地址 `server` | **留空**（资源与页面同域相对路径加载） |
| MD5 Cache | 生产可开启，更新后需刷新 CDN 缓存 |
| 主包压缩 | 默认 `merge_dep` 即可 |

若资源与页面不在同一路径，在构建面板填写 CDN 根 URL 到「资源服务器地址」，例如 `https://cdn.example.com/tfrh001/`。

### 5. 与 Unity mstest5 对比

| | Unity mstest5 | Cocos mstest5 |
|--|---------------|-------------------|
| 入口 | `index.html` | `index.html` |
| 运行时 | `Build/*.br` (WASM) | `cocos-js/` + `src/` (JS) |
| 关卡资源 | `StreamingAssets/aa/*.bundle` | `assets/` (JSON + 贴图) |
| JS 桥 | 需主站页挂回调 | 已含 `cocos-bridge.js` |
| Brotli | 需要 `Content-Encoding: br` | 普通静态文件即可 |

---

## 七、生产环境注意

1. **HTTPS**：与 Unity 相同，WebGL/Canvas 在混合内容下可能受限  
2. **缓存**：构建带 MD5 时，更新后清 CDN 缓存  
3. **跨域**：`cocos/` 与主站同域部署最省事  
4. **回退**：可保留 Unity `Build/` 目录，通过配置开关切换加载 Unity 或 Cocos

---

## 八、关卡

已导入 Levels600 共 **600** 关，`SwitchLevel(1..600)` 与 Unity 一致。