Add hot-update boot pipeline, UI bundles/atlas assets, and design docs.
Ignore AIClient/Library and AIClient/HybridCLRData permanently; include HybridCLR/YooAsset project setup and UI tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
udx
@@ -0,0 +1,386 @@
|
||||
# AIGame 项目框架设计
|
||||
|
||||
> 目标：Unity 微信小游戏（竖屏）
|
||||
> 客户端工程：`AIClient/`
|
||||
> 资源生产：`ResourceCreate.md`
|
||||
> 热更资源 CDN：`https://www.xworld.ren`
|
||||
> 游戏服：`game.xworld.ren`（WebSocket：`wss://game.xworld.ren/ws?pid=...`）
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与约束
|
||||
|
||||
| 项 | 选型 / 约束 |
|
||||
| --- | --- |
|
||||
| 平台 | Unity → 微信小游戏（WebGL / WASM 适配） |
|
||||
| 屏幕 | **竖屏**（Portrait，基准设计分辨率建议 `750×1624` 或 `1080×1920`） |
|
||||
| 渲染 | **URP**（已接入 `com.unity.render-pipelines.universal`） |
|
||||
| 资源加载 | **YooAsset** `3.x`（已接入 `com.tuyoogame.yooasset`） |
|
||||
| 代码热更 | **HybridCLR**（已接入 `com.code-philosophy.hybridclr`） |
|
||||
| 资源生产 | 统一走 `ResourceCreate.md` 流水线，完成后登记 `Doc/ResDesc_*.md` |
|
||||
| 网络 | 长连接 WebSocket；短链 HTTP 仅用于版本/CDN 清单 |
|
||||
| CDN | `https://www.xworld.ren` |
|
||||
| 游戏服域名 | `game.xworld.ren`（Caddy `reverse_proxy`，自动处理 WS Upgrade） |
|
||||
|
||||
非目标（首期不做）：横屏、原生 App 包、复杂战斗回放、跨服匹配。
|
||||
|
||||
---
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 微信小游戏宿主 │
|
||||
│ ┌──────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ AOT 壳 (主包) │→ │ HybridCLR 加载热更 DLL │ │
|
||||
│ │ Boot / 补丁 │ │ HotUpdate 业务程序集 │ │
|
||||
│ └──────┬───────┘ └──────────────────┬──────────────────┘ │
|
||||
│ │ YooAsset │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ 本地缓存/包内 │ │ Net / UI / 玩法 │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ │
|
||||
└─────────┼─────────────────────────────┼─────────────────────┘
|
||||
│ HTTPS │ WSS
|
||||
▼ ▼
|
||||
https://www.xworld.ren wss://game.xworld.ren/ws?pid=...
|
||||
(CDN: 版本清单 + AB + DLL) (Caddy → 游戏服进程)
|
||||
```
|
||||
|
||||
分层原则：
|
||||
|
||||
1. **AOT 壳（不可热更）**：启动、权限、HybridCLR 初始化、YooAsset 初始化、补丁下载、加载热更程序集、进入热更入口。
|
||||
2. **HotUpdate（可热更）**：UI、玩法、协议、配置表、业务逻辑。
|
||||
3. **资源层（YooAsset）**：AssetBundle / RawFile（含 DLL、配置、音视频等）。
|
||||
4. **网络层**：WebSocket 会话；业务协议与热更代码绑定，壳层只保留连通性探测（可选）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 仓库与目录约定
|
||||
|
||||
```text
|
||||
AIGame/
|
||||
├── AIClient/ # Unity 客户端
|
||||
│ ├── Assets/
|
||||
│ │ ├── AOT/ # 壳程序集源码（Boot、Patch、HybridCLR 加载）
|
||||
│ │ ├── HotUpdate/ # 热更程序集源码（玩法/UI/Net）
|
||||
│ │ ├── Bundles/ # 待打包资源（按 YooAsset Collector 收集）
|
||||
│ │ ├── Scenes/ # Boot 场景等（主包内）
|
||||
│ │ ├── Settings/ # URP / 质量 / 输入
|
||||
│ │ └── Editor/ # 构建、收集、上传工具
|
||||
│ ├── Packages/ # HybridCLR / YooAsset / URP ...
|
||||
│ └── HybridCLRData/
|
||||
├── Tools/ # 资源生产脚本（见 ResourceCreate.md）
|
||||
├── Doc/ # 设计、资源登记、接口文档
|
||||
├── TempResource/ # 中间产物（不进主包）
|
||||
├── ResourceCreate.md # 资源生成节点用法
|
||||
└── ProjectDesign.md # 本文档
|
||||
```
|
||||
|
||||
程序集建议：
|
||||
|
||||
| 程序集 | 热更 | 职责 |
|
||||
| --- | --- | --- |
|
||||
| `AOT.Runtime` | 否 | Boot、版本检查、YooAsset 初始化、HybridCLR Load、最小 UI（更新条） |
|
||||
| `HotUpdate.Runtime` | 是 | 游戏入口、UI、玩法、协议、配置 |
|
||||
| `HotUpdate.Shared`（可选） | 是 | 与服务器共享的协议 DTO / 常量 |
|
||||
| `*.Editor` | — | 打包、收集规则、CDN 上传、HybridCLR 生成 |
|
||||
|
||||
微信小游戏包体限制严格：**主包只放 AOT 壳 + 启动资源**；其余全部走 CDN 热更。
|
||||
|
||||
---
|
||||
|
||||
## 4. 渲染与竖屏
|
||||
|
||||
- Pipeline：**URP**，移动端/小游戏质量档（关闭不必要的后处理，控制实时光数量）。
|
||||
- 方向：Player Settings → **Portrait**；微信侧 `game.json` / 适配层同步竖屏。
|
||||
- UI：Canvas Scaler 以竖屏基准分辨率 Match Width/Height；安全区适配刘海/底部横条。
|
||||
- 相机：默认正交或透视按品类定；首期统一一套 URP Asset（可再分 Low/Mid）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 资源生产流水线
|
||||
|
||||
严格遵循 [`ResourceCreate.md`](ResourceCreate.md)，产出进 `TempResource/` 或 `Tools/output/`，导入 `AIClient/Assets/Bundles/` 后再由 YooAsset 打包。
|
||||
|
||||
```text
|
||||
概念 / 需求
|
||||
→ 文/图生图（gpt_image_generate.py）
|
||||
→ [模型] 混元图生3D → GLB（hunyuan_3d_generate.py）
|
||||
→ [模型] 减面 + 烘焙（model_lowpoly_bake.py）
|
||||
→ 导入 Unity（Pipeline / 人工整理到 Bundles）
|
||||
→ 登记 Doc/ResDesc_*.md
|
||||
→ YooAsset 构建 → 上传 CDN
|
||||
```
|
||||
|
||||
规则摘要：
|
||||
|
||||
1. ≤1K 图用默认模型；>1K（如 2048 图集）必须 VIP + 像素尺寸。
|
||||
2. 3D：图 → 混元 GLB → 低模烘焙；登记 `Doc/ResDesc_Model.md`。
|
||||
3. UI / 贴图登记 `Doc/ResDesc_Picture.md`；音效、特效等同理。
|
||||
4. **未登记 = 资源流程未完成**，不得进入正式 Bundle 发布。
|
||||
5. **UI Prefab**：走 `Doc/UI_AutoGen_Overview.md`（JSON→`Assets/Bundles/UI/Prefab`）；竖屏设计分辨率 `[1080,1920]`。
|
||||
|
||||
YooAsset 包划分建议：
|
||||
|
||||
| Package | 内容 | 更新策略 |
|
||||
| --- | --- | --- |
|
||||
| `DefaultPackage` | 热更 DLL、启动必需表、通用 UI | 启动强制更新 |
|
||||
| `Art` | 场景、角色、特效、音频 | 按需 / 后台 |
|
||||
| `Config`（可并入 Default） | 数值表、本地化 | 随版本 |
|
||||
|
||||
地址规则（CDN）：
|
||||
|
||||
```text
|
||||
https://www.xworld.ren/{channel}/{appVersion}/{packageName}/{fileName}
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
https://www.xworld.ren/wechat/1.0.0/DefaultPackage/PackageManifest_DefaultPackage_20260321.bytes
|
||||
https://www.xworld.ren/wechat/1.0.0/DefaultPackage/xxx.bundle
|
||||
```
|
||||
|
||||
`channel` 固定 `wechat`；`appVersion` 与壳版本对齐（强更时升壳版本）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 热更循环（核心）
|
||||
|
||||
整套循环覆盖：**代码（HybridCLR）+ 资源（YooAsset）+ 版本门控 + CDN 发布**。
|
||||
|
||||
### 6.1 版本模型
|
||||
|
||||
| 版本 | 存放位置 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| `appVersion` | 壳内写死 / 微信提审包 | 原生壳版本；不兼容时强制用户更新微信小游戏包 |
|
||||
| `resVersion` | CDN 清单 | 资源与热更 DLL 的逻辑版本 |
|
||||
| `packageVersion` | YooAsset Package | 各 Package 的构建号 |
|
||||
|
||||
CDN 根提供总控文件（建议）：
|
||||
|
||||
```text
|
||||
https://www.xworld.ren/wechat/version.json
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"appVersionMin": "1.0.0",
|
||||
"appVersionMax": "1.0.0",
|
||||
"resVersion": "20260321.1",
|
||||
"cdnRoot": "https://www.xworld.ren/wechat/1.0.0",
|
||||
"packages": ["DefaultPackage", "Art"],
|
||||
"forceUpdate": false,
|
||||
"notice": ""
|
||||
}
|
||||
```
|
||||
|
||||
壳启动时：
|
||||
|
||||
1. 读本地 `appVersion`。
|
||||
2. 拉 `version.json`。
|
||||
3. 若本地 `appVersion < appVersionMin` → 提示去微信更新小游戏（壳强更）。
|
||||
4. 否则用 `cdnRoot` 初始化 YooAsset HostPlayMode，更新各 Package。
|
||||
5. 从资源中取出热更 DLL → HybridCLR 加载 → 调用热更入口。
|
||||
|
||||
### 6.2 客户端启动时序
|
||||
|
||||
```text
|
||||
微信启动
|
||||
→ AOT Boot 场景
|
||||
→ 初始化日志 / 安全区 / 竖屏确认
|
||||
→ 请求 version.json（CDN）
|
||||
→ 壳版本门控
|
||||
→ YooAsset.Initialize
|
||||
→ UpdatePackageVersion / UpdatePackageManifest
|
||||
→ Download（DLL + 必需资源）+ 进度 UI
|
||||
→ HybridCLR LoadAssembly(HotUpdate.dll [+ AOT 补充元数据])
|
||||
→ HotUpdate.GameEntry.Start()
|
||||
→ 连接 wss://game.xworld.ren/ws?pid=...
|
||||
→ 进入登录 / 主界面
|
||||
```
|
||||
|
||||
失败策略：
|
||||
|
||||
| 阶段 | 策略 |
|
||||
| --- | --- |
|
||||
| `version.json` 失败 | 重试 N 次；仍失败则用本地缓存清单（若存在）或提示网络错误 |
|
||||
| 下载失败 | 断点续传（YooAsset）；失败可重试；关键包失败不可进游戏 |
|
||||
| DLL 加载失败 | 清缓存并重下；仍失败则报错退出 |
|
||||
| WS 连接失败 | 热更 UI 可进；玩法层提示重连（指数退避） |
|
||||
|
||||
### 6.3 构建与发布流水线
|
||||
|
||||
```text
|
||||
开发改动（HotUpdate / Bundles）
|
||||
→ HybridCLR Generate（AOT 泛型 / LinkXml 等按工程配置）
|
||||
→ 编译热更 DLL，拷入 YooAsset 收集目录（RawFile）
|
||||
→ YooAsset Build（ActiveBuildTarget = WeixinMiniGame / WebGL）
|
||||
→ 产出 Bundles + Manifest
|
||||
→ 上传至 https://www.xworld.ren/wechat/{appVersion}/
|
||||
→ 更新 version.json（resVersion 递增）
|
||||
→ 客户端下次启动自动拉新
|
||||
```
|
||||
|
||||
热更范围：
|
||||
|
||||
| 可热更 | 不可热更（需提审新壳） |
|
||||
| --- | --- |
|
||||
| 玩法/UI/协议 C# | 引擎升级、URP 重大变更 |
|
||||
| AssetBundle 资源 | 新增第三方原生插件、微信 SDK 能力 |
|
||||
| 配置表、文案 | HybridCLR/AOT 元数据不兼容变更 |
|
||||
| 多数 Bugfix | `appVersion` 门控要求升壳 |
|
||||
|
||||
### 6.4 开发期模式
|
||||
|
||||
| 模式 | 用途 |
|
||||
| --- | --- |
|
||||
| EditorSimulateMode | 编辑器快速迭代，不打 AB |
|
||||
| OfflinePlayMode | 本地打包验证 |
|
||||
| HostPlayMode | 真机/微信开发者工具，走 CDN |
|
||||
|
||||
编辑器日常：Simulate；出包前必须 Host/Offline 各验一遍启动热更路径。
|
||||
|
||||
### 6.5 HybridCLR 与微信注意点
|
||||
|
||||
1. 热更程序集不要引用未裁剪保留的 AOT 类型；按 HybridCLR 文档生成并加载 **AOT 泛型补充元数据**。
|
||||
2. 微信小游戏对包体、内存、协程/线程有限制；下载与加载放在启动阶段，避免进游戏后同步卡死。
|
||||
3. DLL 以 RawFile 进 YooAsset，校验哈希，防止脏缓存。
|
||||
4. 热更入口保持稳定签名，例如 `HotUpdate.Entry.Start(BootContext ctx)`，壳只依赖此入口。
|
||||
|
||||
---
|
||||
|
||||
## 7. 网络与服务器
|
||||
|
||||
### 7.1 端点
|
||||
|
||||
| 用途 | URL |
|
||||
| --- | --- |
|
||||
| CDN / 静态资源 | `https://www.xworld.ren/...` |
|
||||
| 游戏 WebSocket | `wss://game.xworld.ren/ws?pid={playerOrSessionId}` |
|
||||
|
||||
说明：
|
||||
|
||||
- `pid`：玩家或会话标识（登录前可用设备临时 id，登录后换正式 pid / token 方案由协议定）。
|
||||
- 服务器前置：**Caddy `reverse_proxy`**，自动处理 WebSocket Upgrade，**无需额外 WS 专用配置**。
|
||||
- TLS 由 Caddy 终止；后端可监听本机 HTTP/WS。
|
||||
|
||||
Caddy 示意（运维侧）：
|
||||
|
||||
```caddyfile
|
||||
game.xworld.ren {
|
||||
reverse_proxy 127.0.0.1:8080
|
||||
}
|
||||
|
||||
www.xworld.ren {
|
||||
root * /var/cdn/www
|
||||
file_server
|
||||
header {
|
||||
Access-Control-Allow-Origin *
|
||||
Cache-Control "public, max-age=60"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
CDN 目录对 Bundle 可用长缓存；`version.json` 建议短缓存或 `no-cache`，避免玩家卡旧版本。
|
||||
|
||||
### 7.2 客户端连接约定
|
||||
|
||||
```text
|
||||
wss://game.xworld.ren/ws?pid=...
|
||||
```
|
||||
|
||||
建议行为：
|
||||
|
||||
1. 热更完成、拿到账号凭证后再连（或先匿名连再绑定）。
|
||||
2. 心跳：客户端定时 ping / 服务端超时踢。
|
||||
3. 断线：指数退避重连，恢复会话（服务端 session）。
|
||||
4. 协议：二进制（MessagePack / Protobuf）或 JSON；版本号放在握手首包。
|
||||
5. 业务协议放在 **HotUpdate** 程序集，便于改协议不发壳。
|
||||
|
||||
### 7.3 与热更的关系
|
||||
|
||||
- **资源/代码热更**：只依赖 CDN，不经过游戏服。
|
||||
- **游戏服**：可下发「推荐 resVersion / 维护公告」，但**权威版本仍以 CDN `version.json` 为准**，避免服与 CDN 不一致。
|
||||
- 维护时：服断开 WS 并返回维护码；壳层仍可展示公告（若 `version.json.notice` 有文案）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 客户端运行时模块（HotUpdate）
|
||||
|
||||
建议模块边界（便于热更与测试）：
|
||||
|
||||
```text
|
||||
HotUpdate
|
||||
├── Entry # 热更入口
|
||||
├── Net # WS 客户端、编解码、会话
|
||||
├── UI # 竖屏 UI 框架、页面栈
|
||||
├── Scene # 场景加载（经 YooAsset）
|
||||
├── Config # 表读取
|
||||
├── Audio / VFX
|
||||
└── Gameplay # 具体玩法
|
||||
```
|
||||
|
||||
BootContext（壳 → 热更）至少传递：
|
||||
|
||||
- `appVersion` / `resVersion`
|
||||
- YooAsset `ResourcePackage` 句柄或封装 API
|
||||
- 设备 / 微信用户临时标识
|
||||
- 日志与报错桥接
|
||||
|
||||
---
|
||||
|
||||
## 9. 微信小游戏发布要点
|
||||
|
||||
1. 构建目标：微信小游戏适配工程（Unity WebGL + 微信转换工具 / 官方导出流程，以当前工程选用的适配插件为准）。
|
||||
2. 主包最小化：Boot 场景 + AOT + 首屏更新 UI 图。
|
||||
3. 远程资源域名白名单：配置 `https://www.xworld.ren`、`wss://game.xworld.ren`。
|
||||
4. 竖屏、安全区、性能档在真机与开发者工具双验。
|
||||
5. 提审包升 `appVersion` 时，同步提高 CDN `appVersionMin/Max`，并保留旧 CDN 路径一段回滚窗口。
|
||||
|
||||
---
|
||||
|
||||
## 10. 安全与运维
|
||||
|
||||
1. CDN 资源哈希校验（YooAsset 自带）；禁止信任未校验 Bundle。
|
||||
2. WS 需鉴权（token / 签名）；`pid` alone 不足以鉴权。
|
||||
3. 密钥与 API Key **不进客户端仓库明文**（资源生产 Key 仅 Tools 本机 / CI 密钥库）。
|
||||
4. `version.json` 与 Bundle 发布使用可回滚目录；出问题将 `version.json` 指回上一 `resVersion`。
|
||||
5. 日志：启动热更阶段打点（版本、下载耗时、失败码）便于定位玩家卡更新。
|
||||
|
||||
---
|
||||
|
||||
## 11. 里程碑（建议）
|
||||
|
||||
| 阶段 | 交付 |
|
||||
| --- | --- |
|
||||
| M0 | 壳工程：URP 竖屏 Boot、YooAsset Host 拉 CDN、HybridCLR 加载空热更 DLL |
|
||||
| M1 | `version.json` + 上传脚本；微信开发者工具跑通更新条 |
|
||||
| M2 | WS 连通 `wss://game.xworld.ren/ws?pid=...`；登录握手 |
|
||||
| M3 | 资源流水线打通（图/模 → Bundles → CDN）；示例角色进场景 |
|
||||
| M4 | UI / 玩法骨架；断线重连；维护公告 |
|
||||
| M5 | 包体与性能优化；提审用壳版本策略固化 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 相关文档
|
||||
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [`ResourceCreate.md`](ResourceCreate.md) | 图、3D、减面烘焙生成方式 |
|
||||
| [`Doc/ResDesc.md`](Doc/ResDesc.md) | 资源登记索引 |
|
||||
| [`UNITY-GUIDE.md`](UNITY-GUIDE.md) | Agent 操作 Unity 规范 |
|
||||
| [`Agents.md`](Agents.md) | 项目可读摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 决策摘要
|
||||
|
||||
- **微信竖屏小游戏** + **URP** + **YooAsset** + **HybridCLR**。
|
||||
- 资源生产统一走 **ResourceCreate**，发布前必须 **ResDesc 登记**。
|
||||
- 热更权威源：CDN `https://www.xworld.ren` 的 `version.json` + Package Manifest。
|
||||
- 玩法服：`wss://game.xworld.ren/ws?pid=...`，Caddy 反代即可，不另配 WS。
|
||||
- 壳只做启动与加载；业务全在热更程序集，保证日常迭代不提审。
|
||||
|
||||
Reference in New Issue
Block a user