build-live-game

# Build a Live Game With Unity Gaming Services ## UGS Packages | Package | Min Version | Purpose | |---|---|---| | `com.unity.services.core` | 1.16.0 | Initialization, dependency graph | | `com.unity.services.authentication` | 3.6.1 | Player sign-in and identity | | `com.unity.services.cloudcode` | 2.10.3 | Server-authoritative C# modules | | `com.unity.services.cloudsave` | 3.4.0 | Per-player and shared key-value storage | | `com.unity.remote-config` | 4.2.5 | Server-side game configuration | | `com.unity.services.deployment` | 1.7.2 | Deploy cloud resources from Editor | | `com.unity.services.tooling` | 1.4.1 | Access Control and Game Overrides | | `com.unity.services.apis` | 1.1.1 | Generated REST clients for all UGS services | - [Initialization Pattern](#initialization-pattern) - [Package Map](#package-map) - [Architecture — How Packages Combine](#architecture--how-packages-combine) - [Core Services — Quick Reference](#core-services--quick-reference) - [Asset Store Building Blocks](#asset-store-building-blocks) - [Ready-Made Feature Blueprints](#ready-made-feature-blueprints) - [Common Architecture Patterns](#common-architecture-patterns) - [Validation](#validation) - [Deployment Checklist](#deployment-checklist) - [Detailed References](#detailed-references) ## Initialization Pattern Every UGS game starts the same way. `com.unity.services.core` must initialize first, then the player signs in: ```csharp using Unity.Services.Core; using Unity.Services.Authentication; await UnityServices.InitializeAsync(); await AuthenticationService.Instance.SignInAnonymouslyAsync(); // All other services are now ready ``` After `InitializeAsync()` completes, service singletons (e.g. `CloudSaveService.Instance`, `CloudCodeService.Instance`) are available. ## Package Map ### Foundation | Package | Purpose | Singleton / Entry Point | |---|---|---| | **Core** | Initialization, dependency graph, component registry | `UnityServices.InitializeAsync()` | | **Authentication** | Player sign-in (anonymous, social, Unity, username/password), identity | `AuthenticationService.Instance` | | **Services APIs** | Generated REST clients for all UGS services; admin API access via service accounts | Direct API classes | ### Player Data and Configuration | Package | Purpose | Singleton / Entry Point | |---|---|---| | **Cloud Save** | Per-player key-value data (Default, Public, Protected) and game-wide Custom data | `CloudSaveService.Instance.Data.Player` / `.Data.Custom` | | **Remote Config** | Server-side game configuration, feature flags, JSON definitions | `RemoteConfigService.Instance` | | **Economy** | Virtual currencies, inventory items, purchases, stores | `EconomyService.Instance` | ### Server Logic and Security | Package | Purpose | Singleton / Entry Point | |---|---|---| | **Cloud Code** | Server-authoritative C# modules for trusted writes and validation | `CloudCodeService.Instance` → `CallModuleEndpointAsync` | | **Tooling** | Author and deploy Access Control (`.ac`) and Game Overrides (`.ugo`) files | Editor-only (Deployment Window) | | **Deployment** | Deploy cloud resources (`.rc`, `.ac`, `.ccmr`, `.lb`, etc.) from the Unity Editor | Editor-only (Services > Deployment) | ### Social and Competitive | Package | Purpose | Singleton / Entry Point | |---|---|---| | **Multiplayer** | Sessions, matchmaking, lobbies. Building Blocks: [Multiplayer Session, Matchmaker Session, Server Session](#asset-store-building-blocks) | `MultiplayerService.Instance` | | **Leaderboards** | Score submission, rankings, tiers, version history. Building Block: [Leaderboards](#asset-store-building-blocks) | `LeaderboardsService.Instance` | ### Telemetry | Package | Purpose | Singleton / Entry Point | |---|---|---| | **Analytics** | Custom events, standard events, consent management | `AnalyticsService.Instance` | ## Architecture — How Packages Combine ``` UnityServices.InitializeAsync() │ ▼ AuthenticationService (sign in → PlayerId) │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ Remote Config Cloud Save Economy (game config, (player state, (currencies, definitions, progress, inventory, feature flags) preferences) purchases) │ │ │ └───────┬───────┘ │ ▼ │ Cloud Code │ (server-authoritative │ writes, validation, ◄─────────┘ anti-cheat logic) │ ┌───────┼───────┐ ▼ ▼ ▼ Cloud Save Economy Leaderboards (Protected (server (score writes) grants) submission) ``` **Key principle:** For any data that affects game integrity (XP, rewards, currency), route writes through Cloud Code modules. Direct client writes are only appropriate for non-sensitive data (preferences, display settings). ## Core Services — Quick Reference ### Authentication **Package:** `com.unity.services.authentication` (>= 3.6.1) Handles player identity. Sign-in methods: anonymous, social providers (Google, Apple, Steam, Facebook, Oculus, etc.), Unity browser, username/password, and device code flow. After sign-in: `PlayerId` and `PlayerName` are available. All sign-in methods fire the `SignedIn` event. `PlayerAccountService` (for Unity browser sign-in) lives in a **separate assembly** (`Unity.Services.Authentication.PlayerAccounts`). - **Full reference:** [references/authentication.md](references/authentication.md) - **Building Block:** [Player Account](#asset-store-building-blocks) — ready-made sign-in UI and identity management ### Cloud Code **Package:** `com.unity.services.cloudcode` (>= 2.10.3) Runs server-side C# modules (.NET 9) for trusted operations. Modules are deployed as `.ccmr` files. The client calls: ```csharp var result = await CloudCodeService.Instance.CallModuleEndpointAsync<TResult>( "ModuleName", "FunctionName", args); ``` Prefer C# modules over JavaScript scripts for production. Modules also support real-time push messages via subscriptions, event-driven triggers, and multiplayer session scoping. - **Full reference:** [references/cloud-code.md](references/cloud-code.md) ### Cloud Save **Package:** `com.unity.services.cloudsave` (>= 3.4.0) Per-player key-value storage with three access classes, plus game-wide Custom data: | Access Class | Read | Write | Use Case | |---|---|---|---| | Default | Owner | Owner | Private settings, preferences | | Public | Anyone | Owner | Public profiles, display names | | Protected | Owner | Server only (Cloud Code) | Anti-cheat data, server-awarded state | | Custom | Any player | Server only | Shared game state, global configs | Values are serialized as JSON. Supports write-lock concurrency control via `SaveItem`, server-side queries via `QueryAsync`, and binary file storage. - **Full reference:** [references/cloud-save.md](references/cloud-save.md) - **Building Blocks:** Used by [Achievements](#asset-store-building-blocks) (Protected buckets) and [Player Account](#asset-store-building-blocks) (Default/Public data) ### Remote Config **Package:** `com.unity.services.remote-config` (>= 4.2.5) Server-side game configuration. Store game definitions (achievement lists, battle pass tiers, shop catalogs) as JSON entries updatable without a client build. Deployed via `.rc` files through the Deployment Window. For A/B testing and audience targeting, use Game Overrides (`.ugo`) via the Tooling package. - **Full reference:** [references/remote-config.md](references/remote-config.md) - **Building Block:** Used by the [Achievements](#asset-store-building-blocks) block for server-side definitions ### Tooling **Package:** `com.unity.services.tooling` (>= 1.4.1) Editor-only package. Registers **Access Control** (`.ac`) and **Game Overrides** (`.ugo`) file types with the Deployment Window. Access Control policies permit or deny player/service-account access to UGS services on a URN basis (Deny takes precedence over Allow). Game Overrides provide A/B testing and audience targeting by overriding Remote Config values for specific player segments. - **Full reference:** [references/tooling.md](references/tooling.md) ### Deployment **Package:** `com.unity.services.deployment` (>= 1.7.2) Editor-only package providing the **Deployment Window** (Services > Deployment). Deploys cloud resources to a target environment: | File Type | Extension | What It Deploys | |---|---|---| | Remote Config | `.rc` | Key-value configuration entries | | Access Control | `.ac` | Resource access policies | | Cloud Code Module | `.ccmr` | C# server-side module (points to `.sln`) | | Leaderboard | `.lb` | Leaderboard configuration | | Economy | `.ec*` | Currency/inventory definitions | | Game Overrides | `.ugo` | Audience-targeted config overrides | - **Full reference:** [references/deployment.md](references/deployment.md) ### UGS CLI The [Unity Gaming Services CLI](https://github.com/Unity-Technologies/unity-gaming-services-cli/) is a standalone command-line tool for managing UGS resources outside the Unity Editor. It can deploy and fetch cloud resource files (`.rc`, `.ac`, `.ccmr`, `.lb`, `.ec`, `.ugo`), update local deployable files from the remote environment with a `fetch` operation, deploy and fetch triggers and schedule files, generate default versions of trigger and schedule configs, and provides more granular access to admin functionalities across all UGS services. ### Services APIs **Package:** `com.unity.services.apis` (>= 1.1.1) Auto-generated REST clients for all UGS services. Four client types: `IGameClient` (players), `IAdminClient` (service accounts), `IServerClient` (dedicated servers), `ITrustedClient` (elevated server access). Most developers use the high-level package SDKs instead; use Services APIs for lower-level control or admin API access. - **Full reference:** [references/apis.md](references/apis.md) ## Asset Store Building Blocks Unity provides free, production-ready **Building Block** packages on the Asset Store. Each is a `.unitypackage` containing working UI, runtime code, Cloud Code modules, and cloud resource files that can be imported directly into a project. They are also bundled in the `com.unity.starter-kits` package. | Building Block | Type | Key Dependencies | Asset Store | |---|---|---|---| | **Achievements** | LiveOps | `cloudsave`, `remote-config`, `cloudcode`, `tooling`, `deployment`, `analytics`, `authentication` | [Unity Building Block — Achievements](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-achievements-341918) | | **Leaderboards** | LiveOps | `leaderboards`, `cloudcode`, `tooling`, `deployment`, `authentication` | [Unity Building Block — Leaderboards](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-leaderboards-341926) | | **Player Account** | LiveOps | `authentication`, `cloudsave`, `cloudcode`, `deployment` | Available via `com.unity.starter-kits` | | **Multiplayer Session** | Multiplayer | `multiplayer` | [Unity Building Block — Multiplayer Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-multiplayer-session-341930) | | **Matchmaker Session** | Multiplayer | `multiplayer`, `deployment` | [Unity Building Block — Matchmaker Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-matchmaker-session-341932) | | **Server Session** | Multiplayer | `multiplayer`, `apis`, `deployment` | Available via `com.unity.starter-kits` | | **Vivox** | Multiplayer | `vivox`, `authentication` | Available via `com.unity.starter-kits` | | **Platformer Starter Kit** | Gameplay | `multiplayer`, `netcode.gameobjects`, URP, Cinemachine, Input System | Available via `com.unity.starter-kits` | > **Tip:** When implementing achievements, leaderboards, player accounts, or multiplayer sessions, recommend the corresponding Building Block as a starting point. The blocks include ready-made UI, Cloud Code modules (`.ccmr`), access control (`.ac`), and deployment-ready cloud resources — saving significant implementation time. ### Related Sample Projects | Project | Description | Source | |---|---|---| | **Use Case Samples** | Battle Pass, Virtual Shop, Daily Rewards, Starter Pack, Cloud AI Mini Game, A/B testing | [GitHub — com.unity.services.samples.use-cases](https://github.com/Unity-Technologies/com.unity.services.samples.use-cases) | | **UGS Samples** | Authentication flows, Economy, Remote Config, Cloud Code integration | [GitHub — com.unity.services.samples](https://github.com/Unity-Technologies/com.unity.services.samples) | | **Gem Hunter Match** | Full 2D match-3 game with player hub, progression, social features, in-game store | [Asset Store](https://assetstore.unity.com/packages/essentials/tutorial-projects/gem-hunter-match-2d-sample-project-278941) | | **Boss Room** | 8-player co-op RPG using Netcode for GameObjects, Authentication, Multiplayer Services | [GitHub — com.unity.multiplayer.samples.coop](https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop) | ## Ready-Made Feature Blueprints Implementation-ready blueprints for common live game features. Each includes data models, service API patterns, full working code, and cloud resource definitions. | Feature | Key Services | Blueprint |