AIGame/ProjectDesign.md

AIGame 项目框架设计

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

当前玩法依据：AIGame 基础游戏设计。功能方向为伙伴收集养成、弹珠、布阵塔防和营地；旧科幻肉鸽方案已归档。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. 总体架构

┌─────────────────────────────────────────────────────────────┐
│ 微信小游戏宿主                                                │
│  ┌──────────────┐   ┌─────────────────────────────────────┐ │
│  │ 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. 仓库与目录约定

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，产出进 TempResource/ 或 Tools/output/，导入 AIClient/Assets/Bundles/ 后再由 YooAsset 打包。

概念 / 需求
  → 文/图生图（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）：

https://www.xworld.ren/{channel}/{appVersion}/{packageName}/{fileName}

示例：

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 根提供总控文件（建议）：

https://www.xworld.ren/wechat/version.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 客户端启动时序

微信启动
  → 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 构建与发布流水线

开发改动（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 示意（运维侧）：

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 客户端连接约定

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）

建议模块边界（便于热更与测试）：

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. 相关文档

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