@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/unity-cli/references/notes.md

@@ -0,0 +1,20 @@
+# Notes
+
+- `--non-interactive` and `--yes` together suppress all prompts — use both in CI.
+- A short flag means one thing on every command: `-y` is `--yes` wherever `--yes` exists, `-a` is `--architecture`, `-e` is `--editor-path`, `-f` is `--force`, `-i` is `--installed`, `-l` is `--list`, `-m` is `--module`, `-o` is `--output` and `-r` is `--releases`. Every other option takes its long name: `unity projects` and `unity projects size` spell "every project" `--all`, `logs` and `projects logs` spell `--follow`, `projects import` spells `--input`, `build` and `run` spell `--log-file`, `projects` spells `--modified`, `templates location` spells `--reset`, `build` spells `--output-path` and `foundry get` spells `--out`. An old spelling the CLI still accepts (`-a`, `-m`, `-i`, `-l`, `-r`, `-f` or `-o` on those, `--project` on `status`, `--template-version`, `--hub-version`, `--package-version`, `--list-components`, `--install-dir`, `--childModules`, `--wait-timeout`, `--git-token-stdin`, `--group_by` on `command`, `--local-space` on `collaboration annotations`, `--project-id` and `--organization-id` on `collaboration`, `-v` on `projects`, `--since` on `releases` and `vcs git migrate-lfs`, `--project` on `assets export`, `assets import` and `auth default`, `--path` on `build run`, `--project-path` on `projects clone`, `--skip` on `releases` and `cloud projects`) prints a warning naming the spelling to use; so does `--verbose` on `editors` and `projects`, which still shows every column but now spells it `--long`; in `--format json` it is in the envelope's `warnings`. Use the new spelling, so the warning never lands in a log you parse.
+- `--timeout` takes a whole number of seconds written as digits (`--timeout 600`) on every command, and so do `UNITY_BUILD_TIMEOUT`, `UNITY_RUN_TIMEOUT` and `UNITY_TEST_TIMEOUT`. A unit, fraction or exponent (`30s`, `5m`, `1.5`, `1e3`) is a usage error (exit `2`), so convert minutes to seconds yourself.
+- `--format json` always produces machine-readable output; prefer it over parsing human text. Error envelopes are pretty-printed with the same 2-space indent as success envelopes. The envelope's `command` is the full command path (`projects list`, `cloud org list`), the same in json and ndjson and on success and failure; it is `""` when no command matched, such as an unknown one.
+- **`success` is `true` exactly when the exit code is `0`.** A status command whose answer is no (`unity auth status` signed out, `unity license status` with no license, `unity status` with no ready Editor) is a failure: `success: false`, an `errors[0].code` naming the answer, and its report still in `data`. A listing that finds nothing (`unity editors running` with no Editor) succeeds with an empty list.
+- **A streamed named command has no CLI envelope.** When the project's `com.unity.pipeline` formats a named command's output itself (see `references/integration-advanced.md`), `unity command <name> --format json` (or `--json`) prints the command's own result, one JSON value per line, with no `success`, `errors` or `data` wrapper, so its rows are not under `.data.items[]`. Branch on the exit code, which is the command's own, not one from the exit-code table above: `0` means it succeeded and any other code that it did not, such as `1` for a failed command, `102` when the Editor was busy and refused it (retry), or `106` when it was cancelled. A cancel that follows your Ctrl-C or a SIGTERM to the CLI exits `130` or `143` instead. With an older `com.unity.pipeline` the envelope and every rule in this list apply.
+- **Read failures from stdout, not stderr.** A failed command still writes a complete document to stdout: under `--format json` an envelope with `success: false` and a populated `errors` array (`errors[0].code` is the stable token to branch on); under `--format ndjson` the usual terminal `{"type":"result","success":false,…}` frame. **Every ndjson stream ends with exactly one terminal `{"type":"result"}` frame, on success too**, so a stream without one was truncated. Table-shaped listings (`unity editors`, `unity editors upgrade --check`, `unity templates`, `unity releases`, `unity projects`, `unity contexts`, `unity auth accounts`, `unity modules`, `unity command`, `unity skills`, `unity logs`, `unity cloud orgs`, `unity cloud projects` and the like) write one row per line first, each starting with `"type":"row"` so you can tell a row from a `progress` or `result` frame, then a terminal frame whose `data` is `{count, total, nextPage|nextCursor, partial}` (some listings keep older keys there too). A `unity templates` row keeps its own `type` (the template type) with no `"row"` marker. A single-record answer (`unity version`, `unity language`, `unity env`, `unity doctor`, `unity config proxy`, `unity cache info`, `unity context current`, `unity editors default`, `unity install-path`, `unity diagnose update` and the like) is that frame alone, its `data` the same as `--format json`. `--quiet` never changes json output. It never changes ndjson output either, except that `unity editors upgrade`, `unity build --list-targets` and `unity build --list-profiles` still drop their rows under `--quiet` (the terminal frame stays), a known bug; leave `--quiet` off when you need those rows. A warning in either format appears only in `warnings`, never on stderr. A `--watch` or `--follow` stream, which only ends on Ctrl-C, writes its rows and no terminal frame. **Branch on `success`, never on `data`** — `data` is usually `null` on a failure, but not always: a partial `unity editors add` failure carries a row per path, and an ambiguous `unity auth switch` carries `data.candidates` for you to disambiguate with. Check `success` and the exit code — never treat empty stdout as a failure signal, and do not parse stderr, which carries only human diagnostics in these formats. If stdout is empty on a non-zero exit, that is a known bug in that command rather than a shape you should code against.
+- **Never merge stderr into stdout when you parse (`2>&1`, or a tool that captures both as one stream).** Stdout alone is a complete, valid document under `--format json` and `--format ndjson`, but stderr carries human diagnostics and, for some agents, a one-line install hint (Claude Code gets a `<claude-code-hint … />` tag there). Merged in, those lines trail the JSON, and a parser fails with `Extra data` or a decoder needs `raw_decode`. Capture the two streams separately (`unity … --format json 2>err.txt >out.json`) and parse stdout only, or discard stderr with `2>/dev/null` (`2>NUL` on Windows cmd). `UNITY_NO_AGENT_HINTS=1` removes the hint line, but separate streams are the fix.
+- `unity <version> [path]` is a shorthand for `unity open [path] --editor-version <version>`. Works with `lts`, `latest`, or a full version string like `6000.0.47f1`.
+- The CLI supports kubectl-style plugins: any `unity-<name>` binary on PATH is callable as `unity <name>`.
+- Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, and now also from Commander usage errors, the `unity bug` log-archive warning, and `unity projects add`/`remove` machine (tsv) output, while SGR color/style codes are preserved.
+- The CLI reports anonymous crashes and errors via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT`, or turn off "Send crash reports" in the Hub's settings, to disable reporting entirely. Separately again, every run sends one anonymous `cli telemetry` usage ping even when nobody answered the consent prompt; turning analytics off (in the CLI, or in the Hub while signed in), `DO_NOT_TRACK`, or `UNITY_NO_CLI_INVOKED_TELEMETRY` stops it — see [diagnostics-maintenance.md](diagnostics-maintenance.md#analytics--usagetelemetry-consent).
+- `unity --version` prints the version you have. `unity self-update --check --format json` says whether a newer one exists on your installed channel (a beta follows betas). `unity self-update --check --channel stable --format json` checks for a stable release, for example when moving off a beta once GA ships.
+- **Always use the latest version of the Unity CLI unless you are told to use a specific version.** A newer CLI regularly adds commands and output fields these docs describe, so an outdated one fails in ways that read like the docs being wrong.
+- Since `0.1.0-beta.8` the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with `unity config update-check off` or the `UNITY_NO_UPDATE_CHECK` env var.
+- The same check also covers plugins the CLI installed (`unity plugin install`): when one has a newer version, a notice names it and suggests `unity plugin upgrade`, at most once a day. The same two switches turn it off.
+- **Under `--format json` and `--format ndjson` that same notice reaches you as a `notifications` array on the envelope** — see [Notifications](../SKILL.md#notifications) below. Over MCP it arrives once per session, as prose in the server's `initialize` `instructions`.
+- Outbound HTTP from every CLI command honors the resolved proxy (see `unity config proxy`). An invalid `--proxy` value (malformed URL or unsupported scheme) fails with a usage error (exit 2) instead of being silently ignored. Inspect what the CLI actually resolved with `unity env --format json` or `unity doctor --format json` — both surface the active proxy URL, its source, and auth source.

package/skills/unity-cli/references/notifications.md

@@ -0,0 +1,39 @@
+# Notifications
+
+A `--format json` or `--format ndjson` envelope may carry a `notifications`
+array: advisories about the user's environment rather than about the command
+you ran. **When one is present, tell the user** — they have no other way to see
+it, because the human-facing equivalent is a terminal banner that never reaches
+you.
+
+The key is absent when there is nothing to report, so read it as
+`envelope.notifications ?? []`.
+
+```jsonc
+{
+  "code": "CLI_UPDATE_AVAILABLE",
+  "message": "A new version of the Unity CLI is available: 1.0.0-beta.8 → 1.0.0-beta.9",
+  "data": { "current": "1.0.0-beta.8", "latest": "1.0.0-beta.9" },
+  "remediation": { "command": "unity self-update", "requiresUserApproval": true }
+}
+```
+
+Branch on `code`; `message` is localized and meant for display. `data` is
+shaped per `code`.
+
+`PLUGIN_UPDATE_AVAILABLE` means an installed plugin has a newer version.
+`data` is `{ "plugin": "<id>", "current": "…", "latest": "…" }`, and the
+remediation is `unity plugin upgrade <id>`. There is one entry per outdated
+plugin.
+
+`remediation` says how the notification gets resolved. It may be absent, which
+means the notification is informational and there is nothing to run.
+
+`FEX_EMU_EXPERIMENTAL` means the command ran, or will run, the x86_64 Editor
+through FEX-Emu on Linux arm64. Tell the user it is experimental and
+unsupported and that C# script compilation is known to crash there.
+
+**`requiresUserApproval: true` means do not run `remediation.command`
+yourself.** Surface the notification and the command, and let the user decide.
+
+---

package/skills/unity-cli/references/playmode-verification-loop.md

@@ -0,0 +1,279 @@
+# Play-mode verification loop
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and the general "drive a running Editor" workflow. All global
+flags (`--format json`, `--non-interactive`, `--yes`, `--proxy`, ...) apply to every command below.
+[integration-advanced.md](integration-advanced.md) covers the Pipeline command surface generally;
+this page is the recipe for one specific loop: enter Play mode, confirm the game is actually
+running (not frozen), look at it, read its console, and tune it, all without leaving the CLI.
+
+Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page.
+
+## Contents
+
+- Why this loop, and not `editor.playmode start` + a screenshot
+- The recipe
+- Summary: the ordered commands
+
+## Why this loop, and not `editor.playmode start` + a screenshot
+
+A screenshot renders on demand: it can capture the last frame a frozen Game view drew and look
+exactly like a live game. Treat "Play mode entered" and "a screenshot came back" as setup, not
+proof. The loop below adds one cheap, server-side check (`job wait` on `Time.frameCount`) that
+actually proves frames are advancing before you trust anything else you observe.
+
+**Command names, parameters, and defaults below are the connected Editor's, not the CLI's own**:
+they come from the project's `com.unity.pipeline` package and can change between package versions.
+Confirm the exact set for your project with `unity command` before relying on any of
+this, the same caution [integration-advanced.md](integration-advanced.md#available-in-production--the-common-live-commands)
+already gives for `script eval`.
+
+**Put pipeline-specific flags after a `--` fence.** `unity command` recognizes a small set of its
+own flags (`--project-path`, `--runtime`, `--runtime-path`, `--timeout`, `--detach`,
+`--result-only`, plus the global flags) anywhere in the tail, not just at the start, so a
+same-named Editor parameter (`script eval`'s own `timeout`, in **milliseconds**, or `job wait`'s, in seconds) is swallowed by the CLI's
+`--timeout` (**seconds**) unless it comes after `--`. Every multi-flag example below uses the
+fence; a single positional argument (like a bare `script eval` call at its default timeout) does not need
+one.
+
+## The recipe
+
+### 1. Confirm a connected Editor and discover its commands
+
+```bash
+unity status --format json          # look for state "ready"
+unity command --format json         # the full catalog, with each command's parameter schema
+```
+
+If nothing is reachable, rule out Safe Mode and a sandboxed shell before concluding the Editor is
+down: see [integration-advanced.md → Recovering from Safe Mode](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors)
+and [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor).
+
+Then read the play state before you change anything: `unity command editor status` reports it, and
+its `playMode` reads `stopped` when the Editor is not playing. If the Editor is already playing or
+paused, that session is the user's. Reading it is fine (steps 4 to 6 only read). Leave the settings in
+step 2, `editor.playmode start` in step 3, the pause and step recipe in step 4, the tuning in step 7 and
+`editor.playmode stop` in step 8 alone, and tell the user what you found.
+
+### 2. Keep the Editor ticking while it is unfocused
+
+Unity throttles `EditorApplication.update` when the Editor window does not have focus, which is
+the common case for an agent driving it headlessly or alongside other work. On an unfocused
+Editor, entering Play mode can leave the game genuinely stuck at frame 1 while `unity status` still
+reports it as playing, because the per-frame loop that would advance it is the thing being
+throttled. `com.unity.pipeline` ships a command for exactly this, `editor set_auto_tick`, which forces a
+tick at a throttled rate even while unfocused:
+
+```bash
+unity command editor set_auto_tick  # enabled=true, interval-ms=16 (~60 Hz), persist=true by default
+```
+
+Call it before every `editor.playmode start` you drive, not once per Editor session: step 8 turns it off
+when you are done, so a second request in the same Editor session must turn it on again or the game freezes
+at frame 1. `persist=true` (the default) survives a domain reload, so you do not need to call it again after
+a recompile within one Play Mode request; pass
+`-- --persist false` for a one-off setting that should revert after the next unrelated recompile
+instead of sticking for the rest of the session.
+
+This is the confirmed, currently available fix for the freeze, not a temporary stand-in: it is a
+real Pipeline command with its own doc entry (`Documentation~/commands/editor-lifecycle-and-observability.md`),
+not something a future package release removes the need for. The CLI does not call it
+automatically before `editor.playmode start`: it sends only the bare `editor.playmode start` command,
+so call it yourself.
+
+The player loop has a second switch: the project's Run In Background Player Setting
+(`Application.runInBackground`). On macOS and Windows, with it off, Unity pauses the game while the
+Editor is unfocused, and `editor set_auto_tick` can't undo that pause. The setting ships in builds, so
+turn it on explicitly with the Pipeline command, which records the project's value and keeps it out
+of builds:
+
+```bash
+unity command editor.playmode set_run_in_background                      # on for this Editor session
+unity command editor.playmode set_run_in_background -- --enabled false    # put the project's value back
+```
+
+The override doesn't touch the project's saved settings, so it lasts until you revert it or the
+Editor restarts. After a restart, run the command again.
+
+Alternatively, a project can turn on **Ensure editor runs in background in PlayMode** under
+Project Settings > Pipeline > Editor, which applies it only while playing. Check that your package
+has the command with `unity command --query set_run_in_background --detail full --format json`. On an older
+package, set it with `script eval` before `editor.playmode start`, and put the project's value back after
+`editor.playmode stop`, because nothing keeps it out of builds there:
+
+```bash
+unity command script eval "return UnityEngine.Application.runInBackground;"   # note the project's value
+unity command script eval "UnityEngine.Application.runInBackground = true;"
+```
+
+### 3. Enter Play mode, then wait for the Pipeline server before the next command
+
+```bash
+unity command editor.playmode start
+unity status --until-ready --project-path <path> --format json
+```
+
+`editor.playmode start` drops the Pipeline listener for a few seconds while the domain reloads. Sending the
+next command immediately can hit `EDITOR_NOT_READY` or simply queue behind the reconnect. `unity
+status --until-ready` is the documented fix, not a hand-rolled polling loop: it keeps checking
+until a matching Editor reports `ready`, then returns. Full detail in
+[integration-advanced.md → status](integration-advanced.md#status--live-state-of-connected-editors).
+
+### 4. Confirm the game is actually advancing, not frozen at frame 1
+
+A `job wait` on `Time.frameCount` with `op: changed` proves the frame counter has moved since the
+wait started, server-side, with no client polling loop:
+
+```bash
+unity command job wait -- \
+  --condition '{"member":"UnityEngine.Time.frameCount","op":"changed"}' \
+  --timeout 10
+```
+
+`op` is `equals` (the default), `notEquals`, `greaterThan`, `lessThan`, `contains` or `changed`, spelled in camelCase exactly like that (`not_equals` is an unknown op). `op: changed` needs no `value`: it is met the first time the member differs from the value observed
+when the wait was armed. A `met: true` result with `framesObserved` > 0 is your proof; `timedOut:
+true` with the frame count unmoved is the frozen-at-frame-1 symptom this whole step exists to
+catch. On a session you started, step 2 (`editor set_auto_tick` and `runInBackground`) is the fix to check
+first. On the user's session, leave step 2 alone and report the stall.
+
+A package that has `editor.playmode set_run_in_background` also reports the player loop in
+`unity status --format json` while in Play mode: `frameCount` and `playerLoopTicking` on the
+instance row. `playerLoopTicking: false` outside a pause is the same frozen symptom, and it costs
+one read instead of a wait. Keep the `job wait` above as the proof; the status fields are a quick
+first check, and an older package omits them. `timeout` (`timeout_s` on `com.unity.pipeline` 0.8.x) defaults to 30 if omitted;
+10 seconds above is a shortened budget, since a ticking Editor should advance the frame count within
+a couple of frames of the wait being armed.
+
+`job wait` is one `/api/exec` request that holds the exec queue for its own duration, so a
+synchronous call like the one above is only for a wait you expect to resolve in a few seconds. For
+anything longer, or a condition that depends on a command you still need to issue, add `--async
+true` and poll the result instead of blocking on it:
+
+```bash
+unity command job wait -- --condition '{"member":"UnityEngine.Time.frameCount","op":"changed"}' \
+  --timeout 120 --async true          # returns { "waitId": "..." } immediately
+unity command job wait_status -- --wait-id <waitId>
+```
+
+`job wait`'s own `--async` is unrelated to `unity command`'s `--detach`: the former is the
+connected Editor evaluating the condition in the background and reporting through `job wait_status` /
+`job wait_cancel`; the latter is the CLI's own client-side job tracking (`unity job status` /
+`unity job wait`) for a command that runs long on the Editor's main thread. Don't conflate the two,
+or `unity job wait <job-id>` (the CLI's own command) with `unity command job wait` (the Pipeline's).
+
+`job wait` also accepts a `find-type`/`target` + instance member path instead of a static one (for
+example a gameplay manager's own state field), and an `on-met.capture` follow-up that captures the
+game view in the same frame the condition first holds, atomically, when a client-side "wait, then
+screenshot" loop would risk missing a short-lived state. Discover the exact shape (and whether your
+project's package version has it at all) with `unity command job --format json`
+rather than assuming it: `job wait`/`job wait_status`/`job wait_cancel` are a comparatively new addition to
+`com.unity.pipeline`.
+
+**Still frozen with `editor set_auto_tick` and Run In Background on?** Check for a locked desktop. On Windows, a locked session can stop Play Mode from advancing even with Run In Background on, so every `job wait` times out and every observation reads frame 1. If nobody can unlock the machine, drive the frames yourself, but only on a session you started. That is one you entered with `editor.playmode start` from a stopped Editor, as step 1 showed. If the Editor was already playing, the session is the user's, so leave its settings alone too, and don't pause, step or stop it. A paused session is flat by design, so ask the user to resume it. If it is frozen, say so, name the likely causes (a locked desktop, or an unfocused Editor with Run In Background off), and ask the user to fix that. On your own session, pause it, then step it one frame per `script eval` call.
+
+```bash
+unity command script eval -- --code 'UnityEditor.EditorApplication.isPaused = true;'
+unity command script eval -- --code 'UnityEditor.EditorApplication.Step();'     # one frame: repeat once per frame you need
+unity command script eval -- --code 'return UnityEngine.Time.frameCount;'      # read the count in its own call
+```
+
+Each `Step()` advances one frame. Drive it from the host, one call per frame, because an `script eval` runs on the main thread and holds the player loop until it returns. Check that the count rose by exactly the number of steps. A frame is not a fixed span of game time. Read `UnityEngine.Time.time` before and after one step, then divide the time you need by the difference (one project measured 50 steps to a second, and yours can differ). If `Time.time` does not move because `Time.timeScale` is 0, no number of steps produces game time. Step by frame count for logic that runs per frame, and for anything timed, ask the user before you change `timeScale`, then put it back. Every step is an `script eval` call that the client may ask the user to approve, so keep the stepped window short and ask before a run that needs more than a few hundred steps. Set `UnityEditor.EditorApplication.isPaused = false;` when you are done, whatever the outcome. Stepping shows what happens frame by frame, not real-time timing or frame rate.
+
+### 5. Capture the game view without bloating the response
+
+```bash
+unity command capture game_view -- --source screen --output-path Screenshots/playtest.png
+```
+
+The flag here is `--output-path`, the same one `capture screenshot` takes. Pass it and the result is a file path, not an inline base64 image, which keeps an agent's
+tool result small. The path is **project-relative** (the package's own docs give
+`Screenshots/foo.png` as the example); nothing in the package documentation states a restriction to
+paths under `Assets/`, so do not assume one. When you do need the image inline instead of, or as
+well as, the file (for example to look at it yourself in this turn), add `--include-inline-image
+true` and use `--max-resolution` to cap the inline copy's longest edge without touching the
+resolution of the saved file:
+
+```bash
+unity command capture game_view -- --max-resolution 512   # inline only, downscaled, no output-path
+```
+
+`source=screen` captures the composited game view (including Screen Space - Overlay UI such as
+HUDs); `source=camera` renders a single camera off-screen instead and never sees Screen Space -
+Overlay canvases. Pass whichever you mean explicitly: the command's default value for `source` has
+changed between package versions (`com.unity.pipeline` 0.8.0-exp.1 switched the default from
+`camera` to `screen`), so relying on the default is one more thing to go stale as the project's
+package updates.
+
+`source=screen` needs an unlocked desktop (reported on Windows): a `screen` capture taken while the session was locked came back as a solid cyan image with no error. When the machine is unattended and may be locked, use `--source camera`. Treat a single-color capture as suspect and check that the frame count is rising before you rely on it, since a fade to black is a legitimate frame. A camera capture shows overlay UI only if its Canvas uses Screen Space - Camera, because no camera draws a Screen Space - Overlay canvas. If the UI you need is on an Overlay canvas, read its state with `script eval` instead of looking for it in the image.
+
+### 6. Read the console for exceptions before trusting a clean-looking capture
+
+```bash
+unity command console get -- --tail 50 --level error
+```
+
+`level` is a minimum-severity floor (`log` | `warn` | `error`, default `log`), not an exact match, so
+`--level error` returns errors and exceptions only. Prefer `console status` (no arguments) when you
+only need the compile-failure flag and entry counts, not the entries themselves, to poll cheaply
+while something else runs.
+
+Older `com.unity.pipeline` documentation names this command `get_console_logs`, and before command
+groups it was `console` (with `console_status` and `clear_console` alongside it); the currently
+shipping command is `console get` (with `console status` and `console clear`), which is a
+case in point for confirming names against `unity command` rather than trusting any cached
+documentation, this page included.
+
+### 7. Tune the running game with `script eval`, not edit, recompile, and re-enter Play mode
+
+Once Play mode is confirmed live, prefer evaluating C# against the running instance over leaving
+Play mode to edit a script, recompiling, and re-entering: it is one round trip instead of a
+domain reload plus a fresh Play mode entry, and it does not lose whatever state you were verifying.
+
+```bash
+unity command script eval "UnityEngine.Time.timeScale = 0.5f;"
+```
+
+A bare positional string is `script eval`'s `code` parameter at its default 5-second timeout. Override the
+timeout with the fully-named form (`timeout` is milliseconds on `script eval`, not the seconds `unity
+command --timeout` takes, which is exactly the collision the `--` fence in this page's intro
+exists for):
+
+```bash
+unity command script eval -- --code 'return UnityEngine.Time.frameCount;' --timeout 15000
+```
+
+Reach for `script create` → `unity recompile` → `script attach` (documented in
+[integration-advanced.md → Authoring custom `[CliCommand]` tools](integration-advanced.md#authoring-custom-clicommand-tools))
+only when the change genuinely needs a new type or a persistent script asset. For a one-off runtime
+tweak inside a live Play mode session, `script eval` is cheaper and keeps the loop in this page intact.
+
+### 8. Exit Play mode when you are done
+
+```bash
+unity command editor.playmode stop
+unity command editor.playmode set_run_in_background -- --enabled false
+unity command editor set_auto_tick -- --enabled false
+```
+
+Stop only a session you started. One that was already playing when you read `editor status` in
+step 1 is the user's. Then put back what step 2 changed: with `persist=true`, auto-tick otherwise
+keeps the Editor ticking while unfocused for the rest of the session. Skip the `editor set_auto_tick`
+revert if you'll keep driving the Editor, because an unfocused Editor stalls without it.
+
+## Summary: the ordered commands
+
+```bash
+unity status --format json
+unity command editor status   # already playing or paused? Then the session is the user's: read it, change nothing
+unity command editor set_auto_tick
+unity command editor.playmode set_run_in_background
+unity command editor.playmode start
+unity status --until-ready --project-path <path> --format json
+unity command job wait -- --condition '{"member":"UnityEngine.Time.frameCount","op":"changed"}' --timeout 10
+unity command capture game_view -- --source screen --output-path Screenshots/playtest.png   # --source camera when the machine may be locked
+unity command console get -- --tail 50 --level error
+unity command script eval "<C# to inspect or tune the running game>"
+unity command editor.playmode stop
+unity command editor.playmode set_run_in_background -- --enabled false
+unity command editor set_auto_tick -- --enabled false   # skip if you'll keep driving the Editor
+```