Locus Unity Bridge

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. Use it only for the project and task the user authorized. Do not install 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.

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'

The probe recognizes canonical and legacy package layouts, plus a live computed pipe when LOCUS_UNITY_NATIVE_BRIDGE=1 is enabled.

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

property_tree_write and property_tree_apply modify serialized data; never use them as diagnostics. 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}

3. Use a top-level operation

Asset images

Do not send asset_thumbnail or asset_preview_render directly: their PNG responses contain Base64. These commands decode it locally and return only a path plus image metadata. Use -OutputDirectory to choose a local destination; otherwise the client uses its local temporary folder.

# Any asset under Assets/ or Packages/; -MaxSize is 64-512 (default 192).
& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command thumbnail -ProjectPath 'E:\Source\SomeUnityProject' `
    -AssetPath 'Assets\Art\Icon.png' -MaxSize 192

# Prefab or model only; width/height are 96-640.
& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command render-preview -ProjectPath 'E:\Source\SomeUnityProject' `
    -AssetPath 'Assets\Props\Chair.prefab' `
    -PreviewWidth 320 -PreviewHeight 220 -Yaw 25 -Pitch -12 -Distance 1.15

Use -PanX, -PanY, and -PanZ only when reframing the model preview is necessary. Rendering does not modify the source asset.

Execute authorized C# or recompile

Use execute only when the curated operations do not answer the task. Prefer a multi-line -CodeFile and print(...) or printJson(...) for returned data.

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command execute -ProjectPath 'E:\Source\SomeUnityProject' `
    -CodeFile 'C:\Temp\inspect-scene.cs' -TimeoutSeconds 30

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command recompile -ProjectPath 'E:\Source\SomeUnityProject' `
    -TimeoutSeconds 10 -RecompileTimeoutSeconds 120

Transport notes

• The pipe can emit unity-editor-update events before the matching response; the client already waits for the envelope whose reply_to matches its request.
• Do not target the Locus source checkout when the requested Unity project is elsewhere.
• Do not assume Unity MCP is required; this skill uses Locus directly.