v0.6.4 to v0.7.0

1 added, 1 removed. Audit A to A.

---

name: ucp-editor-lifecycle

description: >-

Bring a Unity project under control with the `ucp` CLI: install the bridge, open or adopt the

editor, read the `[editor]` state line every command prints, recompile or hot-reload method

bodies without a domain reload, enter and leave play mode, and recover from modal dialogs. Use when a task starts (is Unity running? is the console

red? is the scene dirty?), when a command reports COMPILE ERRORS or a MODAL, or when the editor

must be opened, restarted, or closed. For scene content, assets, UI, capture, debugging, or

project configuration, use the matching ucp-* skill or the unity-control-protocol omni skill.

compatibility: Requires the `ucp` CLI (npm `@mflrevan/ucp`) and the UCP bridge package in the target Unity project. Unity 2021.3 or newer.

metadata:

author: mflRevan

- version: '0.6.4'

+ version: '0.7.0'

homepage: https://unityctl.dev/skills/ucp-editor-lifecycle

---

# Editor lifecycle, state, and recovery

`ucp` talks to a bridge inside the Unity Editor over a local WebSocket. Commands run on Unity's

main thread, so anything that blocks it (a modal dialog, a synchronous import, a compile) blocks

every command. This skill is about knowing which state the editor is in and steering it, so the

other surfaces have a working editor to talk to.

## Ground rules

- Pin the project once with `UCP_PROJECT=/path/to/project` (or `--project`); every command

auto-detects the project from the working directory otherwise.

- Every command that reaches the bridge ends with a dim line. Read it before the next command:

```text

[editor] edit mode · scene SampleScene (dirty) · console 2 errors, 1 warning (+1 error from this command)

```

Segments that change what you do next: `COMPILE ERRORS` (fix scripts, then `ucp compile`),

`compiling` / `importing assets` (wait, retry), `prefab stage <path>` (scene commands target the

open prefab, not the scene), `MODAL "<title>"` (answer it, see below), `play mode` (you are in

play mode; edits are not saved). In `--json` the same data is the `editor` object.

- Instance ids from `ucp scene snapshot` are short-lived. They change after recompiles, domain

reloads, scene loads, package changes, and test runs. Re-snapshot before reusing one, or address

objects by `--path "Root/Child"` where a command supports it.

- `--json` on any command gives a `{ "success": ..., "data": ..., "editor": ... }` envelope and a

non-zero exit on failure. Prefer it when you parse output.

## Install and connect

```bash

ucp doctor # CLI, bridge package, Unity resolution, serialization settings

ucp install # add the bridge to Packages/manifest.json, pinned to this CLI version

ucp install --dev # repo checkout only: mount the local bridge for bridge development

ucp connect # handshake; prints Unity version, protocol, and main-thread readiness

ucp bridge status # installed bridge source and whether it matches the CLI

ucp bridge update # move the manifest reference to this CLI's bridge version

```

`ucp connect` reports `Main thread: responsive` or `not serving yet (first import or compile in

progress)`. A socket answering is not a usable editor; wait for the responsive line after a fresh

open.

## Open, adopt, close

```bash

ucp open # launch the resolved Unity for the project, or adopt a running one, wait for the bridge

ucp editor status # pid, executable, project version, requested version, session

ucp editor ps # every Unity process ucp can see (import workers are filtered out)

ucp editor restart # in-editor quit, then relaunch; waits for the old process to exit

ucp editor close # in-editor quit; --force kills the process if the quit does not return

ucp editor close --discard-changes # the only way past a dirty scene; the edits are lost

ucp editor logs --lines 200 # ucp's log, the editor's own -logFile, or Unity's Editor.log

```

- An editor opened from Unity Hub or by hand is adopted like one ucp launched; `editor status`

says which. ucp refuses to launch a second editor on a project Unity already holds.

- ucp never pulls the editor window to the front; compiles and reloads finish unfocused.

- A command bound to an editor that exits fails with "the editor exited" and does not relaunch

it; an editor ucp launched that dies within two minutes stops automatic launches until you run

`ucp open` yourself. Check `ucp editor logs` (the crashed log is kept as `editor.prev.log`).

- Pick the editor version with `--unity <path/to/Unity.exe>` or `--force-unity-version 6000.4.0f1`

when the project's `ProjectVersion.txt` is not what you want.

- The first open after a Library wipe imports for minutes. `ucp open` waits until the main thread

actually serves requests; with `--timeout 0` it waits indefinitely.

- Never close Unity through the OS window. On a dirty scene that raises Unity's native save

prompt with nobody to answer it. `ucp editor close` uses the in-editor quit, which is prompt

free, and `--force` is the recovery path.

## Compile, play, stop, pause

```bash

ucp compile # recompile and wait; prints per-assembly CS#### errors, exits non-zero on failure

ucp compile --no-wait # kick off compilation and return (a later command waits for the reload itself)

ucp hot-reload apply Assets/Scripts/Foo.cs # patch edited method bodies in ~1 s, no domain reload, play mode survives

ucp hot-reload status # what is patched; `ucp compile` or `hot-reload revert` clears it

ucp play # saves a dirty scene first (a dirty untitled one is discarded unless --keep-untitled)

ucp play --log-file play.log

ucp pause # toggles

ucp stop

```

- Entering play mode reloads the domain. `ucp play` confirms the transition and reports Unity's

refusal reason when scripts do not compile. Do not retry blindly; read `ucp compile`.

- `hot-reload apply` is for method-body edits while iterating; its response lists the edits that

need a real compile (`needsFullCompile`: fields, types, signatures). While patches are live,

auto refresh is held so a focus change cannot recompile under you; `ucp compile` makes the

edits permanent and releases it. Always end with `ucp compile` before tests, builds, or handoff.

- `play` and `scene load` save a dirty titled scene first and discard a dirty untitled one

(`--keep-untitled` keeps it and refuses instead); `--no-save` refuses on any dirty scene with a

non-zero exit. `editor close` and `restart` refuse on any dirty scene; `--discard-changes` is

the explicit way past. Unity's own save prompt is never shown.

- Edits made in play mode are lost on `stop`, exactly as in the editor.

## Modal dialogs

The bridge handshake reports how long ago the main thread last ticked. When it is stale, the CLI

looks for a dialog before sending anything:

- Known Unity prompts are answered per `--dialog-policy` (default `auto`): Safe Mode is declined

with Ignore, "Packages with Errors" is dismissed, editor-version and project-upgrade prompts

are continued. Use `--dialog-policy manual` to answer nothing automatically.

- Anything else fails at once with the dialog's title and buttons instead of a 30 s timeout:

```text

[ERR] Unity is blocked by a modal dialog "Save Scene?" [Save | Don't Save | Cancel] ...

```

Answer it deliberately:

```bash

ucp editor dialog # list open dialogs and their buttons

ucp editor dialog --answer "Don't Save" # exact label first, then substring, case-insensitive

```

- A request that times out while a dialog opened mid-flight is diagnosed the same way when it

returns. Dialog detection is Windows-only today; elsewhere the request timeout applies.

- Scripts run through `ucp exec` bypass the bridge's save guard. Never call

`EditorUtility.DisplayDialog` or `SaveScene()` on an untitled scene from an `IUCPScript`.

## Diagnose a stuck editor

```bash

ucp connect --timeout 5 # main thread responsive? compiling?

ucp editor dialog # anything modal?

ucp logs status # console counts and the most repeated messages

ucp editor logs --lines 100

ucp editor ps # editors, and other ucp processes still acting on them

ucp editor close --force && ucp open

```

If `ucp open` reports the editor is running without a bridge and the project has compile errors,

the editor is in Safe Mode: fix the reported `CS####` errors, then `ucp editor restart`.

## Global flags worth knowing

`--project`, `--unity`, `--force-unity-version`, `--json`, `--timeout <s>` (0 waits forever; UI

render commands default to 310 s, everything else to 30 s), `--dialog-policy

silences the `[editor]` line.