@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/build-live-game/references/cloud-code.md

@@ -0,0 +1,58 @@
+# Cloud Code Reference
+
+## Table of Contents
+
+- [Four Execution Models](#four-execution-models)
+  - [Cloud Code Modules vs CloudBehaviours](#cloud-code-modules-vs-cloudbehaviours)
+- [Where the details live](#where-the-details-live)
+
+Accessed via `CloudCodeService.Instance` (`ICloudCodeService`, namespace `Unity.Services.CloudCode`). Assembly: `Unity.Services.CloudCode`.
+
+Call `UnityServices.InitializeAsync()` from `com.unity.services.core` and sign in via `com.unity.services.authentication` before use.
+
+---
+
+## Four Execution Models
+
+| Model | Language | Client Method | Deployed as |
+|---|---|---|---|
+| **Scripts** | JavaScript | `CallEndpointAsync` | `.js` files via Deployment Window |
+| **Legacy modules** | C# (.NET 8, up to .NET 10) | generated bindings, or `CallModuleEndpointAsync` | `.ccmr` references to a .NET solution built outside Unity |
+| **Cloud Code modules** | C# (.NET 8; .NET 10 on Unity 6.7+) | generated bindings only | `.ccmu` assets, authored natively in the Editor |
+| **CloudBehaviours** (experimental) | C# (.NET 8; .NET 10 on Unity 6.7+) | generated bindings — `await behaviour.Method(args)` | `.ccmu` assets, authored natively in the Editor |
+
+**Recommendation:** Prefer **C#** over JavaScript scripts for production — type safety, generated client
+bindings, and access to NuGet packages. Do not write new scripts; maintain and call existing ones. Prefer authoring
+natively in the Editor (`.ccmu`) over a `.ccmr` reference for new work: the module lives in the project,
+compiles with it, and needs no separate solution. Between Cloud Code modules and CloudBehaviours, see
+the breakdown below.
+
+### Cloud Code Modules vs CloudBehaviours
+
+Both are C# modules, and both can hold state per scope with `[StateScope]`. They differ in how the client
+reaches them and in whether that state reaches the client on its own:
+
+| | Cloud Code modules | CloudBehaviours |
+|---|---|---|
+| **Endpoint naming** | one function per `[CloudCodeFunction]` | one generated `[CloudCodeFunction]` per public method you define, named `Behaviour__Method` |
+| **Scoped state** | `[StateScope]` persists public fields per player or session | the same, and public fields also synchronize to clients |
+| **Client updates** | request/response; subscribe by hand for push messages | synchronized fields and push events arrive on the generated bindings |
+| **Client code** | you write the call and deserialize the result | the bindings partial is generated from the cloud class |
+| **Requires** | `com.unity.services.cloudcode` `3.0.0`+, Unity 6000.5+ | `com.unity.services.cloudcode` `3.1.0-exp.1`+, Unity 6000.5+ |
+
+**Use CloudBehaviours when clients need to see the state** — shared match state, an inventory the client
+displays, per-player views of a shared secret, or a server-owned timer whose deadline the client shows.
+The bindings, the synchronization and the push plumbing are generated, so it is less code and less
+error-prone than a module plus hand-written calls and subscriptions.
+
+**Use Cloud Code modules when the client only needs the result of a call** — validating a purchase, awarding a
+reward, calling another service, running a trigger on a schedule. Scoped state still works; simpler than
+using CloudBehaviours if there is no need for state synchronization.
+
+## Where the details live
+
+| Reference | Covers |
+| :-- | :-- |
+| `references/cloud-code-modules.md` | Cloud Code modules (`.ccmu`), legacy modules (`.ccmr`) and scripts — creating a `.ccmu`, the `.ccmu` asset and how the deployed module name is derived, `ICloudCodeService`, subscriptions, triggers, module scope, generated bindings, deployment, error handling |
+| `references/cloud-code-cloudbehaviours.md` | CloudBehaviours — the authoring model, synchronized state, per-viewer projections, timers, access control |
+

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

@@ -0,0 +1,464 @@
+# 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 `references/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 | Fix |
+|---|---|---| :-- |
+| `Unknown` | 0 | Unknown error | Log `ex.Message`, retry once, then report it |
+| `NoInternetConnection` | 1 | No network | Retry when connectivity returns |
+| `ProjectIdMissing` | 2 | Project ID not set | Link the project in **Project Settings > Services** |
+| `PlayerIdMissing` | 3 | Player not signed in | Sign in before calling Cloud Save |
+| `AccessTokenMissing` | 4 | No access token | Sign in and check the token has not expired |
+| `InvalidArgument` | 5 | Bad input | Correct the keys or values named in the validation details |
+| `Unauthorized` | 6 | Not authorized | Check the access class and any Access Control policy denying the call |
+| `KeyLimitExceeded` | 7 | Too many keys stored | Delete unused keys |
+| `NotFound` | 8 | Key not found | Check the key and the access class used to read it |
+| `TooManyRequests` | 9 | Rate limited | Back off and retry after `RetryAfter` |
+| `ServiceUnavailable` | 10 | Service down | Retry with backoff |
+| `Conflict` | 11 | Write-lock conflict | Reload the keys, merge your change and retry with the new write lock |