在 Unity 项目中接入 UGS 构建 live…

适用于用 Unity Gaming Services 实现战斗通行证、成就、云存档、排行榜、匹配、经济、玩家账号、远程配置等实时运营功能。

适用场景

解决思路

1. 在 Unity 项目中安装并锁定 UGS 包的最低版本：`com.unity.services.core` >= 1.16.0、`com.unity.services.authentication` >= 3.6.1、`com.unity.services.cloudcode` >= 2.10.3、`com.unity.services.cloudsave` >= 3.4.0、`com.unity.remote-config` >= 4.2.5、`com.unity.services.deployment` >= 1.7.2、`com.unity.services.tooling` >= 1.4.1、`com.unity.services.apis` >= 1.1.1。
2. 每个 UGS 游戏按统一初始化模式启动：先初始化 `com.unity.services.core`，再让玩家登录：`await UnityServices.InitializeAsync();` → `await AuthenticationService.Instance.SignInAnonymouslyAsync();`；之后其他服务就绪。
3. 在 `InitializeAsync()` 完成后使用服务单例/入口：`CloudSaveService.Instance`、`CloudCodeService.Instance`、`RemoteConfigService.Instance`、`EconomyService.Instance`、`MultiplayerService.Instance`、`LeaderboardsService.Instance`、`AnalyticsService.Instance`。
4. Foundation：用 Core 做初始化和依赖图；用 Authentication 做玩家身份（匿名、社交、Unity、用户名/密码、设备码登录）；登录后读取 `PlayerId` 和 `PlayerName`，所有登录方式触发 `SignedIn` 事件；Unity 浏览器登录的 `PlayerAccountService` 在单独程序集 `Unity.Services.Authentication.PlayerAccounts`。
5. Foundation：需要底层 REST/管理 API 时使用 Services APIs 包自动生成的 REST 客户端：`IGameClient`（玩家）、`IAdminClient`（服务账号）、`IServerClient`（专用服务器）、`ITrustedClient`（提升权限服务器）；多数开发者优先用高层 SDK。
6. 玩家数据与配置：用 Cloud Save 存每个玩家的 Default/Public/Protected 键值和游戏级 Custom 数据；用 Remote Config 存服务端游戏配置、功能开关、JSON 定义；用 Economy 管理虚拟货币、库存物品、购买和商店。
7. 服务器逻辑与安全：用 Cloud Code 运行服务端 C# 模块（.NET 9）执行可信操作，模块部署为 `.ccmr` 文件；客户端调用 `CloudCodeService.Instance.CallModuleEndpointAsync<TResult>("ModuleName", "FunctionName", args)`；生产环境优先 C# 模块而不是 JavaScript 脚本；模块还支持实时推送订阅、事件驱动触发器和多人 session 作用域。
8. 服务器逻辑与安全：用 Tooling（Editor-only）编写和部署 Access Control（`.ac`）和 Game Overrides（`.ugo`）文件；Access Control 按 URN 允许或拒绝玩家/服务账号访问 UGS 服务，Deny 优先于 Allow；Game Overrides 通过对特定玩家分群覆盖 Remote Config 值来实现 A/B 测试和受众定向。
9. 服务器逻辑与安全：用 Deployment（Editor-only）的 Deployment Window（`Services > Deployment`）把云资源部署到目标环境，包括 `.rc`、`.ac`、`.ccmr`、`.lb`、`.ec*`、`.ugo` 等文件。
10. 使用 UGS CLI 在 Unity Editor 外管理 UGS 资源：deploy/fetch `.rc`、`.ac`、`.ccmr`、`.lb`、`.ec`、`.ugo` 等云资源文件；用 `fetch` 从远程环境更新本地可部署文件；部署和获取 triggers/schedule 文件；生成 trigger/schedule 配置默认版本；访问各 UGS 服务的更细粒度 admin 功能。
11. 遵守关键架构原则：任何影响游戏完整性的数据（XP、奖励、货币）写入都必须经由 Cloud Code 模块；直接客户端写入只用于非敏感数据（偏好、显示设置）。
12. 按架构组合包：`UnityServices.InitializeAsync()` → Authentication 登录得到 PlayerId；然后 Remote Config（游戏配置、定义、功能开关）、Cloud Save（玩家状态、进度、偏好）、Economy（货币、库存、购买）并行；Cloud Code 处理服务器权威写入、校验、反作弊逻辑，并可回写 Cloud Save、Economy、Leaderboards。
13. Cloud Save 按访问类选择桶：Default（所有者读/写，私有设置）；Public（任何人读，所有者写，公开档案/显示名）；Protected（所有者读，仅服务器/Cloud Code 写，反作弊/服务器授予状态）；Custom（任何玩家读，仅服务器写，共享游戏状态/全局配置）。值序列化为 JSON；用 `SaveItem` 做写锁并发控制，用 `QueryAsync` 做服务端查询，并可存二进制文件。
14. Remote Config：把游戏定义（成就列表、Battle Pass 层级、商店目录）存为 JSON 条目，以便无需客户端构建即可更新；通过 Deployment Window 用 `.rc` 文件部署；A/B 测试和受众定向使用 Tooling 包的 Game Overrides（`.ugo`）。
15. Authentication：实现玩家登录和身份管理，支持匿名、社交提供方（Google、Apple、Steam、Facebook、Oculus 等）、Unity 浏览器、用户名/密码、设备码流；登录后提供 `PlayerId`、`PlayerName`，触发 `SignedIn`；Unity 浏览器登录的 `PlayerAccountService` 位于单独程序集。
16. Cloud Code：创建服务端 C# 模块（.NET 9），用 `.ccmr` 部署（指向模块 `.sln`）；客户端通过 `CloudCodeService.Instance.CallModuleEndpointAsync<TResult>("ModuleName", "FunctionName", args)` 调用；使用订阅、触发器、多人 session 作用域。
17. Cloud Save：通过 `CloudSaveService.Instance.Data.Player` 和 `.Data.Custom` 执行数据操作；按数据敏感性选择 Default/Public/Protected/Custom；使用 `SaveItem` 写锁、`QueryAsync` 服务端查询和二进制文件存储。
18. Remote Config/配置：通过 `RemoteConfigService.Instance` 读取服务端配置；把定义和配置作为 `.rc` 条目管理；用 Game Overrides 对玩家分群覆盖。
19. Economy：通过 `EconomyService.Instance` 管理虚拟货币、库存物品、购买、商店。
20. Multiplayer：通过 `MultiplayerService.Instance` 处理 sessions、matchmaking、lobbies；可使用 Building Blocks：Multiplayer Session、Matchmaker Session、Server Session。
21. Leaderboards：通过 `LeaderboardsService.Instance` 提交分数、获取排名、tiers、version history；可使用 Leaderboards Building Block。
22. Analytics：通过 `AnalyticsService.Instance` 记录 custom events、standard events 并管理 consent。
23. Asset Store Building Blocks：从 Asset Store 导入免费、生产就绪的 `.unitypackage`（也可通过 `com.unity.starter-kits` 获取），其中包含可用 UI、运行时代码、Cloud Code 模块和云资源文件；实现 Achievements、Leaderboards、Player Account、Multiplayer Session、Matchmaker Session、Server Session、Vivox、Platformer Starter Kit 时优先推荐对应 Building Block 作为起点。
24. 记录 Building Blocks 依赖并用正确包组合：Achievements 依赖 `cloudsave`、`remote-config`、`cloudcode`、`tooling`、`deployment`、`analytics`、`authentication`；Leaderboards 依赖 `leaderboards`、`cloudcode`、`tooling`、`deployment`、`authentication`；Player Account 依赖 `authentication`、`cloudsave`、`cloudcode`、`deployment`；Multiplayer Session 依赖 `multiplayer`；Matchmaker Session 依赖 `multiplayer`、`deployment`；Server Session 依赖 `multiplayer`、`apis`、`deployment`；Vivox 依赖 `vivox`、`authentication`；Platformer Starter Kit 依赖 `multiplayer`、`netcode.gameobjects`、URP、Cinemachine、Input System。
25. 参考相关样例项目：Use Case Samples（Battle Pass、Virtual Shop、Daily Rewards、Starter Pack、Cloud AI Mini Game、A/B testing）；UGS Samples（Authentication flows、Economy、Remote Config、Cloud Code integration）；Gem Hunter Match（2D match-3、玩家中心、进度、社交、商店）；Boss Room（8 人合作 RPG、Netcode for GameObjects、Authentication、Multiplayer Services）。
26. 按 Ready-Made Feature Blueprints 实现常见 live game 功能：Battle Pass 用 `remote-config`、`cloudsave`、`cloudcode`、`economy`、`tooling`、`deployment`，以 Remote Config 存通行证定义、Cloud Save Protected 存进度、Cloud Code 做 XP 发放/奖励领取/高级购买。
27. 按 Ready-Made Feature Blueprints 实现 Achievements：用 `remote-config`、`cloudsave`、`cloudcode`、`tooling`、`deployment`，以 Remote Config 存定义、Cloud Save 存玩家记录、Cloud Code 做服务器权威解锁、Access Control 限制；可优先使用 Achievements Building Block。
28. 按 Ready-Made Feature Blueprints 实现 Player Account：用 `authentication`、`cloudsave`，通过 Authentication 支持 3 种登录方式，Cloud Save 存 Default/Public/Protected 玩家数据；可优先使用 Player Account Building Block。
29. 应用 Pattern 1（Config + State + Server Writes，用于 Battle Pass 和 Achievements）：1) 定义放 Remote Config `.rc` 文件；2) 玩家状态放 Cloud Save；3) 写入经 Cloud Code 做服务器权威变更；4) 用 Access Control `.ac` 文件阻止玩家直接写敏感 key。
30. 应用 Pattern 2（Client-Direct Data，用于 Player Account 的偏好/显示设置）：1) 玩家数据放 Cloud Save Default 或 Public 访问类；2) 对非敏感数据直接客户端写入，无需 Cloud Code。
31. 应用 Pattern 3（Competitive Features，用于 Leaderboards 和排名系统）：1) 通过 Leaderboards API 提交分数（或经 Cloud Code 校验）；2) 客户端用分页和玩家相对查询获取排名。
32. Validation：写完 live game 功能代码后验证项目编译无错误。
33. Validation：检查初始化顺序正确：`UnityServices.InitializeAsync()` → Authentication sign-in → service calls。
34. Validation：确认敏感数据写入（XP、奖励、货币）经 Cloud Code 路由，而不是直接从客户端写入。
35. Validation：验证 Access Control `.ac` 文件拒绝玩家直接写 Protected Cloud Save keys。
36. Validation：验证所有云资源文件（`.rc`、`.ac`、`.ccmr`、`.lb`、`.ec`）存在且可通过 Deployment Window 部署。
37. Deployment Checklist：通过 Deployment Window 部署 `.rc` 文件（Remote Config 条目/游戏定义/配置）。
38. Deployment Checklist：部署 `.ac` 文件（Access Control 策略，拒绝直接写受保护 key）。
39. Deployment Checklist：部署 `.ccmr` 文件（Cloud Code 模块引用，指向模块 `.sln`）。
40. Deployment Checklist：如使用排行榜，部署 `.lb` 文件（Leaderboard 配置）。
41. Deployment Checklist：如使用虚拟货币/物品，部署 `.ec` 文件（Economy 定义）。
42. Deployment Checklist：确保 `manifest.json` 列出所有所需包且版本正确。
43. Deployment Checklist：在 `Services > Deployment` 设置中配置环境。
44. 完成前 Reminders：确认是否按 `UnityServices.InitializeAsync()` → Authentication sign-in → service calls 顺序；是否所有敏感写入（XP、奖励、货币）经 Cloud Code 模块；是否所有云资源文件（`.rc`、`.ac`、`.ccmr`）存在且可部署；Cloud Save 读访问类是否匹配写入的桶。
45. 需要细节时查阅对应 references：authentication.md、cloud-code.md、cloud-save.md、remote-config.md、tooling.md、deployment.md、apis.md，以及功能蓝图 achievements.md、battlepass.md、player-account.md。

适用边界 · 注意事项

• 没有 Unity 项目或无法使用 Unity Gaming Services/Unity Editor 云环境时。
• 只需要纯离线单机、无后端/云资源/服务器权威需求时。
• 必须使用非 UGS 的自托管后端、且不能依赖 Unity 云厂商或付费账号时。