AIGame/ProjectDesign.md

# AIGame 项目框架设计

> 目标：Unity 微信小游戏（竖屏）  
> 客户端工程：`AIClient/`  
> 资源生产：`ResourceCreate.md`  
> 热更资源 CDN：`https://www.xworld.ren`  
> 游戏服：`game.xworld.ren`（WebSocket：`wss://game.xworld.ren/ws?pid=...`）

当前玩法依据：[AIGame 基础游戏设计](GameDesign.md)。功能方向为伙伴收集养成、弹珠、布阵塔防和营地；旧科幻肉鸽方案已归档。UI 当前仅保留 Candy。

---

## 1. 目标与约束

| 项 | 选型 / 约束 |
| --- | --- |
| 平台 | Unity → 微信小游戏（WebGL / WASM 适配） |
| 屏幕 | **竖屏**（Portrait，UI 设计分辨率固定 `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 登录、幂等玩法 API 与 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 / 玩法骨架；断线重连；维护公告 | ✅ HUD+ConfirmDialog；Ws 指数退避重连；`version.notice` + `maintenance.json` |
| M5 | 包体与性能优化；提审用壳版本策略固化 |

---

## 12. 相关文档

| 文档 | 内容 |
| --- | --- |
| [`GameDesign.md`](GameDesign.md) | 当前基础玩法、系统规则、资源经济与开发验收 |
| [`ResourceCreate.md`](ResourceCreate.md) | 图、3D、减面烘焙生成方式 |
| [`Doc/ResDesc.md`](Doc/ResDesc.md) | 资源登记索引 |
| [`UNITY-GUIDE.md`](UNITY-GUIDE.md) | Agent 操作 Unity 规范 |
| [`Doc/Design/Combat/SkillSystem.md`](Doc/Design/Combat/SkillSystem.md) | 关卡技能系统设计：逻辑行为、动作/特效/音效组合、固定tick事件、服务端结算与TangoFlux制作流程；当前为设计及配置契约，尚未切换运行时 |
| [`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。
- 壳只做启动与加载；业务全在热更程序集，保证日常迭代不提审。