/locus-unity-bridge

name: locus-unity-bridge
description: Use when an agent needs to inspect or control a real Unity Editor through Locus, especially when Unity MCP is unavailable, named-pipe discovery is needed, C# must be executed, or Unity scripts must be recompiled.

Locus Unity Bridge

Use the bundled PowerShell client to inspect or control a real Unity Editor. Do not rewrite its named-pipe client. Always pass the exact Unity root to `-ProjectPath`; it identifies the bridge connection.

Safety

`execute` can run arbitrary C# in Unity, and the property-tree write messages (`property_tree_write`, `property_tree_apply`) mutate the user's project. Use any of them only for the project and task the user authorized, and prefer the read path when the task is inspection. A connected bridge requires Locus to already be installed and enabled in the target project. Do not install or repair Locus, create its marker, launch or close Unity, or modify a project merely to connect the bridge.

Command map

The client has six top-level commands. `send` is a transport command: its `-MessageType` selects a curated Locus protocol message. Do not treat a message type as a value for `-Command`.

| Top-level `-Command` | Use | |---|---| | `probe` | Check package and bridge connectivity before every Unity operation. | | `send` | Send one approved protocol message listed below. | | `thumbnail` | Save an asset thumbnail as a local PNG. | | `render-preview` | Save a Prefab/model preview as a local PNG. | | `execute` | Run an authorized C# snippet. | | `recompile` | Request compilation and wait through domain reload. |

All commands except `recompile` use `-TimeoutSeconds` (default `10`, range `1`–`600`) for their final pipe response. Increase it only for an operation that is expected to take longer. `recompile` instead uses its dedicated timeout options below.

Resolve the client once:

$locusBridge = Join-Path $env:USERPROFILE '.agents\skills\locus-unity-bridge\scripts\locus-unity.ps1'

1. Probe first

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command probe -ProjectPath 'E:\Source\SomeUnityProject'

| Status | Next action | |---|---| | `connected` | Continue with an operation. | | `package_missing` | Report the expected `Packages/com.farlocus.locus`; installation is outside this skill. | | `package_invalid` | Report the incomplete installation path; repair is outside this skill. | | `bridge_not_enabled` | Ask the user to enable/connect Locus for this project. | | `editor_unreachable` | Verify that the matching project is open in Unity and Locus is active. |

The probe recognizes canonical and legacy package layouts. It uses a bridge marker when present, otherwise it computes the project-specific pipe name.

2. Inspect with `send`

Use this shape for all entries in the table. Successful responses are JSON; parse a nested JSON payload from the envelope's `message` field when noted.

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command send -ProjectPath 'E:\Source\SomeUnityProject' `
    -MessageType <message-type> -Message '<json-or-empty-string>'

| Need | `-MessageType` | `-Message` / guidance | |---|---|---| | Editor status and active scene | `status` | Empty string. | | Console errors or warnings | `unity_get_console_log` | `{"levels":["error","warn"],"limit":20}`; raise `limit` only when needed. | | Known serialized target | `property_tree_read` | Read [Property Tree requests](references/property-tree.md). | | Locate serialized properties | `property_tree_discover` | Read [Property Tree requests](references/property-tree.md). | | Find objects/fields in `.unity` or `.prefab` | `search_yaml` | Read [Scene and Prefab search](references/scene-prefab-search.md). | | Inspect one found scene/Prefab object | `read_yaml` | Use the `object_path` from search; see the same reference. | | Capture Game, Scene, or Editor window | `capture_viewport` | JSON below. |

`get_console_text` is a large compatibility snapshot, not a default query.

For `capture_viewport`, set `target` to `game`, `scene`, or `editor_window`. `maxLongEdge` defaults to `1280`, accepts `0` for source size, and is capped at `8192`; `editor_window` optionally accepts `windowTitle`. The response returns a PNG path under `Library/Locus/Screenshots/`; report it and do not delete it.

{"target":"game","maxLongEdge":1280}

Writing properties (mutating — confirm authorization first)

Everything above is read-only. Unity's property write path is a separate, explicitly authorized step:

| Need | `-MessageType` | `-Message` | |---|---|---| | Set one existing serialized property | `property_tree_write` | `{"target":{"kind":"selection","propertyPath":"m_Speed"},"valueJson":"12.5"}` | | Commit several writes together | `property_tree_apply` | `{"writes":[<write request>, ...]}` |

A write reuses the read targets (`selection`, `asset`, `scriptableobject`, `material`, `gameobject`, `component`) plus the `target.propertyPath` reported by a preceding read or discover. `valueJson` is the JSON-encoded value. `mode: "preview"` applies a transient drag preview instead of committing; omit `mode` for a real commit. `bindingId` is only echoed back and may be omitted.

`property_tree_write` records Undo, marks the object and scene dirty, and returns a fresh read plus a `beforeSnapshot`. **It does not save the asset** — `live` writes keep Property Tree commit semantics, so the asset can still be waiting for Unity to save it. Never report a write as persisted without a separate save step, and say so when the file is still dirty.

Writes that must be persisted, revision-checked, or correct against Prefab inheritance use a different surface: `asset_api` (transaction id, `expected_revision`, `dependencies`, `persist: "disk"`, array operations, batches up to 256 files / 10,000 operations). That is the transactional YAML backend, not a raw file writer; trea