Initial commit: Client Doc docs Server Tools
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
ud18010
@@ -0,0 +1,237 @@
|
||||
# 小游戏打包流程：Unity 菜单「XWorld/生成小游戏更新」设计
|
||||
|
||||
日期：2026-07-07
|
||||
状态：已与用户逐段确认（§1-§4）
|
||||
|
||||
## 0. 目标与范围
|
||||
|
||||
一条菜单驱动的发布流水线，对选定的小游戏：
|
||||
|
||||
- 客户端：打**代码热更 AB**（DLL 以 .bytes/TextAsset 进 AB）与**资源热更 AB**，落到
|
||||
`CDN/minigame/<gameId>/<version>/<platform>/`，供多端下载更新（本地 `Cdn.Runner` 或外网 CDN 同一布局）。
|
||||
- 服务器：`Server/games-src/<对应目录>` 编译出普通 DLL，落到
|
||||
`deploy/minigame/<gameId>/<version>/`，整目录上传外网服务器即可作为网关 `--gamesRoot` 的 games 根热更运行。
|
||||
- `Client/Assets/MiniGames` 下有多个小游戏目录时，先弹窗选择其一（单个也弹窗，用于确认版本/平台）。
|
||||
|
||||
本设计同时落地 2026-06-22 的「统一 AB」决策（设计 §10.1）：客户端发布产物全部为 `.unity3d`，
|
||||
弃用裸 `.bytes` 直下双管线，并同步改造客户端运行时消费端。
|
||||
|
||||
已确认的决策：
|
||||
- 代码热更形态：**落地统一 AB**（DLL .bytes 进代码 AB，运行时同步改造）。
|
||||
- 平台维度：**加 `<platform>/` 子目录，一次菜单可勾选多平台构建**。
|
||||
- 版本号：**自动递增（扫 CDN 已有版本取 max+1）+ 弹窗可改**，两端共用同一 version。
|
||||
- 元数据：**每游一份 `publish.json`**（解决 RockPaperScissors ↔ RPS ↔ rps 名称映射）。
|
||||
- 签名：**可选**——约定私钥路径存在则签，否则空 sig + 警告。
|
||||
- 实现架构：**方案 B（Editor 编排 + 复用 PublishTool，新增瘦 CLI 壳）**。
|
||||
|
||||
## 1. 产物布局与格式
|
||||
|
||||
### 1.1 publish.json（每个小游戏一份，驱动全流程）
|
||||
|
||||
`Client/Assets/MiniGames/<Game>/publish.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"gameId": "rps",
|
||||
"serverSrcDir": "RPS",
|
||||
"serverProject": "RPS.Server/RPS.Server.csproj",
|
||||
"serverAssembly": "RPS.Server.dll",
|
||||
"serverEntryType": "RPS.Server.RpsServerRoom",
|
||||
"clientProject": "Client/HotUpdateGames/RPS.Client/RPS.Client.csproj",
|
||||
"coreDll": "RPS.Core.dll",
|
||||
"clientDll": "RPS.Client.dll",
|
||||
"clientEntryType": "RPS.Client.RpsGameClient",
|
||||
"minFrameworkVersion": 1,
|
||||
"playerCount": 2,
|
||||
"tickRateHz": 10
|
||||
}
|
||||
```
|
||||
|
||||
- `serverSrcDir` 相对 `Server/games-src/`；`serverProject` 相对 `serverSrcDir`；
|
||||
`clientProject` 相对仓库根。
|
||||
- 菜单只把「含 publish.json 的目录」视为可发布小游戏；新游戏拷模板改字段即接入。
|
||||
|
||||
### 1.2 客户端产物（每平台一份）：`CDN/minigame/<gameId>/<version>/<platform>/`
|
||||
|
||||
```
|
||||
game.json gameId/version/clientEntryType/coreDll/clientDll/minFrameworkVersion
|
||||
+ 新字段 "codeAb": "code.unity3d" + "assets": ["res.unity3d"]
|
||||
files.txt {'code.unity3d','<md5>',size}, {'res.unity3d','<md5>',size},
|
||||
files.txt.sig 有私钥则 RSA 签名，否则空文件（沿用两端"未配置则跳过"语义）
|
||||
code_<md5>.unity3d 代码 AB：<coreDll>.bytes + <clientDll>.bytes 两个 TextAsset
|
||||
res_<md5>.unity3d 资源 AB：整个 res/ 目录打一个包（assets 数组支持以后拆多包）
|
||||
```
|
||||
|
||||
- 平台名沿用底包惯例：`pc / android / ios / webgl`（与 `LoadDll.sPlatform`、
|
||||
`CDN/XWorld/<platform>/` 一致）。
|
||||
- 线上文件 md5 命名（`name_<md5>.ext`），files.txt 登记逻辑名——与现有
|
||||
`MiniGameDownloader.Md5Name` 推导一致。
|
||||
- 边界：`res/` 不存在或为空时跳过资源 AB，`assets` 为空数组（仅发代码 AB）。
|
||||
- **不做 AES 加密**（minigame 链路现状如此，与 XWorld 底包 AB 加密体系无关）。
|
||||
|
||||
### 1.3 服务器产物：`deploy/minigame/<gameId>/<version>/`
|
||||
|
||||
```
|
||||
<serverAssembly> / <coreDll> 普通 DLL（不含 Framework.Shared.dll，Private=false 保证）
|
||||
game.json server 视图（serverAssembly/serverEntryType/playerCount/tickRateHz/minFrameworkVersion）
|
||||
files.txt + files.txt.sig 供 GameModuleLoader 配公钥后加载前验签
|
||||
```
|
||||
|
||||
结构与网关 `--gamesRoot` 消费的 `<id>/<ver>/` 完全一致。
|
||||
|
||||
### 1.4 配套修正：Core 单源
|
||||
|
||||
现状问题：`RPS.Client.csproj` 以 `<Compile Include="scripts~\**\*.cs">` 把 Core+Client
|
||||
全编进 RPS.Client.dll（内嵌 Core 类型副本，下载的 RPS.Core.dll 实为冗余）；而服务器
|
||||
`RPS.Core.csproj` 编译的是 `Server/games-src/RPS/RPS.Core/` 下另一份已发生格式漂移的拷贝。
|
||||
两端 Core 一旦真漂移即确定性不同步。
|
||||
|
||||
修正：
|
||||
- `Server/games-src/RPS/RPS.Core/` 删除重复 .cs，csproj 改
|
||||
`<Compile Include>` 链接 `Client/Assets/MiniGames/RockPaperScissors/scripts~/Core/**`
|
||||
（恢复「Core 唯一源码位在客户端 scripts~/Core」的原设计）。
|
||||
- `RPS.Client.csproj` 改为只编 `scripts~/Client/**` + `ProjectReference` RPS.Core
|
||||
（Private=false），Client.dll 不再内嵌 Core 副本；发布用的客户端 Core.dll 取自
|
||||
RPS.Core 构建产物（与服务器同一 IL）。
|
||||
|
||||
## 2. 构建编排（Editor 菜单 + PublishTool.Cli）
|
||||
|
||||
### 2.1 Editor 侧
|
||||
|
||||
重写 `Client/Assets/Editor/MiniGamePublishMenu.cs`（替换 stub 菜单「XWorld/生成小游戏」），
|
||||
新增 `MiniGamePublishWindow`（EditorWindow）：
|
||||
|
||||
- **游戏选择**：扫 `Assets/MiniGames/*/publish.json`；多个则列表选择，仅一个预选。
|
||||
- **版本号**：默认 = 扫 `CDN/minigame/<gameId>/` 下数字目录取 max+1（无则 1），可手改；
|
||||
覆盖已有版本前弹确认。
|
||||
- **平台勾选**：PC/Android/iOS/WebGL，默认勾选当前激活 BuildTarget 对应项。
|
||||
- **生成按钮**：执行 §2.2 流水线，每步失败 `DisplayDialog` 报错中断。
|
||||
|
||||
### 2.2 流水线
|
||||
|
||||
```
|
||||
1. dotnet build Server/games-src/<serverSrcDir>/<serverProject> -c Release
|
||||
→ <serverAssembly> + <coreDll>
|
||||
2. dotnet build <clientProject> -c Release
|
||||
→ <clientDll>（ProjectReference 引用步骤 1 的 Core 工程产物）
|
||||
3. 拷 Core.dll/Client.dll → Assets/MiniGameStaging/code/*.dll.bytes；
|
||||
AssetDatabase.Refresh 导入为 TextAsset（staging 必须在 Assets 下且**不能带 `~` 后缀**——
|
||||
`~` 目录 Unity 不导入、资产进不了 AB；用完即删含 .meta）
|
||||
4. 对每个勾选平台：
|
||||
BuildPipeline.BuildAssetBundles(平台临时目录,
|
||||
[ code.unity3d ← 两个 .bytes 资产,
|
||||
res.unity3d ← AssetDatabase 枚举 Assets/MiniGames/<Game>/res/ 下全部资产 ],
|
||||
ChunkBasedCompression, 对应 BuildTarget) ← 不切激活平台，直接传 target
|
||||
5. 写 resolved-spec.json（publish.json 字段 + version + AB 文件名列表）到临时目录
|
||||
6. Process 调 PublishTool.Cli（惯例同 XWorldUtil 起 dotnet 的方式）：
|
||||
server：调一次 → 临时 out → 成功后原子 Directory.Move 入 deploy/minigame/<id>/<ver>/
|
||||
client：每平台一次 → 临时 out → 成功后移入 CDN/minigame/<id>/<ver>/<platform>/
|
||||
7. 清理 staging；汇总日志 + 完成对话框（列出全部落位路径、是否已签名）
|
||||
```
|
||||
|
||||
先落临时目录、成功后整体 Move 的原因：`CDN/` 可能正被 `Cdn.Runner` 对外提供下载，
|
||||
避免半成品被客户端拉走。
|
||||
|
||||
### 2.3 PublishTool 侧（.NET，本环境可 dotnet test 回归）
|
||||
|
||||
- **`PublishLayout` 改造**：拆 `PublishServer(srcDir, outDir, spec, key?)` 与
|
||||
`PublishClient(srcDir, outDir, spec, key?)`；客户端侧删除 `CopyBytes` 双 .bytes 逻辑，
|
||||
改为登记 `codeAb + assets` 各 AB（md5 命名落盘 + files.txt 登记逻辑名）。
|
||||
- **`GameSpec` / `GameJsonWriter`**：加 `CodeAb` 字段；`WriteClient` 输出 `codeAb`。
|
||||
- **新增 `Server/PublishTool.Cli`**（瘦控制台，入 Server.sln）：
|
||||
`--mode client|server --src <dir> --out <dir> --spec <resolved-spec.json> [--key <pem>]`
|
||||
- **签名**：约定私钥 `Tools/keys/minigame-private.pem`（gitignore）；Editor 检测到则传
|
||||
`--key`，否则 CLI 写空 sig 并在输出中警告「未签名」。
|
||||
- **`PublishTool.Tests` 同步更新**：新布局断言（codeAb 进清单、无 .bytes 散文件、
|
||||
双端目录形状、无 key 时空 sig）。
|
||||
|
||||
## 3. 客户端运行时改造（XWorld.Link）
|
||||
|
||||
- **`MiniGameManifest`**：解析新字段 `codeAb`（校验非空）；`assets` 语义变为
|
||||
「资源 AB 文件名列表」。
|
||||
- **`MiniGameDownloader`**：`RemoteBase` 加平台段 →
|
||||
`<cdnBase><gameId>/<version>/<platform>/`（平台名以编译宏判定，热更层内新增小工具函数，
|
||||
不引用底包 LoadDll）。下载逻辑零改动（按 files.txt 通用增量下载）。
|
||||
`LocalDir` 不加平台段（设备平台固定）。
|
||||
- **`MiniGameAssemblyLoader`**：从 `LocalDir + codeAb`（本地为明文件名）
|
||||
`AssetBundle.LoadFromFile` → `LoadAsset<TextAsset>("<coreDll>.bytes"/"<clientDll>.bytes")`
|
||||
→ `Assembly.Load`（Core 先于 Client）→ `AB.Unload(false)`。
|
||||
找不到 TextAsset 时报清晰错误（列出 AB 内实际资产名）。
|
||||
- **资源 AB 加载**：新增 `MiniGameAssetLoader : IAssetLoader`——按需
|
||||
`AssetBundle.LoadFromFile(LocalDir + 资源AB)`，缓存已开包，按资产路径 `LoadAsset`，
|
||||
小游戏退出统一 `Unload(true)`。`MiniGameHost` 注入 `GameClientCtx` 的 loader 由
|
||||
`UnityAssetLoader`（走 XResLoader 大厅管线，不认识 minigame AB）换成它，并在
|
||||
`ExitGame` 补上此前 TODO 的 AB 卸载（MiniGameHost.cs:111）。
|
||||
|
||||
## 4. 错误处理、测试与配套
|
||||
|
||||
### 4.1 错误处理
|
||||
|
||||
- Editor 流水线每步检查退出码/产物存在性，失败即 `DisplayDialog` + 保留日志，
|
||||
临时目录不移入 CDN/deploy（无半成品）。
|
||||
- 覆盖已有版本目录：确认弹窗后先删旧目录再 Move。
|
||||
- 运行时：沿用 Fail/Error 路径；新增错误信息注明「需要 codeAb 格式，旧 .bytes 包不再支持」。
|
||||
|
||||
### 4.2 测试与验证
|
||||
|
||||
- **本环境可实证**：PublishTool 新布局 + Cli 的 xUnit（`dotnet test Server/Server.sln`
|
||||
全量回归）；两端 csproj 改造后 `dotnet build` 0 错；客户端改动照惯例 csc 编译验证。
|
||||
- **须 Unity 人工核对**（本环境无 Unity）：EditorWindow 交互、BuildAssetBundles
|
||||
跨平台产出、Editor Play 端到端（菜单生成 → Cdn.Runner 供 CDN → 网关
|
||||
`--gamesRoot deploy/minigame` → 进 RPS 对局）。
|
||||
|
||||
### 4.3 配套调整
|
||||
|
||||
- **删除 `Tools/PcMiniGameSmoke/Build-PcMiniGameSmoke.ps1`**：其裸 .bytes 产物格式
|
||||
运行时不再支持，且 ps1 打不了 AB；README 改指菜单。
|
||||
- **本地开发网关改指 `deploy/minigame`**：`XWorldUtil.MINI_GAME_SERVER_GAMES_ROOT`
|
||||
由 `../../Build/PcMiniGameSmoke/server/games` 改为指向仓库 `deploy/minigame`——
|
||||
菜单产物直接被 Play 自动起的本地网关消费，本地/外网同一份服务器产物布局；
|
||||
目录缺失提示改为「先跑 XWorld/生成小游戏更新」。
|
||||
- `.gitignore`：`Assets/MiniGameStaging/`、`Tools/keys/`（CDN/deploy 产物默认不 ignore；
|
||||
当前 `.git` 不可用、仓库无 .gitignore，此条待启用 git 后生效）。
|
||||
- WebGL 注意：`AssetBundle.LoadFromFile` 在 WebGL 不可用，运行时按平台走
|
||||
`LoadFromMemory(File.ReadAllBytes(...))` 回退（微信 WASM 实测仍是已知开放风险）。
|
||||
|
||||
### 4.3.1 修订（2026-07-07，用户定）：本地网关无条件启动，发布即生效
|
||||
|
||||
原 §4.3 给本地网关加的「`deploy/minigame` 下须有 game.json 才启动」检测与热更架构矛盾——
|
||||
服务器本就支持运行中热更（`ServerLoop.BuildGameList` 每次请求重扫目录；
|
||||
`GameModuleRegistry.Acquire` 建房时按需加载，新版本自动淘汰旧版本），不应做启动期存在性检测。
|
||||
|
||||
- `XWorldUtil` 删除 `HasMiniGameServerPackage()` 及其两处调用：`CanOpenLocalServer`
|
||||
只看网关 Runner DLL 存在；`StartMiniGameGatewayRunnerProcess` 删除
|
||||
「PC minigame package not found」弹框分支。
|
||||
- 启动前 `Directory.CreateDirectory(GetMiniGameServerGamesRoot())`（幂等）保证
|
||||
`--gamesRoot` 有效；目录下暂无任何 `*/*/game.json` 时仅 `Debug.Log` 提示
|
||||
「可随时用菜单发布，运行中即生效」，不打断。
|
||||
- ~~已知边界：同版本覆盖重发会因 `LoadFromAssemblyPath` 文件锁失败~~（已被 §4.3.2 消除）。
|
||||
- 大厅列表为实时扫描结果，客户端重新拉列表即见新游戏，不做推送（YAGNI）。
|
||||
|
||||
### 4.3.2 修订（2026-07-07，用户定方案 B）：字节加载去锁 + 内容指纹自动失效
|
||||
|
||||
消除"同版本覆盖重发被文件锁挡住"的问题，使覆盖重发也**发布即生效**（新房间用新代码，
|
||||
已入房玩家打完旧代码）：
|
||||
|
||||
- **GameModuleAlc 字节加载**：`LoadEntry` 与私有依赖解析两处 `LoadFromAssemblyPath`
|
||||
改为 `File.ReadAllBytes` + `LoadFromStream`——加载后不持有任何文件句柄，覆盖/删除
|
||||
目录永远成功；`Unload()` 仍惰性异步（无锁故无需强制 GC）。已知约束：字节加载的
|
||||
Assembly `Location` 为空，小游戏 DLL 不得依赖它。验签照旧不受影响。
|
||||
- **GameModuleRegistry 内容指纹失效**：`ComputeFingerprint(moduleDir)` = 目录下全部
|
||||
`*.dll`+`game.json` 按名 Ordinal 排序拼 `name=md5;` 再整体 md5。结构改为
|
||||
`_current`（key=`gameId@version`，Entry 加 Fingerprint）+ `_retired` 列表。
|
||||
`Acquire` 命中时重算磁盘指纹：相同 → 计数++返回；目录读不到（覆盖交换瞬间窗口）→
|
||||
视为未变化用缓存；不同 → 先加载新模块（失败旧条目原样保留），成功后旧条目标
|
||||
Superseded（引用 0 即卸载，否则挪 `_retired`），新条目入 `_current`。
|
||||
`Release` 改按模块实例识别（先 `_current` 同实例，否则 `_retired` ReferenceEquals）。
|
||||
`RefCount/IsLoaded` 语义指 `_current`。生产环境版本不可变、指纹恒命中，行为零变化。
|
||||
- 测试（TDD）：字节加载后磁盘 DLL 可删/可覆盖；同 key 内容变化 → 新实例 + 旧条目归零
|
||||
后弱引用 GC 断言卸载；新旧并存期各自 Release 正确；指纹未变命中缓存；现有
|
||||
Registry/AlcUnload/RoomHost 测试零回归。
|
||||
- 配套：PcMiniGameSmoke README 的文件锁注意事项改为"覆盖重发即生效"语义说明。
|
||||
|
||||
### 4.4 兼容性说明
|
||||
|
||||
- 旧格式（裸 .bytes、无平台段）的既有 CDN 产物在运行时改造后不再可用；当前仅 RPS 一款、
|
||||
由本流水线重新生成即可，无迁移负担。
|
||||
- 服务器端 game.json/DLL 布局不变，网关/GameModuleLoader 零改动。
|
||||
Reference in New Issue
Block a user