@aqian0/dsh-unity 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,231 @@
+# 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 (native) | `com.unity.services.cloudcode` | `.ccmu` | 3.0.0 |
+| Cloud Code C# Modules (legacy) | `com.unity.services.cloudcode` | `.ccmr` | 2.5.0 |
+| Remote Config | `com.unity.remote-config` | `.rc` | 3.2.0 |
+| 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 |
+| Triggers | `com.unity.services.tooling` | `.tr` | 1.4.2 |
+| Scheduler | `com.unity.services.tooling` | `.sched` | 1.4.2 |
+| 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 `references/apis.md` for the full `IAdminClient` interface and code templates.
+
+### Code Template -- Trigger Deployment Programmatically
+
+Run it with `unity command run_script --file AgentScripts/Deploy.cs --entry Deploy.Run --args '[["Assets/MyConfig.rc"]]'`
+(needs the `com.unity.pipeline` and `com.unity.services.deployment.api` packages; keep the file outside `Assets/`). `DeploymentWindow` throws
+*"Deployment Window must be opened for this operation."* until the window is open, so the script opens it
+and waits.
+
+```csharp
+// AgentScripts/Deploy.cs — deploys to the active environment. Await; never .Wait(), which deadlocks the main thread.
+using System.Linq;
+using System.Threading.Tasks;
+using Unity.Services.DeploymentApi.Editor;
+using UnityEditor;
+
+public static class Deploy
+{
+    public static async Task<string> Run(string[] paths)
+    {
+        var deployments = Deployments.Instance;
+        if (!(deployments.DeploymentWindow is EditorWindow))
+            deployments.DeploymentWindow.OpenWindow();
+        for (var i = 0; i < 100 && !(deployments.DeploymentWindow is EditorWindow); i++)
+            await Task.Delay(100);
+
+        var items = deployments.DeploymentWindow.GetFromFiles(paths);
+        var found = items.Where(item => item != null).ToList();
+        // Deploy all items instead: await deployments.DeploymentWindow.Deploy(deployments.DeploymentWindow.GetAllDeploymentItems());
+        if (found.Count > 0)
+            await deployments.DeploymentWindow.Deploy(found);
+        return string.Join("\n", paths.Select((path, i) => items[i] == null
+            ? $"{path}: not a deployable item"
+            : $"{path}: {items[i].Status.MessageSeverity} {items[i].Status.Message} {items[i].Status.MessageDetail}"));
+    }
+}
+```

package/skills/build-live-game/references/orientation.md

@@ -0,0 +1,30 @@
+# Glossary
+
+| Term | Meaning |
+|---|---|
+| **UGS** | Unity Gaming Services: the backend services (Authentication, Cloud Code, Cloud Save, Remote Config, Leaderboards and others). The Package Manager calls them "Unity Services" |
+| **Building Block** | A free Asset Store package with UI, runtime code and cloud resource files for one feature. Its Cloud Code is legacy `.ccmr` |
+| **Cloud Code module** | Server-side C# class library. Authored in the Unity project as a `.ccmu` asset on Unity 6000.5+ |
+| **`.ccmr`** | Legacy module reference file that points at a C# solution built outside Unity |
+| **Script** | Server-side JavaScript endpoint. Legacy: maintain existing ones, don't write new ones |
+| **CloudBehaviour** | Experimental Cloud Code class that generates client bindings, synchronized state and push events |
+| **Protected data** | Cloud Save player data that the player can read but only server code can write |
+| **Custom data** | Cloud Save game-wide data, not tied to one player, written only by server code |
+| **Cloud resource file** | A deployable config file (`.rc`, `.ac`, `.ccmu`, `.ccmr`, `.lb`, `.ugo`) that the Deployment Window pushes to a UGS environment |
+
+# Documentation Map
+
+Prefer `WebFetch` over `WebSearch`: it is faster and lands on the exact reference. Only fetch what you need. Pages on docs.unity.com are available as Markdown when the URL ends in `.md`. Replace `<VERSION>` with the following before fetching:
+
+- **Package on docs.unity3d.com**: the installed package version as `major.minor`, for example `3.0`. Read it from `Packages/packages-lock.json` if unsure.
+- **docs.unity.com**: the UGS product pages below are unversioned, so there is nothing to replace.
+
+Pages to read before acting:
+
+- Cloud Code C# modules: [Overview](https://docs.unity.com/en-us/cloud-code/modules/overview.md), [Get started](https://docs.unity.com/en-us/cloud-code/modules/getting-started.md), [Module structure](https://docs.unity.com/en-us/cloud-code/modules/how-to-guides/module-structure.md), [Error handling](https://docs.unity.com/en-us/cloud-code/modules/how-to-guides/error-handling.md), [Limits](https://docs.unity.com/en-us/cloud-code/modules/reference/limits.md)
+- Cloud Code server authority: [Server authority](https://docs.unity.com/en-us/cloud-code/server-authority.md), [Cheat prevention](https://docs.unity.com/en-us/cloud-code/cheat-prevention.md), [UGS integration and access control](https://docs.unity.com/en-us/cloud-code/server-access-control.md)
+- Authentication: [How Authentication works](https://docs.unity.com/en-us/authentication/how-authentication-works.md), [Sessions and cached players](https://docs.unity.com/en-us/authentication/session-management.md), [Common errors](https://docs.unity.com/en-us/authentication/common-errors.md)
+- Cloud Save: [Player Data](https://docs.unity.com/en-us/cloud-save/concepts/player-data.md), [Game Data](https://docs.unity.com/en-us/cloud-save/concepts/game-data.md), [Cloud Save for Cloud Code](https://docs.unity.com/en-us/cloud-save/tutorials/cloud-code.md)
+- Remote Config: [Remote Config files](https://docs.unity.com/en-us/remote-config/remote-config-files.md), [Code integration](https://docs.unity.com/en-us/remote-config/code-integration.md)
+- Leaderboards: [Overview](https://docs.unity.com/en-us/leaderboards.md), [Unity SDK tutorial](https://docs.unity.com/en-us/leaderboards/tutorials/unity-sdk.md)
+- Deployment Window: [Deployment package manual](https://docs.unity3d.com/Packages/com.unity.services.deployment@<VERSION>/manual/index.html)