build-live-game

使用 Unity Gaming Services 构建实时游戏

开始之前

1. 从 ProjectSettings/ProjectVersion.txt 读取 Editor 版本，并从 Packages/packages-lock.json 读取已安装的 UGS 包版本。选择与之匹配的下方步骤（例如 .ccmu 或 .ccmr 模块），因为正确的工作流取决于 Editor 和包版本。
2. 检查项目是否已关联 Unity 项目 ID 和环境（Edit > Project Settings > Services），如果尚未关联，请让用户进行关联。
3. 创建可回滚的还原点，以便在更改失败时恢复：将项目提交到版本控制中。如果没有版本控制，请复制项目文件夹。
4. 在继续执行工作流或诊断之前，打开并阅读所用服务的文档页面（参见文档索引）以及 references/ 下对应的文件，并在回复中列出阅读过的页面。这样做是因为你掌握的 Unity Gaming Services 相关知识可能已经过时、有误，或不适用于当前包版本。
5. 只做用户要求的事。不要更改无关的资源或文件。避免长篇解释。
6. 更改运行时行为时，在需要验证的位置添加 Debug.Log 行（登录完成、模块调用返回、配置已获取）。在验证期间的 Play 模式中读取这些日志。

术语表

术语	含义
UGS	Unity Gaming Services：后端服务（Authentication、Cloud Code、Cloud Save、Remote Config、Leaderboards 等）。Package Manager 将它们称为“Unity Services”
Building Block	免费的 Asset Store 包，包含某项功能的 UI、运行时代码和云资源文件。其 Cloud Code 属于旧版 .ccmr
Cloud Code 模块	服务端 C# 类库。在 Unity 6000.5 及更高版本中，以 .ccmu 资源的形式在 Unity 项目中编写
.ccmr	旧版模块引用文件，指向在 Unity 之外构建的 C# 解决方案
Script	服务端 JavaScript 端点。旧版：保留现有端点，不要编写新端点
CloudBehaviour	实验性的 Cloud Code 类，可生成客户端绑定、同步状态和推送事件
受保护数据	Cloud Save 玩家数据，玩家可以读取，但只有服务端代码可以写入
自定义数据	Cloud Save 游戏级数据，不关联任何玩家，只能由服务端代码写入
云资源文件	可部署的配置文件（.rc、.ac、.ccmu、.ccmr、.lb、.ugo），Deployment Window 会将其推送到 UGS 环境

文档导航

优先使用 WebFetch，而非 WebSearch：速度更快，并且能直接打开准确的参考页面。只获取所需内容。docs.unity.com 上的页面可通过在 URL 末尾添加 .md 以 Markdown 格式访问。获取前，请将 <VERSION> 替换为以下内容：

• docs.unity3d.com 上的软件包：已安装软件包的版本号，格式为 major.minor，例如 3.0。如不确定，请从 Packages/packages-lock.json 中读取。
• docs.unity.com：以下 UGS 产品页面均不带版本号，因此无需替换。

执行操作前需阅读的页面：

• Cloud Code C# 模块：概览、入门、模块结构、错误处理、限制
• Cloud Code 服务端权威性：服务端权威性、防作弊、UGS 集成与访问控制
• 身份验证：身份验证的工作原理、会话与缓存玩家、常见错误
• Cloud Save：玩家数据、游戏数据、面向 Cloud Code 的 Cloud Save
• Remote Config：Remote Config 文件、代码集成
• Leaderboards：概览、Unity SDK 教程
• Deployment Window：部署软件包手册

UGS 软件包

软件包	最低版本	用途
com.unity.services.core	1.16.0	初始化、依赖关系图
com.unity.services.authentication	3.6.1	玩家登录与身份
com.unity.services.cloudcode	3.0.0	服务端权威 C# 模块，以 .ccmu 格式在项目中创作。2.10.x 系列仅部署旧版 .ccmr，详见下文
com.unity.services.cloudsave	3.4.0	单玩家及共享键值存储
com.unity.remote-config	4.2.5	服务端游戏配置
com.unity.services.deployment	1.7.2	从 Editor 部署云资源
com.unity.services.tooling	1.4.1	访问控制和 Game Overrides
com.unity.services.apis	1.1.1	所有 UGS 服务的生成式 REST 客户端

• 开始之前
• 术语表
• 文档导航
• 初始化模式
• 架构 — 软件包如何组合
• 核心服务 — 快速参考
• 常见架构模式
• 验证
• 详细参考
• 最终报告

初始化模式

每款 UGS 游戏的启动方式都相同。必须先初始化 com.unity.services.core，然后玩家登录：

using Unity.Services.Core;
using Unity.Services.Authentication;

await UnityServices.InitializeAsync();
await AuthenticationService.Instance.SignInAnonymouslyAsync();
// All other services are now ready

架构 — 包如何协同工作

                    UnityServices.InitializeAsync()
                              │
                              ▼
                     AuthenticationService
                    (sign in → PlayerId)
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        Remote Config     Cloud Save      Multiplayer
      (game config,    (player state,   (sessions,
       definitions,     progress,        matchmaking,
       feature flags)   preferences)     lobbies)
              │               │
              └───────┬───────┘
                      ▼
                 Cloud Code
              (server-authoritative
               writes, validation,
               anti-cheat logic)
                      │
              ┌───────┴───────┐
              ▼               ▼
         Cloud Save       Leaderboards
         (Protected       (score
          writes)          submission)

核心原则： 对于任何影响游戏完整性的数据（XP、奖励、货币），都应通过 Cloud Code 模块路由写入。直接从客户端写入仅适用于非敏感数据（偏好设置、显示设置）。

核心服务 — 快速参考

身份验证

包： com.unity.services.authentication (>= 3.6.1)

负责玩家身份；身份验证的工作原理介绍了各种登录方式。登录后，PlayerId 即可使用，并会触发 SignedIn 事件。PlayerAccountService（Unity 浏览器登录）位于单独的程序集中：Unity.Services.Authentication.PlayerAccounts。

• 完整参考： references/authentication.md

Cloud Code

包： 面向原生 .ccmu 编写的 com.unity.services.cloudcode 3.0.0（Unity 6000.5+）；>= 2.10.3 可维护旧版 .ccmr 模块。在编写 .ccmu 之前，如果清单固定使用 2.10.x，请将其升级到 3.0.0 或更高版本。

运行服务端 C# 模块（.NET 8；Unity 6.7+ 使用 .NET 10），用于执行可信操作。检查项目的 Editor 版本，然后在 Unity 6000.5+ 上将新模块编写为 .ccmu：在 Unity 项目中通过 Create > Services > Cloud Code Module Script 创建模块。Unity 会使用项目进行编译，并在编译时生成客户端绑定。.ccmr 属于旧版格式：在 6000.5+ 上仅维护现有模块；在更早版本的 Editor 上，将新模块编写为 .ccmr。 客户端只能通过生成的绑定调用 .ccmu 模块，切勿使用 CallModuleEndpointAsync。CloudCodeService.Instance.CallModuleEndpointAsync 仅用于旧版 .ccmr 模块。 仅在用户提出要求时才编写新的 JavaScript 脚本；维护现有脚本。

• 完整参考： references/cloud-code-modules.md

CloudBehaviours（实验性）可从单个 C# 类生成模块的客户端绑定，包括 RPC、同步状态和推送事件。可将其用于共享对局状态、每位玩家的机密状态或由服务端管理的计时器；其他情况请使用普通 Cloud Code 模块。需要 com.unity.services.cloudcode 3.1.0-exp.1+ 和 Unity 6000.5+。请先检查已安装的包：如果 CloudBehaviours 不可用，请改用普通有状态模块（[StateScope]，参见模块参考），不要因此停止，除非用户要求使用实验性包。

• 完整参考： references/cloud-code-cloudbehaviours.md

Cloud Save

包： com.unity.services.cloudsave (>= 3.4.0)

提供按玩家划分的键值存储，包含三种访问类别（Default、Public、Protected），以及面向整个游戏的 Custom 数据。Protected 和 Custom 数据只能由服务端代码写入，因此应在其中存储反作弊数据和由服务端发放的状态。每种类别的读写规则请参阅玩家数据和游戏数据。

• 完整参考： references/cloud-save.md

Remote Config

包： com.unity.services.remote-config (>= 4.2.5)

服务端游戏配置。将游戏定义（成就列表、战斗通行证等级、商店目录）存储为 JSON 条目，无需构建客户端即可更新。通过 Deployment Window 部署 .rc 文件。

如需 A/B 测试和受众定位，请通过 Tooling 包使用 Game Overrides（.ugo）。

• 完整参考： references/remote-config.md

工具

包： com.unity.services.tooling (>= 1.4.1)

仅限 Editor 使用的包。向 Deployment Window 注册 Access Control (.ac) 和 Game Overrides (.ugo) 文件类型。使用 Access Control 禁止玩家直接写入受保护的键；Deny 的优先级高于 Allow。

• 完整参考： references/tooling.md

部署

包： com.unity.services.deployment (>= 1.7.2)

仅限 Editor 使用的包，提供 Deployment Window（Services > Deployment）。将云资源部署到目标环境：

Deployment Window 会部署云资源文件：.rc（Remote Config）、.ac（Access Control）、.ccmu（项目内的 Cloud Code 模块，推荐）、.ccmr（旧版模块引用）、.lb（Leaderboard）和 .ugo（Game Overrides）。

• 完整参考： references/deployment.md

UGS CLI

UGS CLI 以 Unity CLI 插件形式提供，通过 unity ugs <command> 运行，可在 Editor 之外部署和获取云资源。安装、身份验证/设置以及它支持部署的文件类型：references/ugs-cli.md。插件系统：unity-cli 技能。

Services APIs

包： com.unity.services.apis (>= 1.1.1)

为所有 UGS 服务自动生成的 REST 客户端，分为四种客户端类型（IGameClient、IAdminClient、IServerClient、ITrustedClient）。默认使用高层级的包 SDK；仅在需要访问管理 API 或没有包 SDK 支持相应调用时使用 Services APIs。

• 完整参考： references/apis.md

常见架构模式

模式 1：配置 + 状态 + 服务端写入

用于 Battle Pass 和 Achievements：

1. 定义存储在 Remote Config（.rc 文件）中 — 游戏中存在的内容
2. 玩家状态存储在 Cloud Save 中 — 每位玩家的进度
3. 通过 Cloud Code 写入 — 由服务端权威控制的修改
4. Access Control（.ac 文件）— 阻止玩家直接写入敏感键

模式 2：客户端直接处理数据

用于 Player Account（偏好设置、显示设置）：

1. 玩家数据存储在 Cloud Save Default 或 Public 访问类别中
2. 客户端直接写入 — 非敏感数据无需使用 Cloud Code

模式 3：竞技功能

用于 Leaderboards 和排名系统：

1. 通过 Leaderboards API 提交分数（或通过 Cloud Code 验证后提交）
2. 在客户端通过分页和相对于玩家的查询获取排名

验证

为在线游戏功能编写代码后，请按顺序运行以下检查。如果某项检查失败，请修复原因并重新运行，然后再继续；如果修复无效，请返回并重新阅读相应的文档页面和 references/ 文件。

1. 检查项目是否能够编译：阅读 Editor 控制台（或 Editor 日志），确认没有编译错误。
2. 检查代码中的初始化顺序：搜索 UnityServices.InitializeAsync()，确认它在登录调用之前运行，并且登录完成后才会调用任何服务。
3. 检查敏感数据写入（XP、奖励、货币）是否通过 Cloud Code 进行：在客户端代码中搜索针对这些键的 Cloud Save SaveAsync 调用，并将找到的调用移至模块中。还要确认每次 Cloud Save 读取都使用写入数据所在存储桶的访问类别，因为类别不匹配会导致返回空数据。
4. 使用 references/deployment.md 中的 Deploy.cs 脚本，将功能使用的云资源文件（.rc、.ac、.ccmu 或 .ccmr、.lb；跳过未使用的类型）部署到当前环境，并查看脚本输出：每个文件都必须显示 Success。显示 not a deployable item 或状态为 Error 的文件均表示部署失败。如果项目没有脚本所需的两个包 com.unity.pipeline 和 com.unity.services.deployment.api，请让用户从 Deployment Window 部署，并报告每个文件的状态。
5. 通过效果检查 Access Control：如果该功能部署的 .ac 策略会拒绝玩家直接写入，请进入 Play 模式，运行一次对该策略涵盖的键进行直接客户端 Cloud Save 写入的操作（临时调用 SaveAsync），并确认该操作因 403 而失败。之后移除临时调用。如果该功能没有 .ac 文件，则跳过此步骤。
6. 进入 Play 模式，运行一次该功能，并确认 开始之前 中的 Debug.Log 行按预期顺序显示，且控制台没有错误。

详细参考

服务参考

• Authentication — 登录方法、事件、个人资料、身份提供商、代码模板：references/authentication.md
• Cloud Code — 模型选择：references/cloud-code.md；脚本和模块：references/cloud-code-modules.md；CloudBehaviours：references/cloud-code-cloudbehaviours.md
• Cloud Save — 访问类别、数据操作、文件、查询、代码模板：references/cloud-save.md
• Remote Config — 定义、.rc 格式、Game Overrides、代码模板：references/remote-config.md
• 工具 — Access Control（.ac）策略、Game Overrides（.ugo）、URN 参考：references/tooling.md
• 部署 — 文件类型、工作流、编程 API：references/deployment.md
• UGS CLI — 安装 unity ugs 插件、身份验证/设置、按文件类型进行无头部署：references/ugs-cli.md
• 服务 API — 四种客户端类型、服务领域、代码模板：references/apis.md

功能蓝图

• 选择起点 — 本技能的蓝图、Asset Store 构建模块和示例项目，以及如何复用它们的旧版 Cloud Code：references/blueprints-and-samples.md
• 成就 — 完整实现，包括数据模型、客户端代码、Cloud Code 模块和云资源：references/achievements.md
• 战斗通行证 — 实现分级 XP、免费/高级路线、Cloud Code 模块和云资源（高级版购买功能是需要你完成的集成桩）：references/battlepass.md
• 玩家账户 — 登录流程、身份管理、Cloud Save 数据和代码模板：references/player-account.md

最终报告

完成工作后，请在回复末尾附上简短报告：

1. 你创建或更改的内容：文件、添加到 Packages/manifest.json 的包，以及云资源文件。
2. 你运行的 验证 检查及其结果，包括无法运行的检查及原因。
3. 仅需用户完成的后续事项，例如：将云资源部署到目标环境、将项目关联到 Unity 项目 ID 和环境、完成桩接入（例如战斗通行证的 PurchasePremium），或在用户拒绝更改时从你创建的还原点恢复。
4. 你阅读过的文档页面。