unity-pipeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity Pipeline (agent control)

Unity Pipeline（Agent 控制）

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.

使用

unity command <name> [args]

调用命令。不带名称运行

unity command

可列出实例暴露的所有命令。存在两种服务器：Editor（端口

7800-7849

，随编辑器自动启动）和 Runtime（端口

7900-7949

，仅在开发版 Player 构建中存在）。

unity command --query <term>

可按名称、描述或标签过滤该列表。

1. Install & verify

1. 安装与验证

bash

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

bash

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

已打开的 Editor 仅在下次刷新时（通常是窗口重新获得焦点时）才会加载该包。在此之前，

unity status

会返回

STATUS_PIPELINE_LOAD_PENDING

；如果该状态持续存在，请让用户切换到 Unity Editor 窗口，然后重新运行

unity status --until-ready

。

2. Autonomous edit loop (Editor)

2. 自主编辑循环（Editor）

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

bash

undefined

这是 Agent 的核心工作流：保持编辑器运行、修改代码、重新编译、测试。

bash

undefined

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.

unity command run_tests --mode editor --filter MyFixture.MyTest


`run_tests` 的模式包括：`all` | `editor` | `playmode`。`filter_type` 可选值：`testName` | `assembly` | `category`。对于长时间运行的测试，可使用 `--async_tests true` 并轮询 `unity command test_status`（使用 `unity command cancel_tests` 中止）。

> **已知注意事项：** 当任意选中的测试*失败*时，`run_tests` 可能返回模糊的结果而非失败详情。请使用更窄的 `--filter` 重新运行，或检查编辑器的 Test Runner / 日志以获取真实的失败原因。

**读取退出码。** 退出码区分了「需要修改调用方式」和「Editor 本身失败」，这是该循环依赖的关键区别：

| 退出码 | 含义 | 处理方式 |
|------|---------|------------|
| `2` | 参数错误——标志拼写错误、类型错误或位置参数过多，命令未执行。 | 修复命令行后重试。错误信息会指出问题，通常还会建议正确的标志。 |
| `6` | 命令已执行但失败，或无法连接到 Editor。 | 查看错误信息。如果提示未找到 Pipeline 实例，说明 Editor 不可达：使用 `unity status --until-ready` 等待（或检查 `unity pipeline list` 是否为安全模式），然后重试。其他情况下重试相同命令不会有帮助。 |

不要在未修改的情况下重试退出码为 2 的命令，也不要在退出码为 6 时重写命令行。

3. Runtime method reload

3. 运行时方法重载

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.

无需域重载即可修改运行中游戏的玩法代码。游戏必须处于运行状态：进入 Editor Play Mode（

unity command editor_play

）或运行开发版 Player。运行时 Pipeline 驱动（通过 Project Settings > Pipeline > Runtime 启用）会在

Awake

时自动发现带标记的方法（无需手动注册）。仅支持 Mono——适用于 Editor Play Mode 和 Mono 桌面开发版构建，不支持 IL2CPP。本地请求会自动注入令牌。

reload_file

reload_file

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

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.
With the game running, edit the method body on disk.
Apply (re-run to iterate):
bash
```
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):
bash
```
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

--

bash

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

直接编辑方法体；无需单独文件，无需样板代码。

进入 Play Mode 之前，在 MonoBehaviour 上为方法添加
```
[MethodReload]
```
标记并重新编译。重载钩子会被编译到方法中，因此在游戏运行时添加标记不会生效：请退出 Play Mode，重新编译后再重新进入。
游戏运行时，在磁盘上编辑方法体。
应用更改（可重复运行以迭代）：
bash
```
unity command reload_file --filename Assets/Spinner.cs
```
添加
```
--pdb
```
可使其支持调试——会生成映射到源代码的可移植 PDB，这样原始文件中的断点就能绑定（需附加 IDE 并启用 Editor Attaching；以非优化模式编译）：
bash
```
unity command reload_file --filename Assets/Spinner.cs --pdb
```

限制：仅支持

void

实例方法；仅支持public 成员；调试需要

--pdb

（默认不生成符号）。

unity command methodreload_status

可显示当前生效的重载。

reload_file

选项：

--timeout <ms>

（默认 30000）、

--assemblyDir <dir>

（将 DLL 持久化而非存于内存中）；

cleanup_methodreload --assemblyDir <dir>

可清理旧 DLL。

CLI 自身会解析

--timeout

参数（单位为秒）。要传递包本身的

--timeout

参数，请将命令参数放在

--

之后：

bash

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

4. Bulk construction:

run_script

(the builder pattern)

4. 批量构建：

run_script

（构建器模式）

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.

bash

undefined

对于批量工作——创建大量对象、配置字段、生成内容——请将代码放在版本化的项目脚本中，并使用

run_script

运行指定的静态入口点。无需域重载，无需通过协议传输代码；迭代仅需一次内存编译（< 约2秒），而非 15-20 秒的完整重新编译。

bash

undefined

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

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"]'


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.
- 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<T>` — they are awaited asynchronously (the editor keeps
  pumping, so awaits resuming on Unity's context work naturally) and `Task<T>.Result` is returned.
  The wait is bounded by `timeout_ms`; 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.


经验法则：

- **代码应通过 `run_script` 放在磁盘文件中；`eval` 仅用于真正临时的单行代码。** 永远不要通过 `eval` 传递多行转义的 C# 字符串——请写入文件，再运行入口点。
- 编译会使用项目的**当前编辑器定义符号**（`UNITY_EDITOR`、版本/平台符号）；`--defines` 可在此基础上追加额外符号。
- 入口点可以是 `async Task`/`Task<T>`——它们会被异步等待（编辑器会持续处理消息，因此在 Unity 上下文中恢复的 await 会自然工作），并返回 `Task<T>.Result`。等待时间受 `timeout_ms` 限制；超时后任务会继续在后台运行。
- 运行时异常会返回映射到源代码的 `文件:行号`（执行运行时始终会生成带源映射的 PDB；以非优化模式编译）。
- `--mode hotpatch` 则会应用 `[MethodReload]` 原地方法替换（委托给 `reload_file`）；该模式下不支持 `entry`/`args`/`dry_run`，且 `references`/`defines` 不生效。

5. Quick C# eval (Editor or dev Player)

5. 快速 C# 求值（Editor 或开发版 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 <process name>

to run it in a dev Player.

bash

unity command eval "return 2 + 2;"
unity command eval "return UnityEngine.Time.timeScale;" --runtime MyGame

仅用于真正临时的单行代码——更长的代码应放在文件中通过

run_script

运行。

eval

默认目标为 Editor；添加

--runtime <进程名>

可在开发版 Player 中运行。

bash

unity command eval "return 2 + 2;"
unity command 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

undefined

unity command eval_file AgentScripts/Scratch.cs

undefined

6. Project audit (Editor)

6. 项目审计（Editor）

Static-analysis scan via Project Auditor, producing a CSV of issues to fix. Trigger, poll, read.

bash

unity command audit                              # optional: --categories Code,ProjectSetting --output my.csv
unity command audit_status                       # repeat until terminal status

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.

CSV columns:

Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation

(diagnostics only, so every row is something to fix;

Recommendation

says how).

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.

通过 Project Auditor 进行静态分析扫描，生成待修复问题的 CSV 文件。流程为：触发、轮询、读取。

bash

unity command audit                              # optional: --categories Code,ProjectSetting --output my.csv
unity command audit_status                       # repeat until terminal status

audit_status

的终态包括

completed

（附带

csvPath

和

issueCount

）、

failed

、

unavailable

或

interrupted

（域重载终止了扫描——只需重新运行

audit

）。当代码类别的扫描编译程序集并阻塞主线程时，轮询仍能保持响应。每次只能运行一个扫描：第二次调用

audit

会返回

busy

。没有取消功能——停止轮询即可放弃扫描。

CSV 列包括：

Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation

（仅为诊断结果，因此每一行都是需要修复的问题；

Recommendation

说明修复方法）。

需要 Project Auditor 及其规则。
unavailable
表示 Editor 未安装 Project Auditor，或没有分析规则——在内置模块的 Editor 中，规则位于单独的
com.unity.project-auditor-rules
包中（可通过
unity command package_add --identifier com.unity.project-auditor-rules --confirm true
安装）。请查看
message
字段；该命令永远不会返回空的
completed
扫描结果（即看起来项目没有问题的结果）。

Gotchas

注意事项

set_autotick
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 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 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.
Target a specific instance when more than one is running:
```
--project-path <path>
```
selects an Editor,
```
--runtime <process name>
```
or
```
--runtime-path <port file>
```
selects a dev Player.

先执行
set_autotick
。没有它，当编辑器失去焦点时，重新编译和测试可能会挂起。该包的看门狗依赖于 tick 循环保持运行。
命令卡住可能是因为打开了模态对话框，而非真的挂起——对话框会阻塞主线程直到被关闭。如果命令运行时间过长，请检查
```
unity command editor_status
```
（即使被阻塞也会立即响应）；如果
```
status: "blocked_by_dialog"
```
，请停止重试并告知用户阻塞原因（对话框的
```
title
```
/
```
message
```
/
```
buttons
```
）——无法通过 CLI 点击对话框。
方法重载需要游戏处于运行状态。
```
reload_file
```
适用于运行中的游戏——请先进入 Editor Play Mode（
```
unity command editor_play
```
），或运行开发版 Player。
仅 Player 可用的命令需要开发版 Player。
```
log
```
、
```
set_timescale
```
、
```
runtime_status
```
等命令会访问 Runtime 服务器，而该服务器不会在 Editor 中运行。
异步命令需要轮询。 例如
```
recompile
```
→
```
recompile_status
```
、
```
run_tests --async_tests
```
→
```
test_status
```
。永远不要仅根据触发调用的响应就认为操作已完成。
当运行多个实例时，请指定目标实例：
```
--project-path <路径>
```
选择 Editor，
```
--runtime <进程名>
```
或
```
--runtime-path <端口文件路径>
```
选择开发版 Player。

unity-pipeline

Original

Translation

Unity Pipeline (agent control)

Unity Pipeline（Agent 控制）

1. Install & verify

1. 安装与验证

2. Autonomous edit loop (Editor)

2. 自主编辑循环（Editor）

1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work —

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 otherwise throttles or stalls update/compile when it isn't the active app.

2. Edit C# source files on disk normally.

2. Edit C# source files on disk normally.

3. Recompile (async: triggers a domain reload, then poll until done).

3. Recompile (async: triggers a domain reload, then poll until done).

Tolerate connection errors while the domain reload is in flight — that is expected.

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 recompile_status reports failed=true, read its "errors" array and fix before testing.

4. (Optional) List available tests without running them.

4. (Optional) List available tests without running them.

5. Run tests (filter to keep it fast).

5. Run tests (filter to keep it fast).

3. Runtime method reload

3. 运行时方法重载

reload_file

reload_file

4. Bulk construction: run_script (the builder pattern)

4. 批量构建：run_script（构建器模式）

1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload),

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() { ... } }

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/):

2. Run it — relative paths resolve against the project root (the parent of Assets/):

3. Iterate: edit the file, re-run. Useful extras:

3. Iterate: edit the file, re-run. Useful extras:

5. Quick C# eval (Editor or dev Player)

5. 快速 C# 求值（Editor 或开发版 Player）

Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source:

Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source:

6. Project audit (Editor)

6. 项目审计（Editor）

Gotchas

注意事项

`reload_file`

`reload_file`

4. Bulk construction:
`run_script`
(the builder pattern)

4. 批量构建：
`run_script`
（构建器模式）