7# Build a Live Game With Unity Gaming Services
8
9## UGS Packages
10
11| Package | Min Version | Purpose |
12|---|---|---|
13| com.unity.services.core | 1.16.0 | Initialization, dependency graph |
14| com.unity.services.authentication | 3.6.1 | Player sign-in and identity |
15| com.unity.services.cloudcode | 2.10.3 | Server-authoritative C# modules |
16| com.unity.services.cloudsave | 3.4.0 | Per-player and shared key-value storage |
17| com.unity.remote-config | 4.2.5 | Server-side game configuration |
18| com.unity.services.deployment | 1.7.2 | Deploy cloud resources from Editor |
19| com.unity.services.tooling | 1.4.1 | Access Control and Game Overrides |
20| com.unity.services.apis | 1.1.1 | Generated REST clients for all UGS services |
21
22- [Initialization Pattern](#initialization-pattern)
23- [Package Map](#package-map)
24- [Architecture — How Packages Combine](#architecture--how-packages-combine)
25- [Core Services — Quick Reference](#core-services--quick-reference)
26- [Asset Store Building Blocks](#asset-store-building-blocks)
27- [Ready-Made Feature Blueprints](#ready-made-feature-blueprints)
28- [Common Architecture Patterns](#common-architecture-patterns)
29- [Validation](#validation)
30- [Deployment Checklist](#deployment-checklist)
31- [Detailed References](#detailed-references)
32
33## Initialization Pattern
34
35Every UGS game starts the same way. com.unity.services.core must initialize first, then the player signs in:
36
37```csharp
38using Unity.Services.Core;
39using Unity.Services.Authentication;
40
41await UnityServices.InitializeAsync();
42await AuthenticationService.Instance.SignInAnonymouslyAsync();
43// All other services are now ready
44```
45
46After InitializeAsync() completes, service singletons (e.g. CloudSaveService.Instance, CloudCodeService.Instance) are available.
47
48## Package Map
49
50### Foundation
51
52| Package | Purpose | Singleton / Entry Point |
53|---|---|---|
54| **Core** | Initialization, dependency graph, component registry | UnityServices.InitializeAsync() |
55| **Authentication** | Player sign-in (anonymous, social, Unity, username/password), identity | AuthenticationService.Instance |
56| **Services APIs** | Generated REST clients for all UGS services; admin API access via service accounts | Direct API classes |
57
58### Player Data and Configuration
59
60| Package | Purpose | Singleton / Entry Point |
61|---|---|---|
62| **Cloud Save** | Per-player key-value data (Default, Public, Protected) and game-wide Custom data | CloudSaveService.Instance.Data.Player / .Data.Custom |
63| **Remote Config** | Server-side game configuration, feature flags, JSON definitions | RemoteConfigService.Instance |
64| **Economy** | Virtual currencies, inventory items, purchases, stores | EconomyService.Instance |
65
66### Server Logic and Security
67
68| Package | Purpose | Singleton / Entry Point |
69|---|---|---|
70| **Cloud Code** | Server-authoritative C# modules for trusted writes and validation | CloudCodeService.Instance → CallModuleEndpointAsync |
71| **Tooling** | Author and deploy Access Control (.ac) and Game Overrides (.ugo) files | Editor-only (Deployment Window) |
72| **Deployment** | Deploy cloud resources (.rc, .ac, .ccmr, .lb, etc.) from the Unity Editor | Editor-only (Services > Deployment) |
73
74### Social and Competitive
75
76| Package | Purpose | Singleton / Entry Point |
77|---|---|---|
78| **Multiplayer** | Sessions, matchmaking, lobbies. Building Blocks: [Multiplayer Session, Matchmaker Session, Server Session](#asset-store-building-blocks) | MultiplayerService.Instance |
79| **Leaderboards** | Score submission, rankings, tiers, version history. Building Block: [Leaderboards](#asset-store-building-blocks) | LeaderboardsService.Instance |
80
81### Telemetry
82
83| Package | Purpose | Singleton / Entry Point |
84|---|---|---|
85| **Analytics** | Custom events, standard events, consent management | AnalyticsService.Instance |
86
87## Architecture — How Packages Combine
88
89```
90 UnityServices.InitializeAsync()
91 │
92 ▼
93 AuthenticationService
94 (sign in → PlayerId)
95 │
96 ┌───────────────┼───────────────┐
97 ▼ ▼ ▼
98 Remote Config Cloud Save Economy
99 (game config, (player state, (currencies,
100 definitions, progress, inventory,
101 feature flags) preferences) purchases)
102 │ │ │
103 └───────┬───────┘ │
104 ▼ │
105 Cloud Code │
106 (server-authoritative │
107 writes, validation, ◄─────────┘
108 anti-cheat logic)
109 │
110 ┌───────┼───────┐
111 ▼ ▼ ▼
112 Cloud Save Economy Leaderboards
113 (Protected (server (score
114 writes) grants) submission)
115```
116
117**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).
118
119## Core Services — Quick Reference
120
121### Authentication
122
123**Package:** com.unity.services.authentication (>= 3.6.1)
124
125Handles player identity. Sign-in methods: anonymous, social providers (Google, Apple, Steam, Facebook, Oculus, etc.), Unity browser, username/password, and device code flow.
126
127After 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).
128
129- **Full reference:** [references/authentication.md](references/authentication.md)
130- **Building Block:** [Player Account](#asset-store-building-blocks) — ready-made sign-in UI and identity management
131
132### Cloud Code
133
134**Package:** com.unity.services.cloudcode (>= 2.10.3)
135
136Runs server-side C# modules (.NET 9) for trusted operations. Modules are deployed as .ccmr files. The client calls:
137
138```csharp
139var result = await CloudCodeService.Instance.CallModuleEndpointAsync<TResult>(
140 "ModuleName", "FunctionName", args);
141```
142
143Prefer C# modules over JavaScript scripts for production. Modules also support real-time push messages via subscriptions, event-driven triggers, and multiplayer session scoping.
144
145- **Full reference:** [references/cloud-code.md](references/cloud-code.md)
146
147### Cloud Save
148
149**Package:** com.unity.services.cloudsave (>= 3.4.0)
150
151Per-player key-value storage with three access classes, plus game-wide Custom data:
152
153| Access Class | Read | Write | Use Case |
154|---|---|---|---|
155| Default | Owner | Owner | Private settings, preferences |
156| Public | Anyone | Owner | Public profiles, display names |
157| Protected | Owner | Server only (Cloud Code) | Anti-cheat data, server-awarded state |
158| Custom | Any player | Server only | Shared game state, global configs |
159
160Values are serialized as JSON. Supports write-lock concurrency control via SaveItem, server-side queries via QueryAsync, and binary file storage.
161
162- **Full reference:** [references/cloud-save.md](references/cloud-save.md)
163- **Building Blocks:** Used by [Achievements](#asset-store-building-blocks) (Protected buckets) and [Player Account](#asset-store-building-blocks) (Default/Public data)
164
165### Remote Config
166
167**Package:** com.unity.services.remote-config (>= 4.2.5)
168
169Server-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.
170
171For A/B testing and audience targeting, use Game Overrides (.ugo) via the Tooling package.
172
173- **Full reference:** [references/remote-config.md](references/remote-config.md)
174- **Building Block:** Used by the [Achievements](#asset-store-building-blocks) block for server-side definitions
175
176### Tooling
177
178**Package:** com.unity.services.tooling (>= 1.4.1)
179
180Editor-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.
181
182- **Full reference:** [references/tooling.md](references/tooling.md)
183
184### Deployment
185
186**Package:** com.unity.services.deployment (>= 1.7.2)
187
188Editor-only package providing the **Deployment Window** (Services > Deployment). Deploys cloud resources to a target environment:
189
190| File Type | Extension | What It Deploys |
191|---|---|---|
192| Remote Config | .rc | Key-value configuration entries |
193| Access Control | .ac | Resource access policies |
194| Cloud Code Module | .ccmr | C# server-side module (points to .sln) |
195| Leaderboard | .lb | Leaderboard configuration |
196| Economy | .ec* | Currency/inventory definitions |
197| Game Overrides | .ugo | Audience-targeted config overrides |
198
199- **Full reference:** [references/deployment.md](references/deployment.md)
200
201### UGS CLI
202
203The [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.
204
205### Services APIs
206
207**Package:** com.unity.services.apis (>= 1.1.1)
208
209Auto-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.
210
211- **Full reference:** [references/apis.md](references/apis.md)
212
213## Asset Store Building Blocks
214
215Unity 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.
216
217| Building Block | Type | Key Dependencies | Asset Store |
218|---|---|---|---|
219| **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) |
220| **Leaderboards** | LiveOps | leaderboards, cloudcode, tooling, deployment, authentication | [Unity Building Block — Leaderboards](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-leaderboards-341926) |
221| **Player Account** | LiveOps | authentication, cloudsave, cloudcode, deployment | Available via com.unity.starter-kits |
222| **Multiplayer Session** | Multiplayer | multiplayer | [Unity Building Block — Multiplayer Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-multiplayer-session-341930) |
223| **Matchmaker Session** | Multiplayer | multiplayer, deployment | [Unity Building Block — Matchmaker Session](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-matchmaker-session-341932) |
224| **Server Session** | Multiplayer | multiplayer, apis, deployment | Available via com.unity.starter-kits |
225| **Vivox** | Multiplayer | vivox, authentication | Available via com.unity.starter-kits |
226| **Platformer Starter Kit** | Gameplay | multiplayer, netcode.gameobjects, URP, Cinemachine, Input System | Available via com.unity.starter-kits |
227
228> **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.
229
230### Related Sample Projects
231
232| Project | Description | Source |
233|---|---|---|
234| **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) |
235| **UGS Samples** | Authentication flows, Economy, Remote Config, Cloud Code integration | [GitHub — com.unity.services.samples](https://github.com/Unity-Technologies/com.unity.services.samples) |
236| **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) |
237| **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) |
238
239## Ready-Made Feature Blueprints
240
241Implementation-ready blueprints for common live game features. Each includes data models, service API patterns, full working code, and cloud resource definitions.
242
243| Feature | Key Services | Blueprint |
244|---|---|---|
245| **Battle Pass** | remote-config, cloudsave, cloudcode, economy, tooling, deployment — Remote Config (pass definitions) + Cloud Save Protected (progress) + Cloud Code (XP awards, reward claims, premium purchase) | [references/battlepass.md](references/battlepass.md) |
246| **Achievements** | remote-config, cloudsave, cloudcode, tooling, deployment — Remote Config (definitions) + Cloud Save (player records) + Cloud Code (server-authoritative unlocks) + Access Control. **Asset Store:** [Achievements Building Block](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-achievements-341918) | [references/achievements.md](references/achievements.md) |
247| **Player Account** | authentication, cloudsave — Authentication (3 sign-in methods) + Cloud Save (Default/Public/Protected player data). **Asset Store:** Player Account Building Block (via com.unity.starter-kits) | [references/player-account.md](references/player-account.md) |
248
249## Common Architecture Patterns
250
251### Pattern 1: Config + State + Server Writes
252
253Used by **Battle Pass** and **Achievements**:
254
2551. **Definitions** in Remote Config (.rc file) — what exists in the game
2562. **Player state** in Cloud Save — per-player progress
2573. **Writes via Cloud Code** — server-authoritative mutations
2584. **Access Control** (.ac file) — block direct player writes to sensitive keys
259
260### Pattern 2: Client-Direct Data
261
262Used by **Player Account** (preferences, display settings):
263
2641. **Player data** in Cloud Save Default or Public access class
2652. **Direct client writes** — no Cloud Code needed for non-sensitive data
266
267### Pattern 3: Competitive Features
268
269Used by **Leaderboards** and ranked systems:
270
2711. **Score submission** via Leaderboards API (or through Cloud Code for validation)
2722. **Rankings** retrieved client-side with pagination and player-relative queries
273
274## Validation
275
276After writing code for a live game feature:
2771. Verify the project compiles without errors.
2782. Check that initialization order is correct: UnityServices.InitializeAsync() → Authentication sign-in → service calls.
2793. Confirm sensitive data writes (XP, rewards, currency) are routed through Cloud Code, not written directly from the client.
2804. Verify Access Control .ac files deny direct player writes to Protected Cloud Save keys.
2815. Verify all cloud resource files (.rc, .ac, .ccmr, .lb, .ec) are present and deployable via the Deployment Window.
282
283## Deployment Checklist
284
285For any live game feature, deploy these cloud resources via the Deployment Window:
286
287- [ ] .rc file — Remote Config entries (game definitions, configs)
288- [ ] .ac file — Access Control policies (deny direct writes to protected keys)
289- [ ] .ccmr file — Cloud Code module reference (pointing to the module .sln)
290- [ ] .lb file — Leaderboard configuration (if using leaderboards)
291- [ ] .ec file — Economy definitions (if using virtual currencies/items)
292- [ ] manifest.json — Ensure all required packages are listed with correct versions
293- [ ] Environment configured in **Services > Deployment** settings
294
295## Detailed References
296
297### Service References
298- **Authentication** — sign-in methods, events, profiles, identity providers, code templates: [references/authentication.md](references/authentication.md)
299- **Cloud Code** — scripts, modules, subscriptions, triggers, module creation, code templates: [references/cloud-code.md](references/cloud-code.md)
300- **Cloud Save** — access classes, data operations, files, queries, code templates: [references/cloud-save.md](references/cloud-save.md)
301- **Remote Config** — definitions, .rc format, Game Overrides, code templates: [references/remote-config.md](references/remote-config.md)
302- **Tooling** — Access Control (.ac) policies, Game Overrides (.ugo), URN reference: [references/tooling.md](references/tooling.md)
303- **Deployment** — file types, workflow, programmatic API: [references/deployment.md](references/deployment.md)
304- **Services APIs** — four client types, service areas, code templates: [references/apis.md](references/apis.md)
305
306### Feature Blueprints
307- **Achievements** — full implementation with data models, client code, Cloud Code module, cloud resources: [references/achievements.md](references/achievements.md)
308- **Battle Pass** — full implementation with tiered XP, free/premium tracks, Cloud Code module, cloud resources: [references/battlepass.md](references/battlepass.md)
309- **Player Account** — sign-in flows, identity management, Cloud Save data, code templates: [references/player-account.md](references/player-account.md)
310
311## Reminders
312
313Before completing, verify:
314- Did you use UnityServices.InitializeAsync() → Authentication sign-in → service calls (in that order)?
315- Are all sensitive writes (XP, rewards, currency) routed through Cloud Code modules?
316- Are all cloud resource files (.rc, .ac, .ccmr) present and deployable?
317- Do Cloud Save read access classes match the bucket that was written to?
318