@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/asset-transformer-toolkit/references/ruleblock-api.md

@@ -0,0 +1,37 @@
+## ActionBase properties
+
+### `Id`
+
+```csharp
+public abstract int Id { get; }
+```
+
+A unique integer identifier for an action type. Pass this to the `RuleBlock(int actionId)` constructor.
+
+## RuleBlock constructors
+
+The RuleBlock API reference contains the following constructors.
+
+### `RuleBlock(int actionId)`
+
+This constructor creates a RuleBlock that will execute the action identified by `actionId`. The action instance is created lazily on first access.
+
+```csharp
+public RuleBlock(int actionId)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `actionId` | int | required | The ID of the action this RuleBlock will trigger. Use `ActionBase.Id` to obtain this value from an action instance. |
+
+## RuleBlock properties
+
+The RuleBlock API reference contains the following properties.
+
+### `IsEnabled`
+
+```csharp
+public bool IsEnabled { get; set; }
+```
+
+Controls whether this block is active within its Rule. When `false`, the block is skipped during execution.

package/skills/asset-transformer-toolkit/references/ruleset-api.md

@@ -0,0 +1,138 @@
+## Contents
+- [RuleSet methods](#ruleset-methods) — `GetRule`, `GetRuleIndex`, `RemoveRuleAt`, `RemoveRule`, `InsertRule`, `AppendRule`, `IsValid`
+- [RuleSet properties](#ruleset-properties) — `RulesCount`
+- [RuleSet utility functions](#ruleset-utility-functions) — `RunRuleSet`
+
+---
+
+## RuleSet methods
+
+The RuleSet API reference contains the following methods.
+
+### `GetRule`
+
+This method retrieves the `Rule` at the specified index.
+
+```csharp
+public Rule GetRule(int i)
+```
+
+`GetRule` accepts the following parameter.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `i` | int | required | Zero-based index of the rule to retrieve. |
+
+This method returns the `Rule` at the given index.
+
+### `GetRuleIndex`
+
+This method returns the index of the given `Rule` within the RuleSet. Returns `-1` and logs an error if the RuleSet is currently running.
+
+```csharp
+public int GetRuleIndex(Rule rule)
+```
+
+`GetRuleIndex` accepts the following parameter.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `rule` | Rule | required | The `Rule` whose index to find. |
+
+This method returns an `int` index, or `-1` if the RuleSet is running or the rule is not found.
+
+### `RemoveRuleAt`
+
+This method removes the rule at the specified index. Has no effect and logs an error if the RuleSet is currently running.
+
+```csharp
+public void RemoveRuleAt(int index)
+```
+
+`RemoveRuleAt` accepts the following parameter.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `index` | int | required | Zero-based index of the rule to remove. |
+
+### `RemoveRule`
+
+This method removes a specific `Rule` instance from the RuleSet. Has no effect and logs an error if the RuleSet is currently running.
+
+```csharp
+public void RemoveRule(Rule rule)
+```
+
+`RemoveRule` accepts the following parameter.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `rule` | Rule | required | The `Rule` instance to remove. |
+
+### `InsertRule`
+
+This method inserts a `Rule` at the specified index, shifting subsequent rules down. Has no effect and logs an error if the RuleSet is currently running.
+
+```csharp
+public void InsertRule(int index, Rule rule, bool notify)
+```
+
+`InsertRule` accepts the following parameters.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `index` | int | required | Zero-based position at which to insert the rule. |
+| `rule` | Rule | required | The `Rule` instance to insert. |
+| `notify` | bool | required | When `true`, notifies the UI that the RuleSet has changed. |
+
+### `AppendRule`
+
+This method adds a `Rule` to the end of the RuleSet. Has no effect and logs an error if the RuleSet is currently running.
+
+```csharp
+public void AppendRule(Rule rule)
+```
+
+`AppendRule` accepts the following parameter.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `rule` | Rule | required | The `Rule` instance to append. |
+
+### `IsValid`
+
+This method validates that every enabled action in the RuleSet has valid input. It skips disabled rules.
+
+```csharp
+public bool IsValid()
+```
+
+This method accepts no parameters. It returns `true` if all enabled actions pass validation, or `false` if any action reports an error.
+
+## RuleSet properties
+
+The RuleSet API reference contains the following properties.
+
+### `RulesCount`
+
+```csharp
+public int RulesCount { get; }
+```
+
+The number of `Rule` instances currently in the RuleSet.
+
+## RuleSet utility functions
+
+The following functions are from `Unity.Pixyz.Plugin4Unity.Editor.AI.ATTAssistantUtilities`.
+
+### `RunRuleSet`
+
+This function executes all rules in a RuleSet asset against the current scene selection, or the entire scene if nothing is selected.
+
+```csharp
+public static void RunRuleSet(string rulesetPath)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `rulesetPath` | string | required | Project-relative path to the RuleSet asset to run. |

package/skills/asset-transformer-toolkit/references/rulesets-and-actions.md

@@ -0,0 +1,227 @@
+## Contents
+- [Actions](#actions)
+- [RuleSets](#rulesets)
+  - Description
+  - Modifying RuleSets
+  - Creating RuleSets
+  - Setting Action Parameters
+  - Running RuleSets
+  - Validation Checklist
+- [Action utility functions](#action-utility-functions) — `GetActionsList`, `GetActionDefinitions`, `SetActionParameter`
+- [Action utility output types](#action-utility-output-types) — `ActionInfo`, `ActionDefinition`, `ActionParameterInfo`, `EnumInfo`
+
+---
+
+## Actions
+
+Actions are classes derived from UnityEditor.PixyzPlugin4Unity.Actions.ActionBase that execute a task on a list of input objects.
+It is expected that users will create additional Action classes to extend the Actions available in the base package.
+
+## RuleSets
+
+### Description
+RuleSets are a SerializedObject containing a list of Rule instances, which contain a list of Action instances. RuleSets are used to ensure a set of Actions are executed in a specific order.
+RuleSets are derived from ScriptableObject and must end with the '.asset' extension.
+RuleSets support conversion to json. This will include information about the Actions they contain.
+
+### Modifying RuleSets
+
+#### Step 1: Load RuleSet
+- Use AssetDatabase.LoadAssetAtPath to load the asset from memory.
+
+#### Step 2: Construct the script
+- Read the API reference for the RuleSet class. Also read the API reference for the Rule and RuleBlock classes if required.
+- Construct a script using the APIs from those files, to run as C# in a live Editor. Here is an
+  example that adds a Decimate Action to a RuleSet:
+
+```csharp
+using UnityEngine;
+using UnityEditor;
+using UnityEditor.PixyzPlugin4Unity.RuleEngine;
+
+string path = "Assets/Rulesets/OptimizationRuleSet.asset";
+RuleSet ruleSet = AssetDatabase.LoadAssetAtPath<RuleSet>(path);
+
+if (ruleSet == null)
+    throw new System.Exception($"RuleSet not found at {path}");
+
+Undo.RecordObject(ruleSet, "Add Decimate action");
+
+if (ruleSet.RulesCount == 0)
+    throw new System.Exception($"No rules found in RuleSet {path}");
+
+Rule rule = ruleSet.GetRule(0);
+
+// Decimate Action ID is 277054868
+RuleBlock decimateBlock = new RuleBlock(277054868);
+
+rule.AppendBlock(decimateBlock);
+
+EditorUtility.SetDirty(ruleSet);
+AssetDatabase.SaveAssets();
+
+return $"Added Decimate action to {path} (Rule index 0)";
+```
+
+A proper script for modifying a RuleSet has the following traits:
+- Does not use the ScriptableObject API (this bypasses necessary event triggers).
+
+#### Step 3: Validation
+- Run the script as C# in a live Editor.
+- Validate the RuleSet against the validation checklist.
+
+
+### Creating RuleSets
+
+#### Step 1: Create RuleSet
+- Create the UnityEditor.PixyzPlugin4Unity.RuleEngine.RuleSet asset.
+Continue to Step 2 if actions need to be added to the RuleSet. If not, add the GetContextGameObjects action and jump to Step 3.
+
+#### Step 2: Add Actions
+
+**Preflight**
+- Ensure the RuleSet exists.
+- Choose the combination of Actions that will best perform the requested procedure. NEVER create new Actions without explicit permission. Instead, use the Actions returned by `GetActionsList`.
+- Divide Actions into Rules based on the GameObject they need to act upon. Each Rule initially executes on every GameObject unless the input is narrowed with a Filter action. Example: If only lights need to be disabled and only meshes with >10000 vertices need to be decimated, two rules will be needed as this is two different groups of GameObjects.
+
+**Adding Rules**
+- Check whether the existing Rule(s) in the RuleSet is just the GetContextGameObjects action. If it is, append the group of actions to it rather than creating a new Rule.
+- If a new Rule needs to be created, add it to the RuleSet.
+- Add Actions to the Rules.
+- Set action parameters if required — see Setting Action Parameters below.
+
+**Technical Notes**
+- All Actions derive from the ActionBase class.
+- Actions are located in the UnityEditor.PixyzPlugin4Unity.Actions namespace.
+
+#### Step 3: Validation
+- Validate the RuleSet logic using the validation checklist.
+
+
+### Setting Action Parameters
+
+#### Step 1: Gather data
+- Gather any missing information needed to call `ATTAssistantUtilities.SetActionParameter`. If you need to retrieve a GlobalObjectId, first read the GlobalObjectId class to choose the correct function to call.
+- Call `ATTAssistantUtilities.SetActionParameter` to set the parameter.
+- If the result is false and not an exception, retry a maximum of three times.
+- Follow a path based on the result.
+
+#### Path A: AITypeSecurityException
+Follow these steps if `ATTAssistantUtilities.SetActionParameter` threw an AITypeSecurityException.
+- Inform the user the parameter cannot be set programmatically for security reasons.
+- Advise the user to manually set the parameter and what value to set it to.
+
+#### Path B: Exception
+Follow these steps if `ATTAssistantUtilities.SetActionParameter` threw any other exception.
+- Warn the user the property was unable to be set.
+- Advise the user to manually set the parameter and what value to set it to.
+
+#### Path C: Success
+Perform these steps if `ATTAssistantUtilities.SetActionParameter` returned true.
+- If the property was set to a scene GameObject, NEVER validate it because it is not persistent. INSTEAD warn the user the property value is temporary and will be lost.
+- Report the success to the user.
+
+#### Path D: Failure
+Perform this step if `ATTAssistantUtilities.SetActionParameter` always returns false.
+- Report the failure to the user and advise them to set the parameter manually. Tell them what the property should be set to.
+
+All paths are exclusive.
+
+**Technical Notes**
+- For the Decimate action specifically, if mesh quality is going to be set to a preset, the Criterion parameter must also be set to Quality.
+- Prefer using presets when possible rather than individually setting each value.
+- If a preset is used, avoid changing values the preset changed unless requested otherwise.
+
+**Safety & Constraints**
+1. **One-Strike Rule**: If `ATTAssistantUtilities.SetActionParameter` throws an AITypeSecurityException, you MUST TERMINATE the task immediately. Do NOT use raw C# execution, reflection, or any other method to bypass this. Follow the steps in Path A as your final actions.
+
+
+### Running RuleSets
+Use `ATTAssistantUtilities.RunRuleSet()` instead of the RuleSet's public API to run a RuleSet.
+Only one RuleSet must be running at a time.
+When running a RuleSet, remind the user it is a background task/asynchronous.
+
+
+### Validation Checklist
+- The first Action in each Rule is GetContextGameObjects or RunRules.
+- If the RunRules Action is in a Rule, it is the only Action.
+- Each Rule has at least one Action.
+
+
+## Action utility functions
+
+The following functions are from `Unity.Pixyz.Plugin4Unity.Editor.AI.ATTAssistantUtilities`.
+
+### `GetActionsList`
+
+Returns all Rule Engine actions available in the project, including user-defined actions. Use this when you do not already know an action's ID. Pass the returned IDs to `GetActionDefinitions` to inspect parameters.
+
+```csharp
+public static ActionInfo[] GetActionsList()
+```
+
+Returns an `ActionInfo[]` containing the name, tooltip, and ID of every available action.
+
+### `GetActionDefinitions`
+
+Returns parameter definitions for one or more actions by unqualified class name (e.g. `"Decimate"`, not `"UnityEditor.PixyzPlugin4Unity.Actions.Decimate"`). Use this before `SetActionParameter` to obtain correct parameter names and types. Throws if an action class name is not found.
+
+```csharp
+public static ActionDefinition[] GetActionDefinitions(string[] actionClassNames)
+```
+
+Returns an `ActionDefinition[]`, each containing the action ID and its full parameter list.
+
+### `SetActionParameter`
+
+Sets a `UserParameter` field value on an action within a RuleSet. Use `GetActionDefinitions` first to obtain the correct parameter name. Returns `false` if the field was not found.
+
+```csharp
+public static bool SetActionParameter(string ruleSetPath, int ruleIndex, int ruleblockIndex, string parameterName, string value)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ruleSetPath` | string | required | Project-relative path to the RuleSet asset. |
+| `ruleIndex` | int | required | Zero-based index of the rule containing the action. |
+| `ruleblockIndex` | int | required | Zero-based index of the action block within the rule. |
+| `parameterName` | string | required | The `ParameterPath` value from `GetActionDefinitions`. Must not be fully qualified. |
+| `value` | string | required | String representation of the value to set. For Unity assets or scene objects, provide a `GlobalObjectId` string. For `LayerMask`, use layer names separated by `\|`. |
+
+Returns `true` if the parameter was set and the RuleSet saved, `false` if the field was not found.
+
+## Action utility output types
+
+### `ActionInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Name` | string | Fully qualified class name of the action. |
+| `Description` | string | Tooltip text describing what the action does. |
+| `ID` | int | Unique integer ID. Pass to `GetActionDefinitions` or use as `RuleBlock` action ID. |
+
+### `ActionDefinition`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ID` | int | Unique integer ID of the action. |
+| `Parameters` | `ActionParameterInfo[]` | All configurable `UserParameter` fields on the action. |
+
+### `ActionParameterInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Name` | string | Immediate field name. |
+| `ParameterPath` | string | Full dot-separated path to pass as `parameterName` to `SetActionParameter` (e.g. `"advancedParametersQuality.surfacicTolerance"`). |
+| `Type` | string | Fully qualified type name of the field. |
+| `Description` | string | Tooltip describing the parameter. |
+| `IsConditional` | bool | `true` if this parameter is only visible under certain conditions. |
+| `PossibleEnumValues` | `EnumInfo[]` | Valid values if the parameter is an enum type. |
+| `NestedParameters` | `ActionParameterInfo[]` | Child parameters for struct fields. |
+
+### `EnumInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Label` | string | Name of the enum value. |
+| `Value` | Int64 | Underlying integer value of the enum member. |

package/skills/audio-setup-mixers/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: audio-setup-mixers
+
+This skill has the agent run C# inside the user's open Unity Editor through `unity command script eval`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `script eval`. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed.
+- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `script eval`.

package/skills/audio-setup-mixers/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: audio-setup-mixers
+description: Routes Audio Sources into existing Audio Mixer Groups, classifying each source by what it plays. Use when the user asks about cleaning up mixer assignments, routing audio through a mixer, or which group a sound belongs in.
+---
+# Audio Mixer Setup
+
+Routing an Audio Source to a mixer group is a scene edit that only a running Editor can
+make, so this skill needs a live Editor it can execute C# in. Step 0 establishes that
+before anything else.
+
+**What this skill automates, and what it hands back to you.** Inspecting mixers and
+routing Audio Sources into groups is entirely public Unity API, and that is the tedious
+part — walking dozens of sources and classifying them by what they play. Creating a mixer
+or a group has no public API; it exists only on types Unity does not commit to keeping
+stable. So this skill will not create groups behind your back. It inventories what exists,
+proposes the routing, asks you to add any missing group in the Audio Mixer window, and
+then does all the routing itself.
+
+That is a deliberate limit, not a gap to work around. Do not reach for reflection to
+create groups, and do not hand-edit a `.mixer` file — mixer structure is not safely
+authorable blind.
+
+## Step 0: Confirm you can run C# in the Editor
+
+Every C# step below runs inside a live Editor through the Unity CLI. **The `unity-cli` skill
+owns getting you there** — installing the CLI, confirming a connected Editor, adding the
+project's `com.unity.pipeline` package, telling a genuinely absent Editor apart from one
+stuck in Safe Mode, and discovering the Editor's command catalog. Follow it first; don't
+re-derive any of it here.
+
+Two things it can't know for you:
+
+- **You need `script eval` in particular**, not just a reachable Editor. Confirm it appears in the
+  catalog. Its presence depends on the Pipeline package version, not on the CLI, so a
+  healthy install can still lack it — if it's missing, say so and stop.
+- **Do not fall back to editing `.mixer` files by hand.** Mixer routing is not safely
+  authorable blind, so an unreachable Editor is a stop, not a cue to improvise.
+
+Once `script eval` is available, that is how each C# step below runs.
+
+Run C# through the connected Editor with the `script eval` command. Discover its parameter shape
+from `unity command --format json` rather than assuming one — the inline form is
+`unity command script eval --caller plugin --skill audio-setup-mixers --code '<snippet>'`, and some Pipeline versions also register
+`script eval_file` for running a snippet from a file. **Check the catalog before reaching for
+`script eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.
+
+### Passing C# to `script eval`
+
+`script eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
+compile error rather than a warning:
+
+- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
+  statement and rejects it (`CS0210`).
+- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
+  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
+
+Where a snippet below is written as a file — with usings, for readability, or because it is
+meant to be saved into the project — qualify the types before passing it to `script eval`.
+
+## Step 1: Pre-flight
+If the user hasn't explicitly asked for Audio Mixers, confirm that they want to proceed with setting them up.
+
+Then inventory what already exists with the mixer-inventory snippet in
+[references/api.md](references/api.md), run through the Editor as described in Step 0. That gives
+you every mixer in the project and the group names in each.
+
+It returns a flat list of groups, not the parent/child tree. That is enough to route into, and it
+is all the public API exposes. If the hierarchy matters for the conversation, ask the user to look
+at the Audio Mixer window and describe it — don't reach for the non-public tree API to find out.
+
+**If the project has no mixer at all,** say so and stop rather than improvising one: creating a
+mixer has no public API. Ask the user to create one (Window → Audio → Audio Mixer, then the **+**
+next to Mixers), and pick up from here once it exists.
+
+## Step 2: Find scene references
+Find all Audio Source components, look at their assigned Generator asset names, and generalize a fitting class or category of the sound name, ideally something already existing. 
+Examples for Audio Clip asset names:
+- "FootStep4_Sound" -> Foley
+- "Dialogue_Female_Scene4" -> Vox/Voice/Dialogue
+- "GunShot" -> SFX
+- "Menu_Theme_Variation" -> Music
+
+If the assigned asset isn't descriptive or non-existing, try to look at the GameObject name or potential adjacent MonoBehaviour names.
+Ask to create an Uncategorized group if it seems hard or confidence is low in classifying how an Audio Source is being used.
+
+## Step 3: Agree the group list, and get any missing groups created
+Present the classification from Step 2 as a proposed routing — each Audio Source and the group you
+intend to send it to — and revise it with the user.
+
+**WAIT for the user to respond before proceeding.**
+
+Prefer an existing group when it genuinely covers the category, even if you'd have named it
+differently. But **don't collapse categories that a mixing engineer would keep apart** — Foley is a
+subset of SFX, not another word for it, so a gunshot does not belong in a `Foley` group just because
+one exists. When the existing groups only partly cover your categories, say which ones fit and which
+need a new group, and let the user decide.
+
+For categories with no matching group, you cannot create the group — there is no public API for it.
+Hand it over precisely, naming the mixer and the exact group names, as shown at the end of
+[references/api.md](references/api.md). Then **re-run the inventory snippet to confirm the groups
+exist and check their spelling** before routing. Don't assume the user did it, and don't assume
+they spelled it the way you asked.
+
+## Step 4: Route the Audio Sources
+With the group list settled and confirmed present, assign each Audio Source's output group using the
+routing snippet in [references/api.md](references/api.md). It is public API throughout, and it wraps
+the whole pass in a single undo step so the user can back all of it out at once.
+
+**Key the mapping on the identifier you classified by.** Step 2 reads the clip asset name first and
+only falls back to the GameObject name, so the mapping accepts either — the two are different
+identifiers and keying on the wrong one drops sources.
+
+Three things to report rather than assume:
+
+- **Any `NO SUCH GROUP` entries the snippet returns.** That means a group you expected is not in the
+  mixer — usually a spelling difference. Resolve it with the user, don't silently skip the source.
+- **Any `NOT IN THE MAPPING` entries.** Those are Audio Sources your classification missed. Reporting
+  a successful routing while sources were quietly left unrouted is the worst outcome here, because it
+  reads as success.
+- **The scene was modified, not the mixer asset.** Routing lives on the Audio Source, so it only
+  persists once the scene is saved. Tell the user, and save only with their agreement.
+
+**Volume, effects, and re-parenting are out of scope.** Those live on non-public API. If the user
+asks for them, say the routing is done and point them at the Audio Mixer window for the mix itself.
+
+## References
+See [references/api.md](references/api.md)