diff --git a/.agents/skills/uloop-status/SKILL.md b/.agents/skills/uloop-status/SKILL.md index 0c754c954..6ecf92583 100644 --- a/.agents/skills/uloop-status/SKILL.md +++ b/.agents/skills/uloop-status/SKILL.md @@ -57,4 +57,4 @@ Play Mode does not change the state: a paused Play Mode session is `Ready`, with - A sandboxed shell that cannot open the Unix socket gets an error, not NotRunning; run it outside the sandbox. - uloop cannot detect Safe Mode directly; ServerUnavailable that does not clear is the signal. - Before reporting MainThreadBlocked it wakes the Editor's main loop and asks again about a second later, so an Editor that is only idle in the background reads as Ready. -- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. +- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. `execute-dynamic-code` is the exception: its own snippet may block the main thread for as long as it runs. diff --git a/.claude/skills/uloop-status/SKILL.md b/.claude/skills/uloop-status/SKILL.md index 0c754c954..6ecf92583 100644 --- a/.claude/skills/uloop-status/SKILL.md +++ b/.claude/skills/uloop-status/SKILL.md @@ -57,4 +57,4 @@ Play Mode does not change the state: a paused Play Mode session is `Ready`, with - A sandboxed shell that cannot open the Unix socket gets an error, not NotRunning; run it outside the sandbox. - uloop cannot detect Safe Mode directly; ServerUnavailable that does not clear is the signal. - Before reporting MainThreadBlocked it wakes the Editor's main loop and asks again about a second later, so an Editor that is only idle in the background reads as Ready. -- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. +- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. `execute-dynamic-code` is the exception: its own snippet may block the main thread for as long as it runs. diff --git a/Packages/src/Documentation~/tools.md b/Packages/src/Documentation~/tools.md index bec2fe075..78bcc70f7 100644 --- a/Packages/src/Documentation~/tools.md +++ b/Packages/src/Documentation~/tools.md @@ -224,3 +224,16 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-windows-e2e.ps ``` `run-posix-e2e.sh` uses the built native CLI binary by default, passes an explicit `--project-path` to every `uloop` invocation, and runs CLI recovery/readiness, simulate-mouse UI coverage, and UI Toolkit screenshot annotation and click coverage in one sequence (skip the last with `--skip-uitoolkit-annotation`). To verify `replay-input` against a JSON created in the Recordings window, run `verify-replay-via-cli.sh` separately. + +## Editor Readiness Tools + +### 18. status - Check Whether the Editor Can Take a Command +Use `uloop status` before sending commands when Unity may be starting, compiling, busy, or closed. It answers without side effects and reports exactly one state in its `State` field: `Busy` (a uloop command holds the command slot), `Starting`, `MainThreadBlocked` (the main thread has not run for 5 seconds or more, usually a modal dialog), `Compiling`, `ImportingAssets`, `Ready` (the only state that exits 0), `NotResponding`, `ServerUnavailable`, `NotRunning`, or `Unreachable`. + +A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait, releases the command slot, and the command fails with `MAIN_THREAD_BLOCKED` and the stall seconds; nothing ran, so sending it again after the block clears is safe. The dedicated error code and its guidance are rendered by project runner 3.12.3 or newer, which this package pins; an older runner shows the same message under `UNITY_RPC_ERROR`. A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`, except for `execute-dynamic-code`, whose snippet may block the main thread for as long as it runs. + +```text +→ status +→ State: MainThreadBlocked, SecondsSinceLastMainThreadTick: 12.3 +→ Dismiss the dialog (or run focus-window to find it), then send the command once more +``` diff --git a/Packages/src/Documentation~/tools_ja.md b/Packages/src/Documentation~/tools_ja.md index b104e6493..4844d837d 100644 --- a/Packages/src/Documentation~/tools_ja.md +++ b/Packages/src/Documentation~/tools_ja.md @@ -224,3 +224,16 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-windows-e2e.ps ``` `run-posix-e2e.sh` は、デフォルトでチェックイン済みのネイティブCLIバイナリを使い、すべての `uloop` 呼び出しに明示的な `--project-path` を渡します。CLI recovery/readiness、simulate-mouse UI、UI Toolkit のスクリーンショット注釈とクリックを1つの流れで検証します(最後のものは `--skip-uitoolkit-annotation` で省けます)。Recordingsウィンドウで作成したJSONの replay-input 検証は `verify-replay-via-cli.sh` を個別に実行します。 + +## Editor 状態確認ツール + +### 18. status - Editor がコマンドを受けられるか確認 +Unity が起動中・コンパイル中・処理中・終了している可能性があるときは、コマンドを送る前に `uloop status` を使います。副作用なしで応答し、`State` 欄に状態を 1 つだけ返します: `Busy`(uloop のコマンドが実行枠を持っている)、`Starting`、`MainThreadBlocked`(main thread が 5 秒以上動いていない。多くはモーダルダイアログ)、`Compiling`、`ImportingAssets`、`Ready`(exit code 0 になる唯一の状態)、`NotResponding`、`ServerUnavailable`、`NotRunning`、`Unreachable`。 + +main thread がブロックされている間に送ったコマンドは、その解除を待ちます。コマンドのコードがまだ 1 行も動いていない状態で停止が 30 秒に達すると、Unity は待機をやめてコマンドの実行枠を解放し、コマンドは `MAIN_THREAD_BLOCKED` と停止秒数を返して失敗します。何も実行されていないので、ブロックが解けた後に送り直しても安全です。専用のエラーコードと案内を表示するのは project runner 3.12.3 以降で、このパッケージはそれを pin しています。古い runner では同じメッセージが `UNITY_RPC_ERROR` として表示されます。コマンド自身のコードが main thread をブロックしている場合は止めません。代わりに CLI が 60 秒ごとに stderr へ停止の通知を出し、5 分で `UNITY_EDITOR_UNRESPONSIVE` を返して諦めます。ただし `execute-dynamic-code` は例外で、スニペットが main thread を塞いでいる間は打ち切りません。 + +```text +→ status +→ State: MainThreadBlocked, SecondsSinceLastMainThreadTick: 12.3 +→ Dismiss the dialog (or run focus-window to find it), then send the command once more +``` diff --git a/Packages/src/Editor/CliOnlyTools~/Status/Skill/SKILL.md b/Packages/src/Editor/CliOnlyTools~/Status/Skill/SKILL.md index 0c754c954..6ecf92583 100644 --- a/Packages/src/Editor/CliOnlyTools~/Status/Skill/SKILL.md +++ b/Packages/src/Editor/CliOnlyTools~/Status/Skill/SKILL.md @@ -57,4 +57,4 @@ Play Mode does not change the state: a paused Play Mode session is `Ready`, with - A sandboxed shell that cannot open the Unix socket gets an error, not NotRunning; run it outside the sandbox. - uloop cannot detect Safe Mode directly; ServerUnavailable that does not clear is the signal. - Before reporting MainThreadBlocked it wakes the Editor's main loop and asks again about a second later, so an Editor that is only idle in the background reads as Ready. -- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. +- A command sent while the main thread is blocked waits for it. Once the stall reaches 30 seconds before any of the command's code has run, Unity stops the wait and the command fails with `MAIN_THREAD_BLOCKED` (nothing ran, so running it again after the block clears is safe). A command whose own code blocks the main thread is not stopped; the CLI prints a stall notice on stderr every 60 seconds instead and gives up after 5 minutes with `UNITY_EDITOR_UNRESPONSIVE`. `execute-dynamic-code` is the exception: its own snippet may block the main thread for as long as it runs.