/unity-pipeline

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.

Unity Pipeline (agent control)

Invoke commands with `unity command <name> [args]`. Run `unity command` with no name to list what an instance exposes. Two servers exist: **Editor** (`7800-7849`, auto-starts with the editor) and **Runtime** (`7900-7949`, only in a dev Player build). `unity command --query <term>` filters that list by name, description or tag.

1. Install & verify

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

An Editor that was already open picks up the package only on its next refresh, usually when its window regains focus. Until then `unity status` reports `STATUS_PIPELINE_LOAD_PENDING`; if that persists, ask the user to switch to the Unity Editor window, then re-run `unity status --until-ready`.

2. Autonomous edit loop (Editor)

This is the core agent workflow: keep the editor alive, change code, recompile, test.

# 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

# 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"
#   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.

# 4. (Optional) List available tests without running them.
unity command list_tests --mode editor            # mode: all | editor | playmode

# 5. Run tests (filter to keep it fast).
unity command run_tests --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`).

> **Known caveat:** when any selected test *fails*, `run_tests` 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.

**Reading exit codes.** They separate "rewrite the invocation" from "the Editor failed", which is the distinction this loop depends on:

| Exit | Meaning | What to do | |------|---------|------------| | `2` | Bad arguments — a misspelled flag, a wrong type, too many positionals. Nothing ran. | Fix the command line and retry. The error names the problem and often suggests the right flag. | | `6` | The command ran and failed, or no Editor could be reached. | Read the error. If it says no Pipeline instance was found, the Editor isn't reachable: wait with `unity status --until-ready` (or check `unity pipeline list` for Safe Mode), then retry. Otherwise retrying the same invocation will not help. |

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 registration). Mono only — Editor Play Mode and Mono desktop dev builds, not IL2CPP. The token is auto-injected for local requests.

`reload_file`

Edit the method body directly; no separate file, no boilerplate.

1. **Before entering Play Mode**, tag the method `[MethodReload]` on the MonoBehaviour and recompile. The reload hook is compiled into the method, so tagging it while the game runs has no effect: exit Play Mode, recompile, and enter it again. 2. With the game running, edit the method body on disk. 3. Apply (re-run to iterate):

   unity command reload_file --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):

   unity command reload_file --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 <ms>` (default 30000), `--assemblyDir <dir>` (persist DLLs instead of in-memory); `cleanup_methodreload --assemblyDir <dir>` clears old DLLs.

The CLI consumes `--timeout` itself, in seconds. To pass the package's `--timeout`, put the command's arguments after `--`:

unity command reload_file -- --filename Assets/Spinner.cs --timeout 60000

4. Bulk construction: `run_script` (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 reload, no code carried through the protocol; iterating costs an in-memory compile (< ~2s), not 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/)