diff --git a/skills/unity-pipeline/SECURITY.md b/skills/unity-pipeline/SECURITY.md index 149651f..ad74dc0 100644 --- a/skills/unity-pipeline/SECURITY.md +++ b/skills/unity-pipeline/SECURITY.md @@ -1,17 +1,17 @@ # Security notes: unity-pipeline -This skill has the agent run C# inside a Unity Editor or development Player the user already has running, through `unity command eval`, `eval_file`, `run_script` and `reload_file`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below. +This skill has the agent run C# inside a Unity Editor or development Player the user already has running, through `unity command script eval`, `script eval_file`, `script run` and `script.methodreload reload`. 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 running Editor or development Player through `unity command eval`, `eval_file`, `run_script` and `reload_file` | It only reaches an instance the user started, with the Pipeline package they installed, so it grants nothing they couldn't do in that Editor themselves. No code fetched from a remote source is run. The skill steers ad-hoc code into versioned project files run with `run_script`, and keeps `eval` for one-liners. | +| `SEC_POWER_CAP` | Runs C# in the user's running Editor or development Player through `unity command script eval`, `script eval_file`, `script run` and `script.methodreload reload` | It only reaches an instance the user started, with the Pipeline package they installed, so it grants nothing they couldn't do in that Editor themselves. No code fetched from a remote source is run. The skill steers ad-hoc code into versioned project files run with `script run`, and keeps `script eval` for one-liners. | ## Mitigations - **Only the user's own instances.** Commands go to an Editor or development Player the user is running with the Pipeline package installed. Runtime commands need a development build; release Players have no Pipeline server. - **No remote code.** The agent runs C# it writes for the user's task. Nothing downloaded from outside is executed. -- **Code lives in reviewable files.** Bulk work goes into scripts on disk run with `run_script`, so the user can read and version what ran. `eval` is reserved for short one-liners. -- **Compile-only check.** `run_script --dry_run true` reports diagnostics without loading or running anything. +- **Code lives in reviewable files.** Bulk work goes into scripts on disk run with `script run`, so the user can read and version what ran. `script eval` is reserved for short one-liners. +- **Compile-only check.** `script run --dry_run true` reports diagnostics without loading or running anything. - **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of running C#. diff --git a/skills/unity-pipeline/SKILL.md b/skills/unity-pipeline/SKILL.md index 44e2bab..8ddc283 100644 --- a/skills/unity-pipeline/SKILL.md +++ b/skills/unity-pipeline/SKILL.md @@ -1,14 +1,30 @@ --- name: unity-pipeline -description: Drives a running Unity Editor or dev Player through the unity-pipeline package — recompile, run tests, run C# scripts, method-reload code at runtime and audit the project. Use when an agent must control a live Unity instance or automate its tests. +description: Drives a Unity Editor or dev Player via the unity-pipeline package. Compile, run tests, run C# scripts, method-reload code, check Editor status, enter Play Mode, capture screenshots. Use when an agent must control a running Unity instance. --- # Unity Pipeline (agent control) -Invoke commands with `unity command [args]`. Run `unity command` with no name to -list what an instance exposes. Two servers exist: **Editor** (`7800-7849`, auto-starts with +Invoke commands with `unity command [args]`. Run `unity command` with no +argument to list the command groups an instance exposes, and `unity command ` to list +the commands in one group. Two servers exist: **Editor** (`7800-7849`, auto-starts with the editor) and **Runtime** (`7900-7949`, only in a dev Player build). `unity command --query ` -filters that list by name, description or tag. +filters the listing by name, description or tag. + +## Before you start + +- Create a restore point you can roll back to if your changes fail, such as a commit or a stash of + the project's working tree. +- Read the project's Editor version from `ProjectSettings/ProjectVersion.txt` (`m_EditorVersion`), + because some commands and parameters below differ by Unity version. Use it to pick the matching + steps wherever this skill names a version. +- Do only what's asked. Don't change unrelated assets or files. Avoid long explanations. +- Before you go forward with a workflow or diagnosis, open and read the [Topic map](#topic-map) + page(s) that cover the commands you intend to run. Name the file(s) you read in your response. This + is because your training knowledge about Unity might be out of date, incorrect, or for the wrong + Unity version, and Pipeline command names and parameters change between package versions. +- When a change affects runtime behaviour, add `Debug.Log` lines that you will read back in Play Mode + to verify the behaviour (see [Final checks](#final-checks)). ## 1. Install & verify @@ -16,7 +32,7 @@ filters that list by name, description or tag. unity pipeline install # install into current project (or --project-path) unity pipeline list # confirm the editor instance + server are reachable unity status --until-ready # wait until the editor server is ready -unity command editor_status # confirm the editor server answers +unity command editor status # confirm the editor server answers ``` An Editor that was already open picks up the package only on its next refresh, usually when its @@ -30,28 +46,28 @@ This is the core agent workflow: keep the editor alive, change code, recompile, ```bash # 1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work — # Unity otherwise throttles or stalls update/compile when it isn't the active app. -unity command set_autotick --enable true +unity command editor set_auto_tick --enable true # 2. Edit C# source files on disk normally. # 3. Recompile (async: triggers a domain reload, then poll until done). -unity command recompile -unity command recompile_status # repeat until "completed" or "up_to_date" +unity command script recompile +unity command script recompile_status # repeat until "completed" or "up_to_date" # Tolerate connection errors while the domain reload is in flight — that is expected. -# If recompile_status reports failed=true, read its "errors" array and fix before testing. +# If script recompile_status reports failed=true, read its "errors" array and fix before testing. # 4. (Optional) List available tests without running them. -unity command list_tests --mode editor # mode: all | editor | playmode +unity command test list --mode editor # mode: all | editor | playmode # 5. Run tests (filter to keep it fast). -unity command run_tests --mode editor --filter MyFixture.MyTest +unity command test run --mode editor --filter MyFixture.MyTest ``` -`run_tests` modes: `all` | `editor` | `playmode`. `filter_type`: `testName` | `assembly` | -`category`. For long runs use `--async_tests true` and poll `unity command test_status` -(abort with `unity command cancel_tests`). +`test run` modes: `all` | `editor` | `playmode`. `filter_type`: `testName` | `assembly` | +`category`. For long runs use `--async_tests true` and poll `unity command test status` +(abort with `unity command test cancel`). -> **Known caveat:** when any selected test *fails*, `run_tests` may surface an opaque +> **Known caveat:** when any selected test *fails*, `test run` may surface an opaque > result instead of the failure details. Re-run a narrower `--filter`, or inspect the > editor's Test Runner / logs to get the real failure. @@ -68,11 +84,11 @@ Do not retry an exit 2 unchanged, and do not rewrite a command line on an exit 6 ## 3. Runtime method reload Change gameplay code in a **running** game with no domain reload. The game must be live: -enter Editor Play Mode (`unity command editor_play`) or run a dev Player. The runtime Pipeline driver (enabled via Project Settings > Pipeline > Runtime) auto-discovers tagged methods on `Awake` (no manual +enter Editor Play Mode (`unity command editor.playmode start`) or run a dev Player. The runtime Pipeline driver (enabled via Project Settings > Pipeline > Runtime) auto-discovers tagged methods on `Awake` (no manual registration). Mono only — Editor Play Mode and Mono desktop dev builds, not IL2CPP. The token is auto-injected for local requests. -### `reload_file` +### `script.methodreload reload` Edit the method body directly; no separate file, no boilerplate. @@ -82,32 +98,32 @@ Edit the method body directly; no separate file, no boilerplate. 2. With the game running, edit the method body on disk. 3. Apply (re-run to iterate): ```bash - unity command reload_file --filename Assets/Spinner.cs + unity command script.methodreload reload --filename Assets/Spinner.cs ``` Add `--pdb` to make it debuggable — emits a portable PDB mapped to your source so breakpoints in the original file bind (attach the IDE + enable Editor Attaching; compiles unoptimized): ```bash - unity command reload_file --filename Assets/Spinner.cs --pdb + unity command script.methodreload reload --filename Assets/Spinner.cs --pdb ``` Constraints: `void` instance methods only; **public** members only; debugging requires `--pdb` (the default emits no symbols). -`unity command methodreload_status` shows active overrides. `reload_file` options: `--timeout ` -(default 30000), `--assemblyDir ` (persist DLLs instead of in-memory); -`cleanup_methodreload --assemblyDir ` clears old DLLs. +`unity command script.methodreload status` shows active overrides. `script.methodreload reload` options: +`--timeout ` (default 60), `--assemblyDir ` (persist DLLs instead of in-memory); +`script.methodreload cleanup --assemblyDir ` clears old DLLs. -The CLI consumes `--timeout` itself, in seconds. To pass the package's `--timeout`, put the command's -arguments after `--`: +The CLI's `--timeout` (seconds) is the command's timeout: the Pipeline writes it into the command's +own `timeout` parameter, so there is no separate value to pass: ```bash -unity command reload_file -- --filename Assets/Spinner.cs --timeout 60000 +unity command script.methodreload reload --filename Assets/Spinner.cs --timeout 120 ``` -## 4. Bulk construction: `run_script` (the builder pattern) +## 4. Bulk construction: `script run` (the builder pattern) For bulk work — creating many objects, wiring fields, generating content — put the code in a -**versioned project script** and run a named static entry point with `run_script`. No domain +**versioned project script** and run a named static entry point with `script run`. No domain reload, no code carried through the protocol; iterating costs an in-memory compile (< ~2s), not a 15–20s recompile. @@ -115,74 +131,205 @@ a 15–20s recompile. # 1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload), # e.g. AgentScripts/Build.cs: public static class Build { public static int All() { ... } } # 2. Run it — relative paths resolve against the project root (the parent of Assets/): -unity command run_script --file AgentScripts/Build.cs --entry Build.All +unity command script run --file AgentScripts/Build.cs --entry Build.All # 3. Iterate: edit the file, re-run. Useful extras: -unity command run_script --file AgentScripts/Build.cs --dry_run true # compile-only check: diagnostics, nothing loaded or executed -unity command run_script --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]' +unity command script run --file AgentScripts/Build.cs --dry_run true # compile-only check: diagnostics, nothing loaded or executed +unity command script run --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]' ``` Rules of thumb: -- **Code goes in files on disk via `run_script`; `eval` is for genuinely ad-hoc one-liners.** - Never ship multi-line escaped C# strings through `eval` — write the file, run the entry. +- **Code goes in files on disk via `script run`; `script eval` is for genuinely ad-hoc one-liners.** + Never ship multi-line escaped C# strings through `script eval` — write the file, run the entry. - Compiles see the project's **active editor defines** (`UNITY_EDITOR`, version/platform symbols); `--defines` appends extra symbols on top. - Entry points may be `async Task`/`Task` — they are awaited asynchronously (the editor keeps pumping, so awaits resuming on Unity's context work naturally) and `Task.Result` is returned. - The wait is bounded by `timeout_ms`; on expiry the task keeps running detached. + The wait is bounded by `--timeout` (seconds, default 60); on expiry the task keeps running detached. - Runtime exceptions come back with `file:line` mapped to your source (a source-mapped PDB is always emitted for executing runs; they compile unoptimized). - `--mode hotpatch` instead applies `[MethodReload]` in-place method replacements (delegates to - `reload_file`); `entry`/`args`/`dry_run` are rejected there and `references`/`defines` don't apply. + `script.methodreload reload`); `entry`/`args`/`dry_run` are rejected there and `references`/`defines` don't apply. ## 5. Quick C# eval (Editor or dev Player) -For genuinely ad-hoc one-liners only — anything longer belongs in a file run via `run_script`. -`eval` targets the Editor by default; add `--runtime ` to run it in a dev Player. +For genuinely ad-hoc one-liners only — anything longer belongs in a file run via `script run`. +`script eval` targets the Editor by default; add `--runtime ` to run it in a dev Player. ```bash -unity command eval "return 2 + 2;" -unity command eval "return UnityEngine.Time.timeScale;" --runtime MyGame +unity command script eval "return 2 + 2;" +unity command script eval "return UnityEngine.Time.timeScale;" --runtime MyGame # Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source: -unity command eval_file AgentScripts/Scratch.cs +unity command script eval_file AgentScripts/Scratch.cs ``` -## 6. Project audit (Editor) +## 6. Play Mode vs. Multiplayer Play Mode (MPPM) scenarios -Static-analysis scan via Project Auditor, producing a CSV of issues to fix. Trigger, poll, read. +These are two different things — do not conflate them. + +### Single-player: normal Play Mode (main Editor only) + +```bash +unity command editor.playmode start # enter Play Mode +unity command editor.playmode pause # toggle pause +unity command editor.playmode stop # exit Play Mode +``` + +`editor.playmode start` just flips the main Editor into Play Mode running the **open scene**. It +controls **one** instance and does **not** launch MPPM virtual players, even if the project has +them configured. Use it for single-instance testing and to make runtime code reload live. + +### Multiplayer: Play Mode Scenarios (main Editor + virtual players) + +A **Play Mode Scenario** is an asset (an `OrchestratedScenario`, e.g. +`Assets/Settings/PlayMode/2Players.asset`) describing the main Editor plus one or more virtual +players. Each virtual player (clone) is a **separate Unity project** at +`/Library/VP/` with its **own Library, port, and Pipeline server** — not a second +window of the main Editor. `editor.playmode start` does **not** run a scenario; use the scenario commands +(they drive MPPM's `PlayModeScenarioManager`, which enters Play Mode itself): ```bash -unity command audit # optional: --categories Code,ProjectSetting --output my.csv -unity command audit_status # repeat until terminal status +unity command editor.playmode list_scenarios # discover scenario assets +unity command editor.playmode list_players # players the active scenario declares +unity command editor.playmode set_active_scenario --path Assets/Settings/PlayMode/2Players.asset +unity command editor.playmode start_scenario # run the active scenario +unity command editor.playmode get_scenario_status # live scenario + play-mode state +unity command editor.playmode stop_scenario # stop it ``` -`audit_status` is terminal on `completed` (with `csvPath` + `issueCount`), `failed`, `unavailable`, or -`interrupted` (a domain reload killed the scan — just re-run `audit`). Polling stays responsive while a -Code-category scan compiles assemblies and holds the main thread. One scan at a time: a second `audit` -returns `busy`. There is no cancel — stop polling to abandon a scan. +Authoring the asset (Edit Mode): -CSV columns: `Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation` -(diagnostics only, so every row is something to fix; `Recommendation` says how). +```bash +unity command editor.playmode create_scenario --name MyScenario # auto-adds the Main Editor player +unity command editor.playmode add_player --path Assets/Settings/PlayMode/MyScenario.asset --type clone --name "Player 2" +unity command editor.playmode remove_player --id --path Assets/Settings/PlayMode/MyScenario.asset --confirm true +``` + +For `remove_player --id`, check the Editor version you read in [Before you start](#before-you-start): +on 6000.5 and later pass the player's GUID; on 6000.3 and 6000.4 pass the player's name. + +The `editor.playmode` scenario commands need **Unity 6000.3+** *and* the `com.unity.multiplayer.playmode` +package, so check the Editor version and `Packages/manifest.json` first. Without both they are compiled out and calling one fails as an unknown command, so run +`unity command editor.playmode` and check that `start_scenario` and the other scenario commands are listed +before using them. The group itself always exists: `editor.playmode list_instances` needs neither +and always works. You may only `editor.playmode set_active_scenario` while state is **Idle**. -> **Requires Project Auditor plus its rules.** `unavailable` means the Editor has no Project Auditor, -> or it has no analysis rules — in a built-in-module Editor the rules live in the separate -> `com.unity.project-auditor-rules` package (`unity command package_add --identifier -> com.unity.project-auditor-rules --confirm true`). Read the `message` field; the command never reports -> an empty `completed` scan that would look like a clean project. +Player editors launch **asynchronously**, so after `editor.playmode start_scenario` poll +`editor.playmode get_scenario_status`. Its `players` array has one entry per player the scenario declares — not +MPPM's fixed four slots — and each entry carries both `state` (`NotLaunched` / `Launching` / +`Launched` / `UnexpectedlyStopped`) and, once that player's Editor is up, `reachable: true` with the +`port` and `projectPath` you need to drive it. Wait for `reachable`, then address it with +`--project-path`. Watch `state` to tell a slow launch (`Launching`) from a dead one +(`UnexpectedlyStopped`) — a missing descriptor alone cannot distinguish those. + +### Discovering and driving the clones + +The CLI folds a project's own clones into its main Editor, so a running scenario adds no +ambiguity by itself. But with another Unity project open, `unity command` with no `--project-path` +picks the Editor whose project contains the current directory (and fails as ambiguous outside +both). When more than one project is open, pass `--project-path ` to the main Editor +commands above. Each clone runs its own server, so address one by its project directory: + +```bash +# List every running instance (main + clones): role, port, pid, vpId, projectPath +unity command editor.playmode list_instances + +# Talk to a clone directly, using the projectPath that listed it +unity command --project-path /Library/VP/ editor status +# Each clone is its own Editor: keep it ticking before running tests on it +unity command --project-path /Library/VP/ editor set_auto_tick --enable true +unity command --project-path /Library/VP/ test run --mode playmode +``` + +`unity pipeline list` also reports clones, named by player ("Player 2") against the project they're +playing. There is no forwarding command — talk to the clone. That way you get its full command +surface and its own status, and nothing queues behind the main Editor. + +## 7. Screen capture (Editor) + +Capture a view to a PNG to check a visual result. + +```bash +unity command capture screenshot --view game # or --view scene; returns the PNG path +unity command capture game_view --source screen --save_path Screenshots/hud.png # what the Game window shows, incl. overlay UI +unity command capture scene_view --max_resolution 512 # inline base64 image, longest edge capped +``` + +`capture game_view` and `capture scene_view` return the image inline as base64 unless `--save_path` is +set; add `--include_inline_image true` to get both. `capture game_view --source camera --camera ` +renders one camera instead and misses Screen Space - Overlay UI. Without `--output`, `capture screenshot` +writes under `/Temp/pipeline-screenshots/`. If the Editor version is 6000.7 or later, +`capture editor_element` and `capture runtime_element` capture a single UI Toolkit element by +`--selector`. On earlier versions these commands don't exist, so capture the whole view instead. ## Gotchas -- **`set_autotick` first.** Without it, recompile and tests can hang while the editor is +- **`editor set_auto_tick` first.** Without it, recompile and tests can hang while the editor is unfocused. The package's watchdog relies on the tick loop staying alive. - **A stuck command may mean a modal dialog is open**, not a hang — a dialog blocks the main - thread until dismissed. If a command runs long, check `unity command editor_status` (answers + thread until dismissed. If a command runs long, check `unity command editor status` (answers instantly even when blocked); `status: "blocked_by_dialog"` means stop retrying and tell the human what's blocking (its `dialog.title`/`message`/`buttons`) — it can't be clicked over CLI. -- **Method reload needs the game running.** `reload_file` applies to a live - game — enter Editor Play Mode (`unity command editor_play`) first, or run a dev Player. -- **Player-only commands need a dev Player.** `log`, `set_timescale`, `runtime_status`, etc. hit +- **Method reload needs the game running.** `script.methodreload reload` applies to a live + game — enter Editor Play Mode (`unity command editor.playmode start`) first, or run a dev Player. +- **`editor.playmode start` ≠ a scenario.** It runs only the main Editor's open scene; it never + launches MPPM virtual players. For a multiplayer session set/start a Play Mode Scenario with + `editor.playmode set_active_scenario` + `editor.playmode start_scenario` (see §6) — never drive a scenario with + `editor.playmode start` (it fights MPPM's play-mode guard) — then drive the clones with `editor.playmode list_instances` + and `--project-path`. +- **Player-only commands need a dev Player.** `console write`, `runtime set_time_scale`, `runtime status`, etc. hit the Runtime server, which does not run in the Editor. -- **Async commands poll.** `recompile`→`recompile_status`, `run_tests --async_tests`→ - `test_status`. Never assume completion from the trigger call's response. +- **Async commands poll.** `script recompile`→`script recompile_status`, `test run --async_tests`→ + `test status`. Never assume completion from the trigger call's response. - **Target a specific instance** when more than one is running: `--project-path ` selects an Editor, `--runtime ` or `--runtime-path ` selects a dev Player. + +## Final checks + +1. Check that the project has zero console errors: + ```bash + unity command console status # groundTruth.consoleErrors must be 0, compilationFailed false + unity command console get --level error # read any errors it reports + ``` +2. If you changed runtime behaviour, enter Play Mode (`unity command editor.playmode start`), exercise + the change, and read back the `Debug.Log` lines you added with `unity command console get`. Confirm + they show the fix works, then stop Play Mode and remove those lines unless the user wants them kept. +3. If the fix doesn't work, go back and reread the relevant [Topic map](#topic-map) pages before you + try again, rather than retrying from memory. + +## Final report + +Give the user a short summary: + +- What you did: the commands you ran, the files you changed, and the test or check results. +- Side effects you left behind: Play Mode still running, `editor set_auto_tick` still enabled, a + scenario left active, files written under `AgentScripts/` or `Screenshots/`, method reload overrides + still applied. +- Follow-ups the user needs to do: anything blocked by a modal dialog, failures you could not fix, + and the restore point to roll back to. + +## Topic map + +The Pipeline package ships its documentation in its `Documentation~` folder. For a registry install +that is `/Library/PackageCache/com.unity.pipeline@*/Documentation~/`; the same pages are +published at `https://docs.unity3d.com/Packages/com.unity.pipeline@/`. Only read what you need. + +Prefer the local `Documentation~` copy, because it matches the installed package exactly. If you +use the live pages, prefer fetching the page directly (for example `WebFetch`) over searching (for +example `WebSearch`) — faster and lands on the exact reference. Only fetch what you need, and only +search if you don't have the exact URL. Replace `` with the following before fetching: + +- **Package on docs.unity3d.com**: The `com.unity.pipeline` major and minor version from + `Packages/packages-lock.json`, eg `@0.9`. + +| Topic | Page | +|-------|------| +| Connecting to an Editor or Player, ports, `--project-path` | `connectivity.md` | +| Dev Player and Runtime server setup | `runtime-setup.md` | +| Method reload (`[MethodReload]`, `script.methodreload`) | `method-reload.md` | +| `script run`, `script eval`, `script recompile` | `commands/scripts.md` | +| Compiling and running tests | `commands/build-and-compilation.md` | +| `editor status`, `editor set_auto_tick`, modal dialogs | `commands/editor-lifecycle-and-observability.md` | +| Play Mode scenarios, virtual players, clones | `commands/multiplayer-play-mode.md` | +| Screen capture | `commands/capture.md` | +| `console get` / `console status`, Runtime commands | `commands/runtime.md` |