刘宇飞
d393302388
Adds level prefabs, theme assets, audio, extensions, and deployment scripts for the Unity WebGL migration. Co-authored-by: Cursor <cursoragent@cursor.com>
280 lines
7.8 KiB
Markdown
280 lines
7.8 KiB
Markdown
# 主站 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 一致。
|