Control a running Unity Editor via a file-polling command bridge. No window clicking, no second editor process.
Protocol
Agent writes <project>/UnityRemote.txt (one command per line, # comments allowed). Editor polls every 0.5 s, executes lines, writes <project>/UnityRemote.result.txt, deletes the command file. Commands are skipped while compiling/updating — wait, never resend.
Full command list with argument formats: references/commands.md.
Setup
- Detect bridge: check
<project>/Assets/UnityRemote.cs. Some projects ship their own variant — grepAssets/**/Editor/*.csfor a command-file poller before deploying. - Deploy if missing: copy
assets/UnityRemote.cs(andassets/UnityRemoteRecorder.csforrecord) intoAssets/, then runrefreshto import + compile. An unfocused editor defers asset import — ifrefreshtimes out, focus the editor window, then retry. Confirm withping. - Send commands:
scripts/unity_cmd.sh <project-root> "ping" # single command
scripts/unity_cmd.sh <project-root> -t 600 "refresh" "ping" # batch with timeout
Verification Loop (after code change)
U=<skill-dir>/scripts/unity_cmd.sh
$U "$P" --compile # refresh → busy-poll until idle → console tail
# 'error CS' = fail; 'console empty' = clean
$U "$P" "play" # enter Play mode
sleep 8 # let systems tick
$U "$P" "state" # playing? MonoBehaviours present? (objs=...)
$U "$P" "errors 50" # runtime exceptions
$U "$P" "stop"
Critical: never trust refresh+ping as a compile gate. refresh returns before recompile starts — same-batch ping/errors answer from the OLD assembly. Use --compile (busy-poll + gen-change check).
Visual Verification
screenshot [relpath] renders the main camera synchronously → PNG at <project>/<relpath>. Captures the Game camera, not editor chrome.
record [sec] [fps] enters Play mode, captures frames → Recordings/shot/frame_####.png + done.txt. Requires assets/UnityRemoteRecorder.cs deployed.
Use layout for window rects + pixelsPerPoint if cropping is needed. OS-level screen capture is unreliable — only use it for editor chrome itself.
Telemetry pattern: errors is the only data channel out of Play mode. Make runtime code log structured single-line events (e.g., Debug.Log($"GAME round={r} score={s}")), then grep errors output. Pass large n (50+) to avoid early entries scrolling out.
Key Rules
- One editor per project — the running editor owns the Library lock. Never launch
-batchmodeon the same project. - Play mode = domain reload — assemblies reload; bridge re-inits. Always
--compilegreen first. - Bridge is editor-only — never shipped in builds. Commit it or
.gitignoreper user preference.
For occlusion caveats, timeout behavior, domain-reload edge cases, and troubleshooting: see references/caveats.md.