build-live-game

Build a Live Game With Unity Gaming Services

UGS Packages

• Initialization Pattern
• Package Map
• Architecture — How Packages Combine
• Core Services — Quick Reference
• Asset Store Building Blocks
• Ready-Made Feature Blueprints
• Common Architecture Patterns
• Validation
• Deployment Checklist
• Detailed References

Initialization Pattern

Every UGS game starts the same way. com.unity.services.core must initialize first, then the player signs in:

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

After InitializeAsync() completes, service singletons (e.g. CloudSaveService.Instance, CloudCodeService.Instance) are available.

Package Map

Foundation

Player Data and Configuration

Server Logic and Security

Social and Competitive

Telemetry

Architecture — How Packages Combine

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
• Building Block: Player Account — 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:

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

Cloud Save

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

Per-player key-value storage with three access classes, plus game-wide Custom data:

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
• Building Blocks: Used by Achievements (Protected buckets) and Player Account (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
• Building Block: Used by the Achievements 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

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:

• Full reference: references/deployment.md

UGS CLI

The 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

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.

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

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.

Common Architecture Patterns

Pattern 1: Config + State + Server Writes

Used by Battle Pass and Achievements:

1. Definitions in Remote Config (.rc file) — what exists in the game
2. Player state in Cloud Save — per-player progress
3. Writes via Cloud Code — server-authoritative mutations
4. Access Control (.ac file) — block direct player writes to sensitive keys

Pattern 2: Client-Direct Data

Used by Player Account (preferences, display settings):

1. Player data in Cloud Save Default or Public access class
2. Direct client writes — no Cloud Code needed for non-sensitive data

Pattern 3: Competitive Features

Used by Leaderboards and ranked systems:

1. Score submission via Leaderboards API (or through Cloud Code for validation)
2. Rankings retrieved client-side with pagination and player-relative queries

Validation

After writing code for a live game feature:

1. Verify the project compiles without errors.
2. Check that initialization order is correct: UnityServices.InitializeAsync() → Authentication sign-in → service calls.
3. Confirm sensitive data writes (XP, rewards, currency) are routed through Cloud Code, not written directly from the client.
4. Verify Access Control .ac files deny direct player writes to Protected Cloud Save keys.
5. Verify all cloud resource files (.rc, .ac, .ccmr, .lb, .ec) are present and deployable via the Deployment Window.

Deployment Checklist

For any live game feature, deploy these cloud resources via the Deployment Window:

• .rc file — Remote Config entries (game definitions, configs)
• .ac file — Access Control policies (deny direct writes to protected keys)
• .ccmr file — Cloud Code module reference (pointing to the module .sln)
• .lb file — Leaderboard configuration (if using leaderboards)
• .ec file — Economy definitions (if using virtual currencies/items)
• manifest.json — Ensure all required packages are listed with correct versions
• Environment configured in Services > Deployment settings

Detailed References

Service References

• Authentication — sign-in methods, events, profiles, identity providers, code templates: references/authentication.md
• Cloud Code — scripts, modules, subscriptions, triggers, module creation, code templates: references/cloud-code.md
• Cloud Save — access classes, data operations, files, queries, code templates: references/cloud-save.md
• Remote Config — definitions, .rc format, Game Overrides, code templates: references/remote-config.md
• Tooling — Access Control (.ac) policies, Game Overrides (.ugo), URN reference: references/tooling.md
• Deployment — file types, workflow, programmatic API: references/deployment.md
• Services APIs — four client types, service areas, code templates: references/apis.md

Feature Blueprints

• Achievements — full implementation with data models, client code, Cloud Code module, cloud resources: references/achievements.md
• Battle Pass — full implementation with tiered XP, free/premium tracks, Cloud Code module, cloud resources: references/battlepass.md
• Player Account — sign-in flows, identity management, Cloud Save data, code templates: references/player-account.md

Reminders

Before completing, verify:

• Did you use UnityServices.InitializeAsync() → Authentication sign-in → service calls (in that order)?
• Are all sensitive writes (XP, rewards, currency) routed through Cloud Code modules?
• Are all cloud resource files (.rc, .ac, .ccmr) present and deployable?
• Do Cloud Save read access classes match the bucket that was written to?