# 版本配置与身份来源

返回[构建目录](README.md)。具体操作见[单游戏构建](single-game-build.md)。本文维护版本字段、身份来源及 XML 构建扩展的职责。

## 1. version.xml 是身份和版本唯一配置文件

源文件在各子游戏目录中：二七王为 `assets/games/erqiwang/resources/erqiwang/version.xml`，模板为 `assets/games/template/resources/Game_Surface_3/version.xml`。路径相对于 YouleNexus，本文不复制第二份配置。

结构保持原生既有格式：XML 声明、game 根节点，以及 agent/game/channel/version 子节点。

- agent@id：网页默认 agentid。
- channel@id：网页默认 channelid。
- 子节点 game@id：服务器 gameid。
- version@value：数值 versionCode，发送到登录包的 version 字段。
- version@name：字符串展示版本 version，登录页显示为 v 加该字符串。
- agent/game/channel 的 name 属性保留供原生读取，必须显式提供。

网页和构建共用这一份源 XML。构建出的副本由工具产生，不手工维护，不反向当作源码编辑。

不要把展示字符串（例如 1.8）作为登录数值版本发送。通用协议部分早期类型描述与真实登录校验存在历史差异，数值约定及实包依据见[数据结构说明](../protocol/04-数据结构.md)。

## 2. 网页与原生身份来源

网页预览从选中游戏的 XML 生成启动身份。原生环境 agentid/channelid/marketid 继续通过既有 settings/uAgent_3 接口读取，缺失时显式报错；gameid 与版本仍来自 XML。

原 XML 没有 marketid。网页的唯一 marketid 配置在应用层 `build-identity.ts` 的 WEB_MARKET_ID，当前为 4。不要为此擅自改变原生 XML 格式。

现有启动解析器仍支持显式 URL agentid/channelid/marketid/version 调试覆盖；gameid 不接受 URL 覆盖。普通预览不传身份参数即可使用 XML。URL version 如使用，含义是数值协议版本，而不是展示版本。

当前 XML 保留当前开发注册身份和 versionCode=1；展示版本二七王为 1.8、模板为 1.1。正式部署要在这份源 XML 中核对真实发布身份与版本，不照搬旧工程过期注册值。

## 3. 版本资源包设置

每个游戏的 resources 文件夹在编辑器中配置 Asset Bundle：

版本 Bundle 优先级为 2，游戏根目录 `game-<gameKey>` Bundle 优先级为 1。不要使用相同优先级，否则嵌套 XML 可能归入父包，版本包变为空包。

- 二七王目录 `assets/games/erqiwang/resources`：bundleName 为 `version-erqiwang`。
- 模板目录 `assets/games/template/resources`：bundleName 为 `version-Game_Surface_3`。

运行时加载 `version-<gameKey>`，再加载包内 `<gameKey>/version` TextAsset。嵌套的 resources 目录不会自动进入全局 resources 包，必须完成上述配置。文件扩展名仍是 .xml，加载路径不带扩展名。

game-config.ts 只定位资源，不保存第二份 gameid 或版本。包名、路径和已保存的场景 gameKey 不一致时应修正来源，不能通过运行时备用路径掩盖。

## 4. 构建操作入口

按[单游戏构建操作](single-game-build.md)选择 gameKey、场景和 Bundle，并校验实际输出。游戏包与版本包必须配对选择，同时保留公共 resources。

Web Mobile 已做真实构建验证；Web Desktop 注册同一 hook 并通过接口测试，但不把这一点当作所有平台都完成了真实验收。

## 5. 构建扩展做了什么

项目扩展名为 **Youle Version Manifest**，实现目录为 `extensions/youle-version-manifest`。新编辑器环境需要确认已启用。

扩展读取构建任务真正的 startScene，而不是猜测当前编辑器正在显示哪个场景。它查找场景中唯一且启用的 SubgameAssets，然后在各游戏目录中查找唯一 `resources/<gameKey>/version.xml`。

构建前验证 XML、版本资源包元数据并保留快照。构建后验证启动场景未变、所选版本 bundle 确实包含在产物、源 XML/场景/元数据未变，再把 XML 字节原样写到实际输出根目录。

无效 XML、重复来源、磁盘场景中的无效选择、缺失所选版本 bundle、构建中来源变化都会阻止构建。扩展只读取已保存场景，不能替用户保存或识别 Inspector 中尚未保存的游戏切换。

扩展不会自动勾选游戏包、自动排除其他游戏、检查版本包内所有资源路径或扫描所有生成代码。看到 XML 发布成功日志，仍需完成单游戏产物检查。失败产物不能当成可发布结果。

## 6. 开发构建与正式发布的区别

当前 `profiles.ts` 是 debug、本地配置、连接本机 127.0.0.1:3088。刚构建出的包不会因为 Cocos 取消 Debug 就自动切换正式服务器；本地配置加载器也不允许在非调试构建使用本地配置。工程的脚本 loose 设置保持 false，避免对标准集合遍历产生不正确的降级编译结果。

目前环境配置仍位于框架历史 profiles.ts，这是尚未完成的应用层配置迁移，不符合未来“发布时无需修改框架”的完整目标。不要把修改它当作每个子游戏接入的步骤。正式发布前，需要完成应用发布环境注入或作为独立框架任务迁移这处配置，并验证 remote/release 的真实来源。

## 7. 当前限制与后续构建方向

- gameKey 选择游戏入口和私有 prefab；roomScene 保持公共承载场景绑定。
- XML 选择和根目录输出已经自动化。
- 公共应用层已解除具体游戏静态导入。构建需显式保留公共 resources、目标游戏和目标版本 Bundle；gameKey 尚未自动同步构建面板勾选项。
- 原有仓库 `scripts/build-game.mjs` 使用另外的子工程实体化流程，不是当前 YouleNexus 同工程游戏选择的一键入口；不要直接把它当成这里的构建命令。
- 未来统一构建入口应在应用/工具层完成选择、资源装配、环境注入与产物裁剪，并验证导出包仅含目标游戏，不随游戏切换修改框架。

## 8. 验证命令与常见故障

从 cocoscreator_projects 目录运行：

```powershell
node scripts/check-import-boundaries.mjs
node scripts/check-room-assets.mjs
node --test scripts/test/version-manifest-build.test.mjs
node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit
```

引擎运行验证脚本 `verify-version-xml-preview.mjs` 需通过 Cocos MCP 在 Game View 上下文执行，不能直接在普通 Node 中运行。它会尝试加载两款游戏，适用于包含两款游戏资源的开发预览，不适用于已排除其他游戏的单游戏发布包。单游戏产物按[导出运行验证](single-game-build.md#7-运行与回归验证)检查。

- `Missing subgame entry`：目标 Bundle 未注册 GameEntry_<gameKey>。
- `Cannot load version-...`：版本目录未设为对应 bundle，或构建排除了它。
- `Version resource does not match selected game`：game-config 中的路径与 gameKey 不一致。
- 根目录没有 XML：确认构建扩展已启用、所选启动场景正确，并查看构建日志；不要手动复制文件后掩盖失败。
- 切换游戏仍出现旧创建页面：检查本游戏 definition.resources 与 gameKey。
- 登录包的版本错误：核对 XML value 及是否传了 URL version 调试参数，不把 XML name 发给服务器。