build-live-game

使用 Unity Gaming Services 构建实时游戏

UGS 软件包

软件包	最低版本	用途
com.unity.services.core	1.16.0	初始化、依赖关系图
com.unity.services.authentication	3.6.1	玩家登录和身份
com.unity.services.cloudcode	2.10.3	由服务器权威控制的 C# 模块
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	访问控制和游戏覆盖
com.unity.services.apis	1.1.1	所有 UGS 服务的生成式 REST 客户端

• 初始化模式
• 软件包一览
• 架构 — 软件包如何组合
• 核心服务 — 快速参考
• Asset Store 构建模块
• 现成的功能蓝图
• 常见架构模式
• 验证
• 部署清单
• 详细参考

初始化模式

所有 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

InitializeAsync() 完成后，服务单例（例如 CloudSaveService.Instance、CloudCodeService.Instance）即可使用。

软件包一览

基础

软件包	用途	单例 / 入口点
Core	初始化、依赖关系图、组件注册表	UnityServices.InitializeAsync()
Authentication	玩家登录（匿名、社交、Unity、用户名/密码）、身份	AuthenticationService.Instance
Services APIs	所有 UGS 服务的生成式 REST 客户端；通过服务帐户访问管理 API	直接使用 API 类

玩家数据和配置

软件包	用途	单例 / 入口点
Cloud Save	每位玩家的键值数据（Default、Public、Protected）和游戏范围的 Custom 数据	CloudSaveService.Instance.Data.Player / .Data.Custom
Remote Config	服务器端游戏配置、功能标志、JSON 定义	RemoteConfigService.Instance

服务器逻辑和安全

软件包	用途	单例 / 入口点
Cloud Code	用于可信写入和验证、由服务器权威控制的 C# 模块	CloudCodeService.Instance → CallModuleEndpointAsync
Tooling	创建和部署 Access Control（.ac）与 Game Overrides（.ugo）文件	仅限 Editor（Deployment Window）
Deployment	从 Unity Editor 部署云资源（.rc、.ac、.ccmr、.lb 等）	仅限 Editor（Services > Deployment）

社交和竞技

软件包	用途	单例 / 入口点
Multiplayer	会话、匹配、游戏大厅。构建模块：Multiplayer Session、Matchmaker Session、Server Session	MultiplayerService.Instance
Leaderboards	提交分数、排名、等级、版本历史。构建模块：Leaderboards	LeaderboardsService.Instance

遥测

软件包	用途	单例 / 入口点
Analytics	自定义事件、标准事件、同意管理	AnalyticsService.Instance

架构 — 软件包如何组合

                    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 模块路由写入操作。只有对于非敏感数据（偏好设置、显示设置），才适合由客户端直接写入。

核心服务 — 快速参考

身份验证

Package: com.unity.services.authentication (>= 3.6.1)

处理玩家身份。登录方式包括：匿名、社交平台（Google、Apple、Steam、Facebook、Oculus 等）、Unity 浏览器、用户名/密码和设备代码流程。

登录后，可使用 PlayerId 和 PlayerName。所有登录方式都会触发 SignedIn 事件。PlayerAccountService（用于 Unity 浏览器登录）位于单独的程序集（Unity.Services.Authentication.PlayerAccounts）中。

• 完整参考： references/authentication.md
• Building Block： 玩家账户 — 提供现成的登录界面和身份管理功能

Cloud Code

Package: com.unity.services.cloudcode (>= 2.10.3)

运行服务器端 C# 模块（.NET 9），执行可信操作。模块以 .ccmr 文件的形式部署。客户端调用：

var result = await CloudCodeService.Instance.CallModuleEndpointAsync<TResult>(
    "ModuleName", "FunctionName", args);

生产环境中，优先使用 C# 模块，而非 JavaScript 脚本。模块还支持通过订阅发送实时推送消息、事件驱动触发器以及多人游戏会话范围限定。

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

Cloud Save

Package: com.unity.services.cloudsave (>= 3.4.0)

提供按玩家划分的键值存储，包含三种访问类别，以及面向整个游戏的 Custom 数据：

访问类别	读取	写入	用例
Default	所有者	所有者	私有设置、偏好设置
Public	任何人	所有者	公开个人资料、显示名称
Protected	所有者	仅服务器（Cloud Code）	反作弊数据、服务器授予的状态
Custom	任何玩家	仅服务器	共享游戏状态、全局配置

值以 JSON 格式序列化。支持通过 SaveItem 实现写入锁并发控制、通过 QueryAsync 执行服务器端查询，以及二进制文件存储。

• 完整参考： references/cloud-save.md
• Building Blocks： 成就（Protected 存储桶）和玩家账户（Default/Public 数据）均使用此功能

Remote Config

Package: com.unity.services.remote-config (>= 4.2.5)

服务器端游戏配置。可将游戏定义（成就列表、战斗通行证等级、商店目录）存储为 JSON 条目，并在不构建客户端的情况下更新。通过 Deployment Window 使用 .rc 文件部署。

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

• 完整参考： references/remote-config.md
• Building Block： 成就模块使用此功能提供服务器端定义

Tooling

Package: com.unity.services.tooling (>= 1.4.1)

仅限编辑器使用的 package。向 Deployment Window 注册 Access Control（.ac）和 Game Overrides（.ugo）文件类型。Access Control 策略按 URN 允许或拒绝玩家/服务账户访问 UGS 服务（拒绝优先于允许）。Game Overrides 通过为特定玩家群体覆盖 Remote Config 值，提供 A/B 测试和受众定位功能。

• 完整参考： references/tooling.md

Deployment

Package: com.unity.services.deployment (>= 1.7.2)

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

文件类型	扩展名	部署内容
Remote Config	.rc	键值配置条目
Access Control	.ac	资源访问策略
Cloud Code Module	.ccmr	C# 服务器端模块（指向 .sln）
Leaderboard	.lb	Leaderboard 配置
Game Overrides	.ugo	面向特定受众的配置覆盖项

• 完整参考： references/deployment.md

UGS CLI

Unity Gaming Services CLI 是一款独立的命令行工具，可在 Unity Editor 外管理 UGS 资源。它可以部署和获取云资源文件（.rc、.ac、.ccmr、.lb、.ugo），通过 fetch 操作将可部署文件更新为远程环境中的版本，部署和获取触发器及计划文件，生成触发器和计划配置的默认版本，并提供对所有 UGS 服务管理功能更细致的访问权限。

Services APIs

包： com.unity.services.apis（>= 1.1.1）

为所有 UGS 服务自动生成的 REST 客户端。包含四种客户端类型：IGameClient（玩家）、IAdminClient（服务账户）、IServerClient（专用服务器）、ITrustedClient（提升权限的服务器访问）。大多数开发者会使用较高层级的包 SDK；如需更底层的控制或访问管理 API，请使用 Services APIs。

• 完整参考： references/apis.md

Asset Store 构建模块

Unity 在 Asset Store 上提供免费的、可用于生产环境的构建模块包。每个包都是一个 .unitypackage，包含可运行的 UI、运行时代码、Cloud Code 模块和云资源文件，可直接导入项目。它们也包含在 com.unity.starter-kits 包中。

构建模块	类型	主要依赖项	Asset Store
成就	LiveOps	cloudsave、remote-config、cloudcode、tooling、deployment、analytics、authentication	Unity 构建模块 — 成就
排行榜	LiveOps	leaderboards、cloudcode、tooling、deployment、authentication	Unity 构建模块 — 排行榜
玩家账户	LiveOps	authentication、cloudsave、cloudcode、deployment	可通过 com.unity.starter-kits 获取
多人游戏会话	多人游戏	multiplayer	Unity 构建模块 — 多人游戏会话
Matchmaker 会话	多人游戏	multiplayer、deployment	Unity 构建模块 — Matchmaker 会话
服务器会话	多人游戏	multiplayer、apis、deployment	可通过 com.unity.starter-kits 获取
Vivox	多人游戏	vivox、authentication	可通过 com.unity.starter-kits 获取
平台跳跃游戏入门套件	游戏玩法	multiplayer、netcode.gameobjects、URP、Cinemachine、Input System	可通过 com.unity.starter-kits 获取

提示： 实现成就、排行榜、玩家账户或多人游戏会话时，建议以相应的构建模块作为起点。这些模块包含现成的 UI、Cloud Code 模块（.ccmr）、访问控制（.ac）和可直接部署的云资源，可大幅节省实现时间。

相关示例项目

项目	描述	来源
用例示例	战斗通行证、虚拟商店、每日奖励、新手礼包、云端 AI 小游戏、A/B 测试	GitHub — com.unity.services.samples.use-cases
UGS 示例	身份验证流程、Remote Config、Cloud Code 集成	GitHub — com.unity.services.samples
宝石猎人消消乐	完整的 2D 三消游戏，包含玩家中心、成长系统、社交功能和游戏内商店	Asset Store
Boss Room	使用 Netcode for GameObjects、Authentication 和 Multiplayer Services 的 8 人合作 RPG	GitHub — com.unity.multiplayer.samples.coop

开箱即用的功能蓝图

用于常见在线游戏功能、可直接投入实现的蓝图。每份蓝图均包含数据模型、服务 API 模式、完整可运行的代码，以及云资源定义。

功能	主要服务	蓝图
战斗通行证	remote-config、cloudsave、cloudcode、tooling、deployment — Remote Config（通行证定义）+ Cloud Save Protected（进度）+ Cloud Code（经验值发放、奖励领取、高级版购买）	references/battlepass.md
成就	remote-config、cloudsave、cloudcode、tooling、deployment — Remote Config（定义）+ Cloud Save（玩家记录）+ Cloud Code（由服务器权威控制的解锁）+ Access Control。Asset Store：Achievements Building Block	references/achievements.md
玩家账户	authentication、cloudsave — Authentication（3 种登录方式）+ Cloud Save（Default/Public/Protected 玩家数据）。**Asset Store：**Player Account Building Block（通过 com.unity.starter-kits）	references/player-account.md

常见架构模式

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

战斗通行证和成就均采用此模式：

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

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

玩家账户（偏好设置、显示设置）采用此模式：

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

模式 3：竞技功能

排行榜和排名系统采用此模式：

1. 通过 Leaderboards API 提交分数（或通过 Cloud Code 进行验证）
2. 在客户端获取排名，支持分页和以玩家为基准的查询

验证

为在线游戏功能编写代码后：

1. 确认项目可成功编译且没有错误。
2. 检查初始化顺序是否正确：UnityServices.InitializeAsync() → Authentication 登录 → 服务调用。
3. 确认敏感数据写入（经验值、奖励、货币）通过 Cloud Code 进行，而不是直接从客户端写入。
4. 确认 Access Control .ac 文件禁止玩家直接写入 Protected Cloud Save 键。
5. 确认所有云资源文件（.rc、.ac、.ccmr、.lb）均已就绪，可通过 Deployment Window 部署。

部署检查清单

对于任何线上游戏功能，请通过 Deployment Window 部署以下云资源：

• .rc 文件 — Remote Config 条目（游戏定义、配置）
• .ac 文件 — 访问控制策略（禁止直接写入受保护的键）
• .ccmr 文件 — Cloud Code 模块引用（指向模块 .sln）
• .lb 文件 — 排行榜配置（如果使用排行榜）
• manifest.json — 确保列出了所有必需的软件包及其正确版本
• 在 Services > Deployment 设置中配置环境

详细参考

服务参考

• 身份验证 — 登录方式、事件、个人资料、身份提供方、代码模板：references/authentication.md
• Cloud Code — 脚本、模块、订阅、触发器、模块创建、代码模板：references/cloud-code.md
• Cloud Save — 访问类别、数据操作、文件、查询、代码模板：references/cloud-save.md
• Remote Config — 定义、.rc 格式、Game Overrides、代码模板：references/remote-config.md
• 工具 — 访问控制（.ac）策略、Game Overrides（.ugo）、URN 参考：references/tooling.md
• 部署 — 文件类型、工作流、编程 API：references/deployment.md
• 服务 API — 四种客户端类型、服务领域、代码模板：references/apis.md

功能蓝图

• 成就 — 完整实现，包含数据模型、客户端代码、Cloud Code 模块和云资源：references/achievements.md
• 战斗通行证 — 实现包含分级 XP、免费/高级路线、Cloud Code 模块和云资源（高级购买是需要你完成的集成存根）：references/battlepass.md
• 玩家账号 — 登录流程、身份管理、Cloud Save 数据、代码模板：references/player-account.md

提醒

完成前，请确认：

• 是否按以下顺序调用了 UnityServices.InitializeAsync() → Authentication 登录 → 服务调用？
• 所有敏感写入（XP、奖励、货币）是否都通过 Cloud Code 模块处理？
• 所有云资源文件（.rc、.ac、.ccmr）是否都已就绪并可部署？
• Cloud Save 读取访问类别是否与写入数据的存储桶匹配？