@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/build-gtk/references/runtime-and-visualization.md

@@ -0,0 +1,191 @@
+# From authored graph to runtime, and back
+
+Graph Toolkit has no runtime. The pattern used by every official sample is: a `ScriptedImporter`
+registered on the graph's extension compiles the authored graph into a plain runtime asset at import
+time, the game loads that asset, and, optionally, editor-only code mirrors execution back into the
+open graph window through the GraphVisualization API.
+
+## Contents
+
+1. Assembly layout
+2. The importer
+3. Walking nodes and ports
+4. Runtime data model
+5. GraphVisualization: live debug view (6.6+)
+6. Building graphs from code
+
+## 1. Assembly layout
+
+- `Editor/` (or an Editor-only asmdef): graph, nodes, importer, toolbar, views. Graph Toolkit is an
+  Editor module, so its assemblies are available to editor code like `UnityEditor` itself: neither a
+  plain `Editor` folder nor an Editor-only asmdef needs a reference entry for it. The official
+  samples' editor asmdefs use `IPort` and `PortCapacity` with an empty `references` list.
+- `Runtime/` asmdef: the runtime data model and executor. Must not reference
+  `Unity.GraphToolkit.Editor`. Visualization calls live here under `#if UNITY_EDITOR`, because they
+  need the editor to be running the game.
+- If the runtime asset type is referenced from the importer, the Editor asmdef references the Runtime
+  asmdef, never the reverse.
+
+## 2. The importer
+
+```csharp
+using Unity.GraphToolkit.Editor;
+using UnityEditor.AssetImporters;
+
+[ScriptedImporter(1, DialogueGraph.AssetExtension)]       // bump the version to force reimport
+class DialogueGraphImporter : ScriptedImporter
+{
+    public override void OnImportAsset(AssetImportContext ctx)
+    {
+        var graph = GraphDatabase.LoadGraphForImporter<DialogueGraph>(ctx.assetPath);
+        if (graph == null)
+        {
+            Debug.LogError($"Failed to load dialogue graph: {ctx.assetPath}");
+            return;
+        }
+
+        var runtime = ScriptableObject.CreateInstance<DialogueRuntimeGraph>();
+        runtime.GraphId = graph.ID;
+        Build(graph, runtime);
+
+        ctx.AddObjectToAsset("Runtime", runtime);
+        ctx.SetMainObject(runtime);             // the .ext file now behaves as a DialogueRuntimeGraph in inspectors
+    }
+}
+```
+
+- Use `LoadGraphForImporter`, not `LoadGraph`, inside importers. The state machine equivalent is
+  `StateMachineDatabase.LoadStateMachineForImporter<T>`.
+- A null graph means the path, type or file is wrong; log and return.
+- Validation errors belong in `OnGraphChanged`, which already shows markers; the importer only needs
+  to bail out quietly when the graph is invalid.
+- Re-import happens on save. Sub-assets the game needs (textures, meshes) are added with further
+  `AddObjectToAsset` calls.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The asset shows as a generic Graph Toolkit asset instead of the runtime type | `ctx.SetMainObject(runtime)` missing | Call `SetMainObject` after `AddObjectToAsset` |
+| Importer changes have no effect on existing assets | Import results are cached per importer version | Bump the `ScriptedImporter` version number, or reimport |
+| The importer throws on an empty graph | No entry node to start from | Return early when the entry node is missing; `OnGraphChanged` already reports it |
+| Edits made from code vanish, or the import sees stale data | `LoadGraph` used inside the importer | `LoadGraphForImporter` in importers, `LoadGraph` everywhere else |
+
+## 3. Walking nodes and ports
+
+```csharp
+static INode Next(INode node, string outputPortName)
+{
+    var port = node.GetOutputPortByName(outputPortName);
+    return port?.FirstConnectedPort?.GetNode();          // null when unconnected
+}
+
+static T ValueOf<T>(INode node, string inputPortName)
+{
+    var port = node.GetInputPortByName(inputPortName);
+    if (port.IsConnected)
+    {
+        var source = port.FirstConnectedPort.GetNode();  // resolve upstream: constant node, variable node, or your node
+        if (source is IConstantNode constant && constant.TryGetValue<T>(out var c)) return c;
+        if (source is IVariableNode variable && variable.Variable.TryGetDefaultValue<T>(out var d)) return d;
+    }
+    port.TryGetValue<T>(out var embedded);               // the value typed on the node
+    return embedded;
+}
+```
+
+- Start from a dedicated entry node type: `graph.GetNodes().OfType<StartNode>().FirstOrDefault()`.
+- Ports with `PortCapacity.Multi` need `GetConnectedPorts(list)` rather than `FirstConnectedPort`.
+- Record `node.ID`, `port.ID` and wire endpoints (`outputPort.ID`, `inputPort.ID`) in the runtime
+  asset when a debug view is planned; the visualization API is keyed by these `Hash128` values.
+- Block nodes: iterate `contextNode.BlockNodes`; a block's `Index` is its order.
+- Subgraph nodes: `((ISubgraphNode)node).GetSubgraph()` returns the nested `Graph`; recurse.
+
+## 4. Runtime data model
+
+Keep it minimal and Unity-serializable: a `ScriptableObject` with a list of `[Serializable]` node
+records or `[SerializeReference]` polymorphic nodes, referencing each other by index or `Hash128`.
+Store only what execution needs; positions, titles and colors stay in the authoring asset. The
+Visual Novel Director sample is the reference layout: `Runtime/` asmdef with the data model and a
+`MonoBehaviour` executor that walks the records.
+
+## 5. GraphVisualization: live debug view (6.6+)
+
+The manual covers contexts, node progress, port values, errors and wires from `6000.7`, on the Debug
+graph view pages; the API is the same on 6.6. What it leaves out is the wiring from runtime code:
+
+```csharp
+#if UNITY_EDITOR
+using Unity.GraphToolkit.Editor.GraphVisualization;
+#endif
+
+class DialogueRunner : MonoBehaviour
+{
+#if UNITY_EDITOR
+    Context m_Debug;
+#endif
+
+    void OnEnable()
+    {
+#if UNITY_EDITOR
+        m_Debug = Registry.CreateVisualizationContext(runtimeGraph.GraphId);   // the authored Graph.ID
+#endif
+    }
+
+    void OnDisable()
+    {
+#if UNITY_EDITOR
+        m_Debug?.Dispose();
+#endif
+    }
+
+    void Enter(DialogueRuntimeNode node)
+    {
+#if UNITY_EDITOR
+        if (m_Debug is { IsValid: true, IsGraphLoaded: true })
+            m_Debug.Motion.Play(m_Debug.GetNodeReference(node.Id), 1f);
+#endif
+    }
+}
+```
+
+- Every visualization call is keyed by authored `Hash128` IDs, so the importer copies `Graph.ID`,
+  `node.ID` and the port IDs into the runtime asset (section 3).
+- Use one context per run: create it when the run starts and dispose it when the run ends. Call the
+  port reference's `ClearPreview()` when the flow leaves a node, or `ClearAllVisualization()` on the
+  context at run end, so previews do not pile up.
+- Add a `[GraphToolbarElement]` toggle that flips the context's `NodeCustomizationEnabled`,
+  `WireCustomizationEnabled` and `PortPreviewEnabled` (plus the `State`, `Transition` and `Condition`
+  ones on 6.7) so the debug view can be switched off.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Nothing shows on the graph | The context was created with the runtime asset's own ID instead of the authored `Graph.ID`, or the Graph window is not open (`IsGraphLoaded` is false) | Store `Graph.ID` in the runtime asset at import time and pass it to `CreateVisualizationContext` |
+| Visualization code breaks the player build | `GraphVisualization` is editor-only | Wrap the `using` and every call in `#if UNITY_EDITOR` |
+
+## 6. Building graphs from code
+
+Generators, migrations and tests build assets without the UI:
+
+```csharp
+var graph = GraphDatabase.LoadGraph<DungeonGraph>(path) ?? GraphDatabase.CreateGraph<DungeonGraph>(path);
+graph.UndoBeginRecordGraph("Generate dungeon");
+
+var start = new StartNode { Position = new Vector2(0, 0) };
+graph.AddNode(start);
+start.GetInputPortByName("Prefab").TrySetValue(startRoomPrefab);
+
+var room = new EncounterNode { Position = new Vector2(300, 0) };
+graph.AddNode(room);
+graph.Connect(start.GetOutputPortByName("Output"), room.GetInputPortByName("Input"));
+
+var enemies = graph.CreateVariable<GameObject>("Enemy");
+var enemyNode = graph.AddVariableNode(enemies, new Vector2(300, 150));
+graph.Connect(enemyNode.GetOutputPort(0), room.GetInputPortByName("Enemy"));
+
+GraphDatabase.SaveGraph(graph);
+graph.UndoEndRecordGraph();
+```
+
+Ports exist as soon as the node is added to the graph, because adding triggers `OnDefinePorts`.
+Set `Position` before or after adding; both work. State machines follow the same shape with
+`AddState`, `Connect(fromState, toState)`, `SaveStateMachine` and the `UndoBeginRecordStateMachine`
+pair.

package/skills/build-gtk/references/state-machine-api.md

@@ -0,0 +1,270 @@
+# State Machine API reference (Unity 6.7 and newer)
+
+All types live in `Unity.GraphToolkit.Editor`. None of this exists on Unity 6000.6 or older. There is
+no manual walkthrough yet: this file covers the patterns, and the Script Reference has the members.
+Page names such as `statemachine.md` are under
+`https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/graphtoolkit/editor/`, with
+`<VERSION>` at least `6000.7`.
+
+## Contents
+
+1. Concepts
+2. StateMachine class and asset lifecycle
+3. States
+4. Transitions and rules
+5. Conditions
+6. Custom self transitions
+7. Variables
+8. Validation with OnStateMachineChanged
+9. Context menus
+10. Custom UI for states and conditions
+11. Subgraph states
+12. Reading a state machine for a runtime
+
+## 1. Concepts
+
+- A `StateMachine` is a graph whose nodes are `State`s and whose wires are transitions. The state
+  machine owns transitions; states have no ports to define.
+- A transition connects a `FromState` to a `ToState`. A **self transition** has the same state on both
+  ends and is anchored on it.
+- A transition carries one or more **rules** (`ITransitionRule`). The transition is taken when the
+  conditions of any enabled rule hold. Each rule has a `RootCondition`, an `IGroupCondition` combining
+  child conditions with And/Or.
+- Conditions are either built in (group, variable comparison) or user types derived from
+  `Condition<T>` / `Condition`.
+- Everything about which state is active, when transitions fire, and what a condition means at
+  runtime is the user's code. Graph Toolkit stores the authoring data only.
+
+## 2. StateMachine class and asset lifecycle
+
+```csharp
+[StateMachine(AssetExtension)]               // optional second arg: StateMachineOptions flags
+[Serializable]
+class EnemyBrain : StateMachine
+{
+    public const string AssetExtension = "enemybrain";
+
+    [MenuItem("Assets/Create/AI/Enemy Brain")]
+    static void Create() => StateMachineDatabase.PromptInProjectBrowserToCreateNewAsset<EnemyBrain>();
+}
+```
+
+`StateMachineOptions` flags: `SupportsSubgraphs`,
+`DisableAutoInclusionOfStatesFromStateMachineAssembly`. `Default` and `None` are 0. The flag applies
+to states, conditions and self transitions alike.
+
+Members of `StateMachine` and `StateMachineDatabase` are in the Script Reference (`statemachine.md`,
+`statemachinedatabase.md`). Behavior the reference does not spell out:
+
+- `Connect(from, to)` creates a new transition with one empty rule on every call, so calling it twice
+  on the same pair gives two transitions. Add rules to an existing transition instead of reconnecting.
+  `Connect(s, s)` adds a rule to the state's self transition when it already has one.
+- Use `LoadStateMachineForImporter<T>` in importers, `LoadStateMachine<T>` everywhere else, and call
+  `SaveStateMachine` after edits from code.
+- Bracket edits in `UndoBeginRecordStateMachine` / `UndoEndRecordStateMachine`, passing the
+  conditions you edit to the first call.
+
+Mutating in `OnEnable`, `OnDisable` or `OnStateMachineChanged` throws `InvalidOperationException`.
+
+## 3. States
+
+```csharp
+[Serializable]
+[State("Movement", "Icons/Patrol.png", "Patrol")]        // args after the first are optional
+class PatrolState : State
+{
+    protected override void OnDefineOptions(IOptionDefinitionContext context)
+    {
+        context.AddOption<float>("Speed").WithDefaultValue(2f).WithTooltip("Units per second");
+        context.AddOption<string>("Notes").AsTextArea();
+    }
+}
+```
+
+`StateAttribute(categoryPath[, iconPath[, title[, stylesheet]]])` mirrors `NodeAttribute`.
+
+State options appear only in the Graph Inspector, never on the state itself.
+`State.IOptionDefinitionContext`: `AddOption<T>(name)`, `AddOption(name, Type)`. Builder
+`IStateOptionBuilder`: `WithDisplayName`, `WithTooltip`, `WithDefaultValue`, `Delayed`, `AsTextArea`,
+`Build()`. Read back with `GetOptionByName(name).TryGetValue<T>(out v)`; `IStateOption` also has
+`DataType`, `Name`, `DisplayName`, `Tooltip`, `TrySetValue<T>`.
+
+`State` / `IState` members: `StateMachine`, `Hash128 ID`, `Title`, `Subtitle`, `Tooltip`,
+`Color DefaultColor`, `float FillAmount`, `Vector2 Position`, `bool IsConnected`,
+`GetIncomingTransitions()`, `GetOutgoingTransitions()`, `Options`, `OptionCount`, `GetOption(int)`,
+`GetOptionByName(string)`, `RemoveFromStateMachine()`. `OnEnable()` and `OnDisable()` are on the
+`State` class only, not on `IState`.
+
+Discovery: states in the state machine's assembly are listed automatically; elsewhere use
+`[UseWithStateMachine(typeof(EnemyBrain))]`. `[UseWithGraph]` is ignored by state machines.
+
+## 4. Transitions and rules
+
+Users create transitions by dragging from a state's edge (Shift + left mouse also starts one). In
+code use `stateMachine.Connect(from, to)`.
+
+Members are in `itransition.md`, `itransitionrule.md` and `igroupcondition.md`. A transition always
+keeps at least one rule; removing the last one is refused. Each rule's `RootCondition` is an
+`IGroupCondition` whose `Operation` is `GroupConditionOperation.And` or `GroupConditionOperation.Or`;
+`Get()` enumerates its children, `Count` and `Get(int)` index them. Regular transitions are styled through
+`ITransition` properties, not subclassed.
+
+## 5. Conditions
+
+```csharp
+[Serializable]
+[Condition("Distance to player")]                 // title in the Add menu of a rule
+class DistanceCondition : Condition<float>
+{
+    public override string Tooltip => "Compared against the distance to the player.";
+    protected override bool DisplayComparisonDropdown => true;
+    protected override IReadOnlyList<ConditionComparison> SupportedComparisons =>
+        new[] { ConditionComparison.Less, ConditionComparison.Greater };
+}
+
+[Serializable]
+[Condition("Took damage")]
+class TookDamageCondition : Condition { }         // valueless trigger, label-only row
+```
+
+- Members are in `condition.md` (both `Condition` and `Condition<T>`) and `conditioncomparison.md`.
+  `DisplayComparisonDropdown` defaults to false; override `SupportedComparisons` to limit the operators.
+- Built-in conditions, created in code with `Condition.CreateGroupCondition()` and
+  `Condition.CreateVariableCondition(IVariable variable, object defaultValue, ConditionComparison comparison = ConditionComparison.Equal)`.
+  Read them through `IGroupCondition` and `IVariableCondition` (`Variable`, `Comparison`, `Value`).
+- Without a `[Condition]` attribute the type name is used as the title. Abstract and open generic
+  condition classes are not listed.
+- Same discovery rules as states: same assembly, or `[UseWithStateMachine(...)]`.
+
+`Condition` has no lifecycle callbacks, so an `OnEnable` override on a condition does not compile.
+Only `StateMachine`, `State` and `SelfTransition` expose `OnEnable` / `OnDisable` here.
+
+Editing a condition value from code: `UndoBeginRecordStateMachine("Set distance", condition)`,
+assign `condition.Value`, `UndoEndRecordStateMachine()`, then `SaveStateMachine`.
+
+## 6. Custom self transitions
+
+```csharp
+[Serializable]
+[UseWithStateMachine(typeof(EnemyBrain))]
+[Transition("", "Icons/Loop.png", "Repeat")]      // (categoryPath[, iconPath[, title]])
+class RepeatTransition : SelfTransition
+{
+    public override void OnEnable()
+    {
+        base.OnEnable();
+        LineColor = Color.cyan;
+        Tooltip = "Loops the state while its conditions hold.";
+    }
+}
+```
+
+Custom self transitions appear in a state's Create Transition menu. `SelfTransition` exposes the
+`ITransition` members plus `Tooltip`, `OnEnable`, `OnDisable`. Regular state-to-state transitions are
+not subclassed; style them through `ITransition` properties.
+
+## 7. Variables
+
+`stateMachine.CreateVariable<int>("Health", 100)` declares a Blackboard variable that the built-in
+variable condition can compare against. `IVariable.StateMachine` gives the owner. Variable kinds and
+members are the same as in the Graph API.
+
+## 8. Validation with OnStateMachineChanged
+
+```csharp
+public override void OnStateMachineChanged(StateMachineLogger logger)
+{
+    foreach (var state in GetStates())
+        if (!state.GetOutgoingTransitions().Any() && state is not EndState)
+            logger.LogWarning("Dead end: add a transition out of this state.", state);
+
+    foreach (var change in logger.StateMachineChanges.ChangedTransitions)
+        if ((change.ChangeKinds & ChangeKind.Added) != 0) { /* new transition */ }
+}
+```
+
+`StateMachineLogger` and `StateMachineChanges` work like `GraphLogger` and `GraphChanges`
+(`statemachinelogger.md`, `statemachinechanges.md`): pass a state or transition as the context to put
+the marker on it, and attach a `StateMachineLogAction` for a fix button.
+
+## 9. Context menus
+
+```csharp
+[StateMachineMenu(typeof(EnemyBrain))]
+static void AddEntries(StateMachineMenuContext context)
+{
+    switch (context.ClickedObject)
+    {
+        case IState state:           context.AppendAction("Log state", () => Debug.Log(state.Title)); break;
+        case ITransition transition: context.AppendAction("Log rules", () => Debug.Log(transition.RuleCount)); break;
+        default:                     context.AppendAction("Canvas action", () => { }); break;
+    }
+}
+
+[ConditionMenu(typeof(EnemyBrain))]
+static void AddConditionEntries(ConditionMenuContext context)   // context.StateMachine, .Transition, .Rule
+{
+}
+```
+
+## 10. Custom UI for states and conditions
+
+- `class PatrolView : StateView<PatrolState>`: `State`, `View.Root`, `OnViewBuilt()`,
+  `OnViewAttached()`, `OnViewDetached()`, `OnViewLODChanged(float)`, `OnCullingChanged(bool)`.
+  Allocate elements in `OnViewBuilt` and re-add them in `OnCullingChanged(false)`; never allocate in
+  `OnViewAttached`.
+- `class DistanceView : ConditionView<DistanceCondition>` (no LOD or culling callbacks): `Condition`,
+  `View.Root`, `OnViewBuilt()`, `OnViewAttached()`, `OnViewDetached()`, `OnConditionChanged()`, and
+  the toggles `protected virtual bool DisplayValueField`, `DisplayTitleLabel`. Add to `Root`; do not
+  remove or reparent the built-in row elements. View instances are never serialized.
+- Exceptions thrown by a view are logged and the built-in UI still renders.
+
+## 11. Subgraph states
+
+With `StateMachineOptions.SupportsSubgraphs`, a state can hold a nested state machine.
+`ISubgraphState : IState` marks such states; `StateMachineChanges.ChangedSubgraphStates` reports them.
+
+## 12. Reading a state machine for a runtime
+
+```csharp
+[ScriptedImporter(1, EnemyBrain.AssetExtension)]
+class EnemyBrainImporter : ScriptedImporter
+{
+    public override void OnImportAsset(AssetImportContext ctx)
+    {
+        var sm = StateMachineDatabase.LoadStateMachineForImporter<EnemyBrain>(ctx.assetPath);
+        if (sm == null) { Debug.LogError($"Failed to load {ctx.assetPath}"); return; }
+
+        var runtime = ScriptableObject.CreateInstance<RuntimeBrain>();
+        foreach (var state in sm.GetStates())
+        {
+            var rs = new RuntimeState { Id = state.ID, Name = state.Title };
+            state.GetOptionByName("Speed")?.TryGetValue<float>(out rs.Speed);
+            foreach (var transition in state.GetOutgoingTransitions())
+                foreach (var rule in transition.GetRules())
+                    if (rule.Enabled)
+                        rs.Transitions.Add(new RuntimeTransition
+                        {
+                            Target = transition.ToState.ID,
+                            Predicate = Compile(rule.RootCondition)
+                        });
+            runtime.States.Add(rs);
+        }
+        ctx.AddObjectToAsset("Runtime", runtime);
+        ctx.SetMainObject(runtime);
+    }
+
+    static RuntimePredicate Compile(ICondition condition) => condition switch
+    {
+        IGroupCondition g      => RuntimePredicate.Group(g.Operation, g.Get().Select(Compile)),
+        IVariableCondition v   => RuntimePredicate.Variable(v.Variable.Name, v.Comparison, v.Value),
+        DistanceCondition d    => RuntimePredicate.Distance(d.Comparison, d.Value),
+        TookDamageCondition    => RuntimePredicate.Trigger("TookDamage"),
+        _                      => RuntimePredicate.Never
+    };
+}
+```
+
+Identify the entry state by a dedicated `State` subclass or a state machine option; the API has no
+built-in "default state". Keep `Hash128` IDs in the runtime asset if the GraphVisualization API will
+highlight states later.

package/skills/build-gtk/references/where-the-docs-stop.md

@@ -0,0 +1,49 @@
+# Step 3: Where the docs stop
+
+The manual covers the 6.6 Graph API. These parts have no manual page yet, so read the reference file
+before writing code. Paths are relative to this skill's folder.
+
+- **Importer to a runtime asset, and wiring the debug view from runtime code:** [`references/runtime-and-visualization.md`](runtime-and-visualization.md).
+  The importer always has this shape:
+
+  ```csharp
+  var graph = GraphDatabase.LoadGraphForImporter<MyGraph>(ctx.assetPath);    // never LoadGraph here
+  if (graph == null) return;                                                  // bad path or type: log and stop
+  var start = graph.GetNodes().OfType<StartNode>().FirstOrDefault();
+  if (start == null) return;                                                  // OnGraphChanged already reported it
+  var next = start.GetOutputPortByName("Next").FirstConnectedPort?.GetNode(); // null when unconnected
+  var titlePort = next.GetInputPortByName("Title");
+  titlePort.TryGetValue<string>(out var title);                               // the value typed on the node
+  if (titlePort.IsConnected) { /* resolve titlePort.FirstConnectedPort.GetNode() upstream instead */ }
+  ctx.AddObjectToAsset("Runtime", runtime); ctx.SetMainObject(runtime);
+  ```
+
+  The runtime asset keeps `Hash128` IDs as `Hash128` and never references `Unity.GraphToolkit.Editor`.
+- **State machines (6000.7+):** [`references/state-machine-api.md`](state-machine-api.md). The core types:
+
+  ```csharp
+  [StateMachine(AssetExtension)] [Serializable]
+  class EnemyBrain : StateMachine
+  {
+      public const string AssetExtension = "enemybrain";
+      [MenuItem("Assets/Create/AI/Enemy Brain")]
+      static void Create() => StateMachineDatabase.PromptInProjectBrowserToCreateNewAsset<EnemyBrain>();
+  }
+
+  [Serializable] class Patrol : State { }                     // no ports; the state machine owns transitions
+
+  [Serializable] [Condition("Distance to player")]
+  class DistanceCondition : Condition<float>                  // derive from Condition for a valueless trigger
+  {
+      protected override bool DisplayComparisonDropdown => true;
+  }
+  ```
+
+  Validation goes in `OnStateMachineChanged(StateMachineLogger)`. An importer walks
+  `GetStates()`, each state's `GetOutgoingTransitions()`, each transition's `GetRules()` and each rule's
+  `RootCondition`. That tree always contains built-in conditions, so handle `IGroupCondition` (recurse,
+  honor `Operation`, a `GroupConditionOperation` of `And` or `Or`) and `IVariableCondition` before matching custom `Condition<T>` types.
+- **Knowing what changed, and the other 6.7 Graph API additions:** [`references/graph-api-gaps.md`](graph-api-gaps.md).
+  On 6000.7+, `logger.GraphChanges.ChangedNodes` reports added and modified nodes. Removed nodes are
+  never reported, so on every version, and for all changes on 6000.6, diff a `[NonSerialized]`
+  `HashSet<Hash128>` of node IDs against `GetNodes()`.

package/skills/build-live-game/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: build-live-game
+description: Builds and operates a live game's backend with Unity Gaming Services. Make sure to use this skill when the user wants trusted server-side game logic, player progress, remote configuration, sign-in, achievements, battle passes or leaderboards.
+---
+
+# Build a Live Game With Unity Gaming Services
+
+## Before You Start
+
+1. Read the Editor version from `ProjectSettings/ProjectVersion.txt` and the installed UGS package versions from `Packages/packages-lock.json`. Pick the steps below that match (for example `.ccmu` or `.ccmr` modules), because the right workflow depends on the Editor and package versions.
+2. Check whether the project is linked to a Unity project ID and environment (**Edit > Project Settings > Services**), and ask the user to link it if it is not.
+3. Create a restore point you can roll back to if your changes fail: commit the project in version control. If there is no version control, copy the project folder instead.
+4. Before you go forward with a workflow or diagnosis, open and read the documentation pages for the service you will use (see [Documentation Map](#documentation-map)) and the matching file under `references/`, and name the pages you read in your response. This is because your training knowledge about Unity Gaming Services might be out of date, incorrect, or for the wrong package version.
+5. Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.
+6. When you change runtime behaviour, add `Debug.Log` lines at the points you need to verify (sign-in complete, module call returned, config fetched). You read them in Play mode during [Validation](#validation).
+
+## Glossary
+
+Read [orientation.md](references/orientation.md#glossary) when a UGS term is ambiguous, such as Building Block, `.ccmu` versus `.ccmr`, CloudBehaviour, or protected versus custom data. It maps each term to what the Editor, the package API and the documentation call it.
+
+## Documentation Map
+
+Read [orientation.md](references/orientation.md#documentation-map) before acting on any service, because training knowledge about Unity Gaming Services is often out of date. It lists the pages to read per service and how to version the package URLs.
+
+## UGS Packages
+
+| Package | Min Version | Purpose |
+|---|---|---|
+| `com.unity.services.core` | 1.16.0 | Initialization, dependency graph |
+| `com.unity.services.authentication` | 3.6.1 | Player sign-in and identity |
+| `com.unity.services.cloudcode` | 3.0.0 | Server-authoritative C# modules, authored in-project as `.ccmu`. The `2.10.x` line deploys legacy `.ccmr` only — see below |
+| `com.unity.services.cloudsave` | 3.4.0 | Per-player and shared key-value storage |
+| `com.unity.remote-config` | 4.2.5 | Server-side game configuration |
+| `com.unity.services.deployment` | 1.7.2 | Deploy cloud resources from Editor |
+| `com.unity.services.tooling` | 1.4.1 | Access Control and Game Overrides |
+| `com.unity.services.apis` | 1.1.1 | Generated REST clients for all UGS services |
+
+- [Before You Start](#before-you-start)
+- [Glossary](#glossary)
+- [Documentation Map](#documentation-map)
+- [Initialization Pattern](#initialization-pattern)
+- [Architecture — How Packages Combine](#architecture--how-packages-combine)
+- [Core Services — Quick Reference](#core-services--quick-reference)
+- [Common Architecture Patterns](#common-architecture-patterns)
+- [Validation](#validation)
+- [Detailed References](#detailed-references)
+- [Final Report](#final-report)
+
+## Initialization Pattern
+
+Every UGS game starts the same way. `com.unity.services.core` must initialize first, then the player signs in:
+
+```csharp
+using Unity.Services.Core;
+using Unity.Services.Authentication;
+
+await UnityServices.InitializeAsync();
+await AuthenticationService.Instance.SignInAnonymouslyAsync();
+// All other services are now ready
+```
+
+## Architecture — How Packages Combine
+
+```
+                    UnityServices.InitializeAsync()
+                              │
+                              ▼
+                     AuthenticationService
+                    (sign in → PlayerId)
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+        Remote Config     Cloud Save      Multiplayer
+      (game config,    (player state,   (sessions,
+       definitions,     progress,        matchmaking,
+       feature flags)   preferences)     lobbies)
+              │               │
+              └───────┬───────┘
+                      ▼
+                 Cloud Code
+              (server-authoritative
+               writes, validation,
+               anti-cheat logic)
+                      │
+              ┌───────┴───────┐
+              ▼               ▼
+         Cloud Save       Leaderboards
+         (Protected       (score
+          writes)          submission)
+```
+
+**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
+
+Read [services-overview.md](references/services-overview.md) to choose the right package and authoring model for a feature, including when to write `.ccmu` instead of `.ccmr` and when CloudBehaviours apply. It summarises each service, the version that supports it, and the full reference for its API.
+
+## 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, run these checks in order. If one fails, fix the cause and re-run it before moving on; if the fix does not work, go back and reread the matching documentation pages and `references/` file.
+
+1. Check the project compiles: read the Editor console (or the Editor log) and confirm zero compile errors.
+2. Check the initialization order in the code: search for `UnityServices.InitializeAsync()` and confirm it runs before the sign-in call, and that sign-in completes before any service call.
+3. Check that sensitive writes (XP, rewards, currency) go through Cloud Code: search the client code for Cloud Save `SaveAsync` calls on those keys and move any you find into a module. Also confirm each Cloud Save read uses the access class of the bucket that was written to, because a mismatched class returns no data.
+4. Deploy the cloud resource files the feature uses (`.rc`, `.ac`, `.ccmu` or `.ccmr`, `.lb`; skip the types it does not use) to the active environment with the `Deploy.cs` script in `references/deployment.md`, and read its output: every file must report `Success`. A file reported as `not a deployable item`, or with an `Error` status, has failed. If the project does not have both packages the script needs, `com.unity.pipeline` and `com.unity.services.deployment.api`, ask the user to deploy from the Deployment Window and report each file's status.
+5. Check Access Control by its effect: if the feature deploys an `.ac` policy that denies direct player writes, enter Play mode, run one direct client Cloud Save write to a key the policy covers (a temporary `SaveAsync` call), and confirm it fails with a `403`. Remove the temporary call afterwards. Skip this step when the feature has no `.ac` file.
+6. Enter Play mode, run the feature once, and confirm the `Debug.Log` lines from [Before You Start](#before-you-start) appear in the order you expect and the console has zero errors.
+
+## Detailed References
+
+### Service References
+- **Authentication** — sign-in methods, events, profiles, identity providers, code templates: [references/authentication.md](references/authentication.md)
+- **Cloud Code** — choosing a model: [references/cloud-code.md](references/cloud-code.md); scripts and modules: [references/cloud-code-modules.md](references/cloud-code-modules.md); CloudBehaviours: [references/cloud-code-cloudbehaviours.md](references/cloud-code-cloudbehaviours.md)
+- **Cloud Save** — access classes, data operations, files, queries, code templates: [references/cloud-save.md](references/cloud-save.md)
+- **Remote Config** — definitions, `.rc` format, Game Overrides, code templates: [references/remote-config.md](references/remote-config.md)
+- **Tooling** — Access Control (`.ac`) policies, Game Overrides (`.ugo`), URN reference: [references/tooling.md](references/tooling.md)
+- **Deployment** — file types, workflow, programmatic API: [references/deployment.md](references/deployment.md)
+- **UGS CLI** — `unity ugs` plugin install, auth/setup, headless deploy by file type: [references/ugs-cli.md](references/ugs-cli.md)
+- **Services APIs** — four client types, service areas, code templates: [references/apis.md](references/apis.md)
+
+### Feature Blueprints
+- **Choosing a starting point** — this skill's blueprints, Asset Store Building Blocks and sample projects, and how to reuse their legacy Cloud Code: [references/blueprints-and-samples.md](references/blueprints-and-samples.md)
+- **Achievements** — full implementation with data models, client code, Cloud Code module, cloud resources: [references/achievements.md](references/achievements.md)
+- **Battle Pass** — implementation with tiered XP, free/premium tracks, Cloud Code module, cloud resources (premium purchase is an integration stub you must complete): [references/battlepass.md](references/battlepass.md)
+- **Player Account** — sign-in flows, identity management, Cloud Save data, code templates: [references/player-account.md](references/player-account.md)
+
+## Final Report
+
+When the work is done, end your response with a short report:
+
+1. What you created or changed: files, packages added to `Packages/manifest.json`, and cloud resource files.
+2. The checks from [Validation](#validation) that you ran and their results, including any you could not run and why.
+3. Follow-ups only the user can do, for example: deploy the cloud resources to the target environment, link the project to a Unity project ID and environment, complete a stubbed integration (such as battle pass `PurchasePremium`), or restore from the restore point you created if they reject the changes.
+4. Which documentation pages you read.