escalate_via_click tool. Write op. Command-line fallback to real input.

When lua_eval command-line operations (e.g. PROJECT_RUNTIME.global.ui:open(uid)) don't carry real data — surfaced by repeated verify_assertions failures under the same goal (verdict.escalation.should_escalate) — the agent should NOT keep forcing the lua path. This tool atomically:

1. Restores the lua op by running the caller-supplied undo_lua (the inverse operation, e.g. PROJECT_RUNTIME.global.ui:close(uid)).

2. Re-enters through REAL simulated input by clicking the true entry-point button (delegates to simulate_click).

3. On a landed click, clears the escalation gate for goal and soft-grounds the lua runway (entering the real environment is a reality-touching act).

If the undo fails, the click is NOT attempted (never stack a click on an un-restored dirty state) and the gate is left intact. If the click misses, the gate is left intact so the agent can retry with a different locator / mode.

PlayMode-only (lua VM + simulate both require Play Mode).

USE WHEN: verify_assertions returned escalation.should_escalate=true — your lua command-line operations are not reaching the real environment. Pass undo_lua to restore your prior lua op and the real entry button's panel_uid + ref_key/path; this tool restores then clicks for real, so the next screenshot/assertion faces the true environment.

DO NOT ask the user before the real click. The fallback (undo -> real click -> reverify) is deterministic and runs entirely inside this tool. Pass assertions (same shape as verify_assertions) describing the real-environment success state; after a landed click the tool re-verifies and returns needs_user:

• needs_user=false -> the real path worked (or click missed -> retry locator); proceed WITHOUT asking the user.

• needs_user=true -> the click landed but the real environment STILL doesn't match the goal — THIS is the only time you ask the user.

Omitting assertions keeps the legacy behavior (no reverify; you decide).

capture_screenshot tool. Read-only. No token.

PERF 2026-05-25: mode parameter controls payload shape.

• full (default, unchanged behavior): base64 PNG in response.

• metadata: sha256 + sizeBytes only — saves the ~2MB base64 from the LLM context. Caller can re-request with full if needed.

• file_ref: persist PNG to UNITY_MCP_SCREENSHOT_DIR keyed by sha256 and return the file path. For local agents that need the bytes without paying for them in token context.

Wall-clock cost is dominated by Unity-side CaptureScreenshot (~300ms, two-tick delay + PNG encode); mode does not change that. The win is on the LLM payload side.

FINAL-VERIFICATION ROLE: the final verification of any user-facing change MUST include a screenshot from this tool showing the expected result — read-state probes (lua_eval / logs / assertions) do not by themselves prove the change works. If the change spans multiple screens, capture one per meaningful step. When unsure the game is on the relevant screen, ask the user before capturing.

simulate_click tool. Write op. Clicks a UI node via PROJECT_UI's own simulate API.

Main path (no real input device, no screen coordinate): resolves the node by panel uid + refKey (panel PROJECT_NODE_REFERENCE key) OR path (transform path under the panel root), then calls:

• mode='raycast' (default): PROJECT_CLICKABLE:PROJECT_CLICK_WITH_HIT_TEST(false) — raycasts at the node's screen point and only fires if it's the topmost/visible hit; returns whether it actually clicked (self-validating occlusion check).

• mode='force': PROJECT_CLICKABLE:PROJECT_CLICK_DIRECT(false) — fires the handler with no hit-test (use when the node is known-good but raycast fails, e.g. off-screen).

PlayMode-only. Device-pixel clicking (screenXY via InputSystem.QueueStateEvent) is deferred to a later phase.

FINAL-VERIFICATION ROLE: when the user described repro steps, drive the same clicks here during final verification instead of calling internal handlers that bypass the input path; then capture_screenshot to evidence the result.

simulate_key tool. Write op. Triggers an input ACTION by its action path.

Calls PROJECT_RUNTIME.global.PROJECT_INPUT_SERVICE:PROJECT_TRIGGER_ACTION(actionPath, 'Performed') then 'Canceled' — this routes through the game's InnerHandleInputInfo funnel exactly like real input, but bypasses the focus / inputEnabled gate, so it works even when the Editor Game view isn't focused. Use for "press the key bound to feature X" (e.g. "Hud/OpenMap", "Player/Jump").

IMPORTANT — only REAL InputActionAsset actions can be triggered this way. Virtual PROJECT_HOTKEY_SYSTEM bindings (isVirtual=true, driven by PROJECT_HOTKEY_CALLBACK — most panel hotkeys like "Common/ClosePanelCommon") are NOT in playerInput.actions, so this returns triggered=false with a note. For those, use simulate_click on the bound button, or lua_eval the panel method.

Device-level raw keystrokes (InputSystem.QueueStateEvent on Keyboard) are deferred to a later phase. PlayMode-only.

FINAL-VERIFICATION ROLE: when the user gave repro steps involving key/gamepad presses, replay them here during final verification, then capture_screenshot to evidence the outcome. (Reaches only real InputActionAsset actions — for virtual PROJECT_HOTKEY_SYSTEM hotkeys use simulate_click on the bound button.)

set_input_text tool. Write op. Sets an PROJECT_UI input field's text and commits it.

Resolves the input node (panel uid + refKey OR path), sets its settable .text, calls ActivateInputField(), then fires the field's PROJECT_COMMIT_TEXT callback (if any) so the panel reacts as if the user typed and committed. Does NOT synthesize per-key device events (unreliable for TMP/UGUI input fields under the new Input System).

PlayMode-only.

FINAL-VERIFICATION ROLE: when the user's repro steps involve typing into a field, set it here during final verification, then capture_screenshot to evidence the result.

选择和绑定到特定的 Unity bridge 实例。

当有多个 Unity 编辑器实例运行时使用此工具。每个实例应该配置不同的端口。

Args: port: 要连接的 Unity bridge 端口号。如果不指定，显示当前连接状态。 scan: 设为 True 时扫描并列出所有可用的 bridge 实例（端口 17873-17882）。

Returns: 操作结果，包含连接状态或扫描到的实例列表。

Examples: # 扫描所有可用的 bridge 实例 select_bridge(scan=True)

# 查看当前连接状态
select_bridge()

# 连接到端口 17874 的 Unity 实例
select_bridge(port=17874)

将 Unity bridge 绑定到当前 MCP 会话。

这个工具会记住当前会话的绑定关系，重启 MCP server 后可以自动恢复。 适合需要长期固定连接到特定 Unity 实例的场景。

Args: port: 要绑定的端口号。如果不指定，显示当前绑定状态。 auto: 设为 True 时自动检测并绑定。如果只有一个实例则自动绑定， 如果有多个实例则返回列表让用户选择。 unbind: 设为 True 时解除当前会话的绑定。 restore: 设为 True 时从持久化文件恢复之前的绑定。

Returns: 操作结果，包含绑定状态、会话 ID、端口信息等。

Examples: # 自动检测并绑定（如果只有一个实例） bind_bridge(auto=True)

# 绑定到指定端口
bind_bridge(port=17874)

# 查看当前绑定状态
bind_bridge()

# 解除绑定
bind_bridge(unbind=True)

# 恢复之前的绑定
bind_bridge(restore=True)

Pair, inspect, diagnose, clear, or safely repair a Unity bridge.

Actions: pair, status, owners, diagnose, clear, repair. Clear also requires side=binding|accepted|listener. Destructive operations retain bridge/client/generation identity checks and never kill a process.