nccgs 1.0.0

package/.claude/skills/build-live-game/references/cloud-save.md

@@ -0,0 +1,474 @@
+# Cloud Save Reference
+
+## Table of Contents
+
+- [Anti-Hallucination Reference](#anti-hallucination-reference)
+- [Subsystems](#subsystems)
+- [IPlayerDataService Methods](#iplayerdataservice-methods)
+- [ICustomDataService Methods](#icustomdataservice-methods)
+- [IPlayerFilesService Methods](#iplayerfilesservice-methods)
+- [Key Model Types](#key-model-types)
+- [Access Classes](#access-classes)
+- [Code Templates](#code-templates)
+- [Error Handling](#error-handling)
+
+Accessed via `CloudSaveService.Instance` (`ICloudSaveService`, namespace `Unity.Services.CloudSave`). Assembly: `Unity.Services.CloudSave`.
+
+Call `UnityServices.InitializeAsync()` from `com.unity.services.core` and sign in via `com.unity.services.authentication` before use.
+
+---
+
+## Anti-Hallucination Reference
+
+| Correct | Incorrect (do NOT use) |
+|---|---|
+| `SaveAsync` returns `Task<Dictionary<string, string>>` (write lock tokens) | `SaveAsync` returns `Task` (void) |
+| `Item.Value` is `IDeserializable` -- call `.GetAs<T>()` | `Item.Value` is `object` |
+| `SaveAsync(IDictionary<string, object>)` -- uses `IDictionary` | `SaveAsync(Dictionary<string, object>)` -- wrong interface type |
+| `SaveAsync(IDictionary<string, SaveItem>)` -- bundles value + write lock | `SaveAsync(data, Dictionary<string, WriteLockOptions>)` -- no such overload |
+| Custom data is **read-only** from client (no save/delete methods) | Custom data can be written from client |
+| `CloudSaveConflictException` has `Details` list | Only `CloudSaveException` exists for conflicts |
+| `CloudSaveExceptionReason.Conflict` (value 11) | `WriteLockConflict` reason |
+| `Item.Modified` / `Item.Created` are `DateTime?` | `Item.Modified` is `ModifiedMetadata` |
+| `FileItem.Modified` / `FileItem.Created` are `DateTime?` | `FileItem.Modified` is `ModifiedMetadata` |
+| `DeleteAsync(key, Models.Data.Player.DeleteOptions)` -- current API | `DeleteAsync(key, CloudSave.DeleteOptions)` -- deprecated overload |
+| `ICustomDataService` methods require `customDataID` first param | Custom data methods with no ID param |
+
+---
+
+## Subsystems
+
+| Subsystem | Access | Description |
+|---|---|---|
+| `Data.Player` | `CloudSaveService.Instance.Data.Player` | Key-value data for the signed-in player |
+| `Data.Custom` | `CloudSaveService.Instance.Data.Custom` | Game-wide or server-written data; **read-only from client** |
+| `Files.Player` | `CloudSaveService.Instance.Files.Player` | Binary file storage per player |
+
+---
+
+## IPlayerDataService Methods
+
+`CloudSaveService.Instance.Data.Player`
+
+**Options namespace:** All option classes (`SaveOptions`, `LoadOptions`, `DeleteOptions`, `DeleteAllOptions`, `ListAllKeysOptions`, `LoadAllOptions`, `QueryOptions`) are in `Unity.Services.CloudSave.Models.Data.Player`. Do **not** confuse with the deprecated root-level `CloudSave.SaveOptions` / `CloudSave.DeleteOptions`.
+
+```csharp
+// List all keys belonging to the current player (with metadata).
+Task<List<ItemKey>> ListAllKeysAsync()
+Task<List<ItemKey>> ListAllKeysAsync(ListAllKeysOptions options)
+
+// Load specific keys. Returns dictionary of key -> Item.
+Task<Dictionary<string, Item>> LoadAsync(ISet<string> keys)
+Task<Dictionary<string, Item>> LoadAsync(ISet<string> keys, LoadOptions options)
+
+// Load all keys for the current player.
+Task<Dictionary<string, Item>> LoadAllAsync()
+Task<Dictionary<string, Item>> LoadAllAsync(LoadAllOptions options)
+
+// Save key-value pairs. Returns Dictionary<string, string> mapping each key to its new write-lock token.
+Task<Dictionary<string, string>> SaveAsync(IDictionary<string, object> data)
+Task<Dictionary<string, string>> SaveAsync(IDictionary<string, object> data, SaveOptions options)
+
+// Save with per-key write locks bundled via SaveItem.
+Task<Dictionary<string, string>> SaveAsync(IDictionary<string, SaveItem> data)
+Task<Dictionary<string, string>> SaveAsync(IDictionary<string, SaveItem> data, SaveOptions options)
+
+// Delete a specific key. Use Models.Data.Player.DeleteOptions (not the deprecated root DeleteOptions).
+Task DeleteAsync(string key, Models.Data.Player.DeleteOptions options)
+
+// Delete ALL keys for the current player.
+Task DeleteAllAsync()
+Task DeleteAllAsync(DeleteAllOptions options)
+
+// Query player data with field filters.
+Task<List<EntityData>> QueryAsync(Query query, QueryOptions options)
+```
+
+---
+
+## ICustomDataService Methods
+
+`CloudSaveService.Instance.Data.Custom`
+
+Read-only from the client. Write via Cloud Code modules or `IAdminClient.CloudSaveData` from the `com.unity.services.apis` package. All methods require a `customDataID` parameter -- the namespace configured in the Unity Dashboard.
+
+> **To write Custom Data from the editor or a deploy command**, use `IAdminClient.CloudSaveData.SetCustomItem` /
+> `SetCustomItemBatch`. See [apis.md](apis.md) for setup and code templates. The client SDK has no write
+> path for Custom Data.
+
+```csharp
+Task<List<ItemKey>> ListAllKeysAsync(string customDataID)
+Task<Dictionary<string, Item>> LoadAllAsync(string customDataID)
+Task<Dictionary<string, Item>> LoadAsync(string customDataID, ISet<string> keys)
+
+// Query across custom data. Uses Models.Data.Custom.QueryOptions.
+Task<List<EntityData>> QueryAsync(Query query, Models.Data.Custom.QueryOptions options = default)
+```
+
+---
+
+## IPlayerFilesService Methods
+
+`CloudSaveService.Instance.Files.Player`
+
+Note: File methods use root-level `CloudSave.SaveOptions` and `CloudSave.DeleteOptions` (not the `Models.Data.Player` versions).
+
+```csharp
+// List all files for the current player.
+Task<List<FileItem>> ListAllAsync()
+
+// Save a file (byte array or stream).
+Task SaveAsync(string key, byte[] bytes, SaveOptions options = default)
+Task SaveAsync(string key, Stream stream, SaveOptions options = default)
+
+// Load a file as a byte array.
+Task<byte[]> LoadBytesAsync(string key)
+
+// Load a file as a stream.
+Task<Stream> LoadStreamAsync(string key)
+
+// Delete a file.
+Task DeleteAsync(string key, DeleteOptions options = default)
+
+// Get metadata for a specific file.
+Task<FileItem> GetMetadataAsync(string key)
+```
+
+---
+
+## Key Model Types
+
+### `Item` (`Unity.Services.CloudSave.Models`)
+
+| Property | Type | Description |
+|---|---|---|
+| `Key` | `string` | The data key |
+| `Value` | `IDeserializable` | Deserialized value -- call `.GetAs<T>()` or `.GetAsString()` |
+| `WriteLock` | `string` | Current write-lock token (use for optimistic concurrency) |
+| `Created` | `DateTime?` | Creation timestamp |
+| `Modified` | `DateTime?` | Last-modified timestamp |
+
+### `ItemKey` (`Unity.Services.CloudSave.Models`)
+
+| Property | Type | Description |
+|---|---|---|
+| `Key` | `string` | The data key |
+| `WriteLock` | `string` | Current write-lock token |
+| `Modified` | `DateTime?` | Last-modified timestamp |
+
+### `FileItem` (`Unity.Services.CloudSave.Models`)
+
+| Property | Type | Description |
+|---|---|---|
+| `Key` | `string` | The file key |
+| `Size` | `long` | File size in bytes |
+| `WriteLock` | `string` | Current write-lock token |
+| `ContentType` | `string` | MIME type of the file |
+| `Created` | `DateTime?` | Creation timestamp |
+| `Modified` | `DateTime?` | Last-modified timestamp |
+
+### `SaveItem` (`Unity.Services.CloudSave.Models`)
+
+Bundles a value and write lock for atomic save-with-lock operations.
+
+```csharp
+new SaveItem(value: myObject, writeLock: previousItem.WriteLock)
+```
+
+### `Query` (`Unity.Services.CloudSave.Models`)
+
+| Property | Type | Description |
+|---|---|---|
+| `Fields` | `List<FieldFilter>` | Filter conditions (required) |
+| `ReturnKeys` | `HashSet<string>` | Project only these keys in results |
+| `Offset` | `int` | Skip N results (pagination) |
+| `Limit` | `int` | Max results to return |
+| `SampleSize` | `int?` | Random sample size (optional) |
+
+### `FieldFilter` (`Unity.Services.CloudSave.Models`)
+
+```csharp
+new FieldFilter(key: "level", value: 10, op: FieldFilter.OpOptions.GE, asc: true)
+```
+
+| `OpOptions` | Meaning |
+|---|---|
+| `EQ` | Equal |
+| `NE` | Not equal |
+| `LT` | Less than |
+| `LE` | Less than or equal |
+| `GT` | Greater than |
+| `GE` | Greater than or equal |
+
+### `EntityData` (`Unity.Services.CloudSave.Models`)
+
+Query results return `List<EntityData>`, where each entry is one player's matching data.
+
+| Property | Type | Description |
+|---|---|---|
+| `Id` | `string` | Player ID |
+| `Data` | `List<Item>` | Matching items for this player |
+
+---
+
+## Access Classes
+
+Namespace: `Unity.Services.CloudSave.Models.Data.Player`.
+
+### `AccessClass` Enum
+
+| Value | Meaning |
+|---|---|
+| `Default` (0) | Owner read/write -- private to the player |
+| `Private` (1) | Alias for Default |
+| `Protected` (2) | Owner read, server-only write |
+| `Public` (3) | Any player can read, owner writes |
+
+### Read Access Class Options (for Load/ListAllKeys)
+
+- `DefaultReadAccessClassOptions()` -- read own Default-class data
+- `PublicReadAccessClassOptions()` -- read own Public-class data
+- `PublicReadAccessClassOptions(string playerId)` -- read **another player's** Public-class data
+- `ProtectedReadAccessClassOptions()` -- read own Protected-class data
+
+### Write Access Class Options (for Save/Delete)
+
+- `DefaultWriteAccessClassOptions()` -- write to Default-class keys
+- `PublicWriteAccessClassOptions()` -- write to Public-class keys
+
+---
+
+## Code Templates
+
+### Save Player Data (Capture Write Lock Tokens)
+
+```csharp
+using Unity.Services.CloudSave;
+using Unity.Services.CloudSave.Models;
+using System.Collections.Generic;
+
+var data = new Dictionary<string, object>
+{
+    { "level", 10 },
+    { "gold", 500 },
+    { "inventory", new string[] { "sword", "shield" } }
+};
+
+// SaveAsync returns write-lock tokens for each saved key
+Dictionary<string, string> writeLocks = await CloudSaveService.Instance.Data.Player.SaveAsync(data);
+// writeLocks["level"] == "new-lock-token-for-level", etc.
+```
+
+### Load Specific Keys
+
+```csharp
+var keys = new HashSet<string> { "level", "gold" };
+var result = await CloudSaveService.Instance.Data.Player.LoadAsync(keys);
+
+if (result.TryGetValue("level", out var levelItem))
+{
+    int level = levelItem.Value.GetAs<int>();
+    Debug.Log($"Level: {level}, Modified: {levelItem.Modified}");
+}
+```
+
+### Save with Write Lock Using SaveItem
+
+```csharp
+using Unity.Services.CloudSave.Models;
+
+// First load to get the current write lock
+var items = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string> { "gold" });
+var goldItem = items["gold"];
+
+// Bundle value + write lock in SaveItem -- fails if another client updated in the meantime
+var saveData = new Dictionary<string, SaveItem>
+{
+    { "gold", new SaveItem(value: 600, writeLock: goldItem.WriteLock) }
+};
+
+Dictionary<string, string> newLocks = await CloudSaveService.Instance.Data.Player.SaveAsync(saveData);
+// newLocks["gold"] is the updated write-lock token
+```
+
+### Handle Write-Lock Conflicts
+
+```csharp
+using Unity.Services.CloudSave;
+
+try
+{
+    await CloudSaveService.Instance.Data.Player.SaveAsync(saveData);
+}
+catch (CloudSaveConflictException ex)
+{
+    foreach (var detail in ex.Details)
+    {
+        Debug.LogError($"Conflict on '{detail.Key}': " +
+            $"you sent lock '{detail.AttemptedWriteLock}', " +
+            $"server has '{detail.ExistingWriteLock}'");
+    }
+    // Reload, merge, and retry
+}
+```
+
+### Delete a Key
+
+```csharp
+using Unity.Services.CloudSave.Models.Data.Player;
+
+// Delete with write-lock check
+var options = new DeleteOptions { WriteLock = knownWriteLock };
+await CloudSaveService.Instance.Data.Player.DeleteAsync("gold", options);
+
+// Delete ALL player data
+await CloudSaveService.Instance.Data.Player.DeleteAllAsync();
+```
+
+### Save and Load with Access Classes (Public, Default, Protected)
+
+> **Namespace note:** `SaveOptions`, `LoadOptions`, and `DeleteOptions` exist in both
+> `Unity.Services.CloudSave` (root) and `Unity.Services.CloudSave.Models.Data.Player`.
+> The access-class overloads live in `Models.Data.Player`. If you import both namespaces,
+> use fully qualified names or a `using` alias to avoid ambiguity.
+
+```csharp
+using Unity.Services.CloudSave.Models.Data.Player;
+
+// Save data as Public (other players can read it)
+var publicData = new Dictionary<string, object> { { "displayName", "Hero123" }, { "rank", 42 } };
+var publicOptions = new SaveOptions(new PublicWriteAccessClassOptions());
+await CloudSaveService.Instance.Data.Player.SaveAsync(publicData, publicOptions);
+
+// Read another player's Public-class data
+var readOptions = new LoadOptions(new PublicReadAccessClassOptions(otherPlayerId));
+var otherPlayerData = await CloudSaveService.Instance.Data.Player.LoadAsync(
+    new HashSet<string> { "displayName", "rank" }, readOptions);
+Debug.Log($"Other player name: {otherPlayerData["displayName"].Value.GetAs<string>()}");
+
+// Read own Protected-class data (written by server/Cloud Code)
+var protectedOptions = new LoadOptions(new ProtectedReadAccessClassOptions());
+var serverData = await CloudSaveService.Instance.Data.Player.LoadAllAsync(
+    new LoadAllOptions(new ProtectedReadAccessClassOptions()));
+```
+
+### Read Custom Data (Game-Wide, Read-Only)
+
+```csharp
+// Custom data is read-only from client -- written via Cloud Code or admin API.
+// customDataID is the namespace configured in the Unity Dashboard.
+var customData = await CloudSaveService.Instance.Data.Custom.LoadAllAsync("my-game-config");
+
+if (customData.TryGetValue("seasonConfig", out var config))
+{
+    var season = config.Value.GetAs<SeasonConfig>();
+    Debug.Log($"Current season: {season.Name}");
+}
+```
+
+### Query Player Data
+
+```csharp
+using Unity.Services.CloudSave.Models;
+using Unity.Services.CloudSave.Models.Data.Player;
+
+// Find players with level >= 10, sorted ascending
+var query = new Query(
+    fields: new List<FieldFilter>
+    {
+        new FieldFilter(key: "level", value: 10, op: FieldFilter.OpOptions.GE, asc: true)
+    },
+    returnKeys: new HashSet<string> { "level", "displayName" },
+    offset: 0,
+    limit: 20
+);
+
+var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new QueryOptions());
+
+foreach (var entity in results)
+{
+    Debug.Log($"Player {entity.Id}:");
+    foreach (var item in entity.Data)
+        Debug.Log($"  {item.Key} = {item.Value.GetAsString()}");
+}
+```
+
+### Save and Load a File
+
+```csharp
+// Save
+byte[] screenshotBytes = await CaptureScreenshot();
+await CloudSaveService.Instance.Files.Player.SaveAsync("screenshot_latest", screenshotBytes);
+
+// Load
+byte[] loaded = await CloudSaveService.Instance.Files.Player.LoadBytesAsync("screenshot_latest");
+
+// Get metadata
+var meta = await CloudSaveService.Instance.Files.Player.GetMetadataAsync("screenshot_latest");
+Debug.Log($"Size: {meta.Size}, ContentType: {meta.ContentType}, Modified: {meta.Modified}");
+```
+
+### List All Keys
+
+```csharp
+var keys = await CloudSaveService.Instance.Data.Player.ListAllKeysAsync();
+foreach (var key in keys)
+{
+    Debug.Log($"Key: {key.Key}, WriteLock: {key.WriteLock}, Modified: {key.Modified}");
+}
+```
+
+---
+
+## Error Handling
+
+```csharp
+try { ... }
+catch (CloudSaveConflictException ex)
+{
+    // Write-lock conflict -- inspect per-key details
+    foreach (var detail in ex.Details)
+        Debug.LogError($"Key '{detail.Key}': attempted={detail.AttemptedWriteLock}, existing={detail.ExistingWriteLock}");
+}
+catch (CloudSaveValidationException ex)
+{
+    // Input validation failure -- inspect per-field details
+    foreach (var detail in ex.Details)
+        Debug.LogError($"Field '{detail.Field}' key '{detail.Key}': {string.Join(", ", detail.Messages)}");
+}
+catch (CloudSaveRateLimitedException ex)
+{
+    Debug.LogError($"Rate limited. Retry after {ex.RetryAfter}s");
+}
+catch (CloudSaveException ex)
+{
+    Debug.LogError($"Cloud Save error: {ex.Message} (reason: {ex.Reason})");
+}
+```
+
+### `CloudSaveExceptionReason` Enum
+
+| Reason | Value | Meaning |
+|---|---|---|
+| `Unknown` | 0 | Unknown error |
+| `NoInternetConnection` | 1 | No network |
+| `ProjectIdMissing` | 2 | Project ID not set |
+| `PlayerIdMissing` | 3 | Player not signed in |
+| `AccessTokenMissing` | 4 | No access token |
+| `InvalidArgument` | 5 | Bad input |
+| `Unauthorized` | 6 | Not authorized |
+| `KeyLimitExceeded` | 7 | Too many keys stored |
+| `NotFound` | 8 | Key not found |
+| `TooManyRequests` | 9 | Rate limited |
+| `ServiceUnavailable` | 10 | Service down |
+| `Conflict` | 11 | Write-lock conflict |
+
+---
+
+## Asset Store Building Blocks
+
+The following Building Blocks from the Unity Asset Store demonstrate Cloud Save patterns:
+
+- **Achievements Building Block** — Reads/writes achievement records in Protected buckets via Cloud Code, with Access Control denying direct player writes. [Asset Store](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-achievements-341918)
+- **Player Account Building Block** — Stores player profile data in Default and Public access classes with direct client writes for non-sensitive data. [Asset Store](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-player-account-341928)
+- **Leaderboards Building Block** — Uses Cloud Save for player score data alongside Cloud Code modules. [Asset Store](https://assetstore.unity.com/packages/essentials/tutorial-projects/unity-building-block-leaderboards-341926)

package/.claude/skills/build-live-game/references/deployment.md

@@ -0,0 +1,216 @@
+# Deployment Reference
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Supported Service Integrations](#supported-service-integrations)
+- [Workflow](#workflow)
+- [Deployment Definitions (.ddef)](#deployment-definitions-ddef)
+  - [JSON Schema](#json-schema)
+  - [Behavior](#behavior)
+- [Programmatic API](#programmatic-api)
+  - [Entry Point: Deployments.Instance](#entry-point-deploymentsinstance)
+  - [IDeploymentWindow](#ideploymentwindow)
+  - [DeploymentResult and DeploymentStatus](#deploymentresult-and-deploymentstatus)
+  - [SeverityLevel](#severitylevel)
+  - [DeploymentProvider (Abstract)](#deploymentprovider-abstract)
+  - [IDeploymentItem](#ideploymentitem)
+  - [Code Template -- Register a Custom Provider](#code-template--register-a-custom-provider)
+  - [Code Template -- Trigger Deployment Programmatically](#code-template--trigger-deployment-programmatically)
+
+## Overview
+
+Editor-only package providing the **Deployment Window** (Services > Deployment). Deploys cloud resources for multiple UGS services from one place, without leaving the Unity Editor.
+
+- **Package:** `com.unity.services.deployment`
+- This package is Editor-only. Runtime code does not reference it.
+
+## Supported Service Integrations
+
+Each service package registers its own file types with the Deployment Window. Install the relevant service package to enable its file types.
+
+| Service | Package | File Type(s) | Min Version |
+|---|---|---|---|
+| Cloud Code Scripts | `com.unity.services.cloudcode` | `.js` | 2.1.0 |
+| Cloud Code C# Modules | `com.unity.services.cloudcode` | `.ccmr` | 2.5.0 |
+| Remote Config | `com.unity.remote-config` | `.rc` | 3.2.0 |
+| Economy | `com.unity.services.economy` | `.ecc`, `.eci`, `.ecv`, `.ecr` | 3.2.1 |
+| Leaderboards | `com.unity.services.leaderboards` | `.lb` | 2.0.0 |
+| Game Server Hosting | `com.unity.services.multiplayer` | `.gsh` | 1.1.0 |
+| Matchmaker | `com.unity.services.multiplayer` | `.mmq` | 1.0 |
+| Game Overrides | `com.unity.services.tooling` | `.ugo` | 1.3.0 |
+| Access Control | `com.unity.services.tooling` | `.ac` | 1.0 |
+| Deployment Definitions | `com.unity.services.deployment` | `.ddef` | -- |
+
+## Workflow
+
+1. Add `com.unity.services.deployment` via Package Manager.
+2. Open **Services > Deployment**.
+3. Select the target environment in the dropdown.
+4. Choose files to deploy (or select all).
+5. Click **Deploy**.
+
+## Deployment Definitions (.ddef)
+
+A Deployment Definition scopes the Deployment Window to a subset of files. Useful for large projects with multiple environments or teams.
+
+**File extension:** `.ddef`
+
+**Create via:** Right-click in Project window > Create > Unity Gaming Services > Deployment Definition
+
+### JSON Schema
+
+```json
+{
+  "name": "GameplayServices",
+  "excludePaths": [
+    "Assets/CloudCode/Experimental/**",
+    "Assets/Config/Archive/**"
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Display name shown in the Deployment Window |
+| `excludePaths` | `string[]` | Glob patterns for files/folders to skip |
+
+### Behavior
+
+- **Without a `.ddef`:** the Deployment Window discovers and deploys all UGS config files under `Assets/`.
+- **With a `.ddef` selected:** only files within the definition's scope (minus excluded paths) are shown and deployed.
+- Multiple `.ddef` files can exist in one project; select which one to use in the Deployment Window dropdown.
+
+## Programmatic API
+
+The separate **`com.unity.services.deployment.api`** package (v1.1) provides programmatic access to the Deployment Window. All types in the main `com.unity.services.deployment` package are `internal` -- there is no public C# API from the main package.
+
+- **Namespace:** `Unity.Services.DeploymentApi.Editor`
+
+### Entry Point: Deployments.Instance
+
+| Member | Type | Description |
+|---|---|---|
+| `Instance` | `Deployments` | Static singleton |
+| `DeploymentProviders` | `ObservableCollection<DeploymentProvider>` | All registered service providers |
+| `DeploymentWindow` | `IDeploymentWindow` | Programmatic window control |
+| `EnvironmentProvider` | `IEnvironmentProvider` | Current environment |
+| `ProjectIdProvider` | `IProjectIdentifierProvider` | Current project ID |
+
+### IDeploymentWindow
+
+| Member | Description |
+|---|---|
+| `Deploy(items, token)` | Returns `Task<DeploymentResult<IDeploymentItem>>` -- deploy selected items |
+| `Deploy(filePaths, token)` | Extension: deploy items by file path (same return type) |
+| `GetAllDeploymentItems(includeDeploymentDefinitions)` | Extension: get all items across all providers |
+| `GetFromFiles(filePaths)` | Get items matching given file paths |
+| `GetDeploymentDefinitions()` | Get available `.ddef` items |
+| `OpenWindow()` | Opens the Deployment Window (`EditorWindow`) |
+| `GetChecked()` / `GetSelected()` | Get checked/selected items (window must be open) |
+| `Check(items)` / `ClearChecked()` | Programmatically check items |
+| `Select(items)` / `ClearSelection()` | Programmatically select items |
+| `DeploymentStarting` | `event Action<IReadOnlyList<IDeploymentItem>>` -- before deployment |
+| `DeploymentEnded` | `event Action<IReadOnlyList<IDeploymentItem>>` -- after deployment |
+| `GetCurrentDeployment()` | Returns the active `DeploymentScope`, or null |
+
+### DeploymentResult and DeploymentStatus
+
+**DeploymentResult\<T\>**
+
+| Member | Type | Description |
+|---|---|---|
+| `Deployed` | `List<T>` | Items that were successfully deployed |
+
+**DeploymentStatus** has static factory methods for common states:
+
+| Factory | Description |
+|---|---|
+| `Empty` / `UpToDate` / `ModifiedLocally` / `FailedToDeploy` | Static readonly instances |
+| `GetDeployed(details)` / `GetDeploying(details)` | Deployment in-progress/complete |
+| `GetFailedToDeploy(details)` / `GetFailedToFetch(details)` | Failure states |
+| `GetFailedToLoad(e, path)` / `GetFailedToRead(e, path)` | File I/O failures |
+| `GetFetched(details)` / `GetFetching(details)` | Fetch from remote states |
+| `GetPartialDeploy(details)` / `GetPartialFetch(details)` | Partial completion |
+
+### SeverityLevel
+
+| Value | Meaning |
+|---|---|
+| `None` (0) | No status |
+| `Info` (1) | Informational |
+| `Warning` (2) | Warning |
+| `Error` (3) | Error |
+| `Success` (4) | Success |
+
+### DeploymentProvider (Abstract)
+
+Subclass this to expose your own deployable assets to the Deployment Window.
+
+| Member | Description |
+|---|---|
+| `Service` | Display name for the service (abstract) |
+| `DeployCommand` | Required deploy command (abstract) |
+| `DeploymentItems` | `ObservableCollection<IDeploymentItem>` -- add/remove to populate the window |
+| `Commands` | Additional context menu commands |
+| `OpenCommand` | Double-click handler (optional) |
+| `ValidateCommand` | Validation command (optional) |
+| `SyncItemsWithRemoteCommand` | Sync-with-remote command (optional) |
+
+### IDeploymentItem
+
+| Member | Description |
+|---|---|
+| `Name` | File name with extension |
+| `Path` | Full asset path |
+| `Progress` | Deploy progress 0-100 |
+| `Status` | `DeploymentStatus` (message + severity) |
+| `States` | `ObservableCollection<AssetState>` -- local asset validation states |
+
+### Code Template -- Register a Custom Provider
+
+```csharp
+using UnityEditor;
+using Unity.Services.DeploymentApi.Editor;
+
+class MyServiceDeploymentProvider : DeploymentProvider
+{
+    public override string Service => "MyService";
+    public override Command DeployCommand { get; } = new MyDeployCommand();
+}
+
+[InitializeOnLoadMethod]
+static void RegisterProvider()
+{
+    Deployments.Instance.DeploymentProviders.Add(new MyServiceDeploymentProvider());
+}
+```
+
+> **Deploy commands that write to UGS services** must use `IAdminClient` from the
+> `com.unity.services.apis` package (`com.unity.services.apis`). Authenticate with a service
+> account via `adminClient.SetServiceAccount(keyId, keySecret)`, then call the appropriate
+> admin API (e.g. `adminClient.CloudSaveData.SetCustomItem` for Cloud Save game data).
+> See [apis.md](apis.md) for the full `IAdminClient` interface and code templates.
+
+### Code Template -- Trigger Deployment Programmatically
+
+```csharp
+using Unity.Services.DeploymentApi.Editor;
+
+// Deploy all items
+var allItems = Deployments.Instance.DeploymentWindow.GetAllDeploymentItems();
+var result = await Deployments.Instance.DeploymentWindow.Deploy(allItems);
+
+// Deploy by file paths
+await Deployments.Instance.DeploymentWindow.Deploy(new[] { "Assets/MyConfig.rc" });
+
+// Listen for deployment events
+Deployments.Instance.DeploymentWindow.DeploymentStarting += items =>
+{
+    Debug.Log($"Deploying {items.Count} items...");
+};
+Deployments.Instance.DeploymentWindow.DeploymentEnded += items =>
+{
+    Debug.Log($"Deployment complete: {items.Count} items");
+};
+```