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, a project may lack the Locus package, named-pipe discovery is needed, C# must be executed, or Unity scripts must be recompiled.

Locus Unity Bridge

Use the bundled PowerShell client instead of rewriting named-pipe code. Locus uses UTF-8 JSON Lines and may emit events before a response; the client waits for the envelope whose reply_to matches its request ID.

Safety boundary

execute_code has arbitrary Unity Editor authority. Use it only for the project and task the user authorized.

Do not install/copy the Locus package, create its marker, launch/close Unity, or modify a project merely to make the bridge connect. Diagnose first and ask for authorization if setup changes are required.

Workflow

1. Resolve the script relative to this skill:

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

2. Probe the target project before any Unity operation:

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

3. Read the returned Status:

   Status	Meaning and next action
   connected	Use execute, send, or recompile.
   package_missing	Locus is not installed. Report the expected package Packages/com.farlocus.locus; request permission before installation.
   package_invalid	A candidate folder exists without Editor/Locus.Editor.asmdef; report the incomplete path.
   bridge_not_enabled	Package exists, but no marker or reachable computed pipe exists. Ask the user to enable/connect Locus for this project.
   editor_unreachable	A marker exists, but its pipe is unavailable. Verify that the matching project is open in Unity and Locus is active.

The probe supports the canonical package plus legacy Assets/Locus and Assets/Plugins/Locus layouts. It also handles LOCUS_UNITY_NATIVE_BRIDGE=1, where no marker may exist but the computed pipe is live.

Commands

Execute multi-line C# from a file. Use print(...) or printJson(...) to return data:

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

Example snippet:

print(UnityEngine.SceneManagement.SceneManager.GetActiveScene().path);

Send a protocol message:

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

Request compilation and wait across domain reload:

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

All successful commands print JSON. A failed transport or Unity response exits nonzero and preserves the useful error text.

Common mistakes

• Do not treat the first pipe line as the response; unsolicited unity-editor-update events have no matching reply_to.
• Do not run against the Locus source checkout when the requested Unity project is elsewhere.
• Do not assume Unity MCP is required; this skill talks directly to Locus.
• Do not infer package installation from a running Unity process; trust probe.