unity-headless-by-default
Unity: Headless by Default — Open a Window Only for Rendering
Section titled “Unity: Headless by Default — Open a Window Only for Rendering”Always-loaded. A windowed Editor costs a GPU context, a modal-dialog risk no agent can dismiss, and a seat in the per-project Editor mutex. A batch run costs none of those.
Every Unity launch you start yourself defaults to -batchmode -nographics: compile check, EditMode and PlayMode tests, builds, asset and .meta edits, the blind-edit confirm round, scripted work. A RAW launch also carries an explicit -logFile and a ceiling (T1K_UNITY_BATCH_TIMEOUT_SEC through the batch gate; never wrap the gate in timeout). The facade exposes neither flag. Only t1k unity test and run launch batch mode through the gate, and only when no Editor is open; the gate may refuse with exit 75, meaning retry later. Test runs outside the facade use unity_batch_gate_run_tests, which returns 77 (reason on stderr: no-results, zero-tests, all-skipped) for a run that proved nothing, never 0. recompile, eval and menu need an OPEN Editor.
Open a windowed Editor (or Xvfb) ONLY when the task needs rendering or frame events: WaitForEndOfFrame or coroutines that need a rendered frame, screenshots, visual or UI verification, Game view interaction. -nographics has no rendering, so WaitForEndOfFrame never fires; use Xvfb for a rendered frame. Before opening one, say in one line which need justifies it. The facade has no launch verb for it, and a window you launched becomes a user-owned Editor: leave it running, never kill it. No such need: stay headless.
Cheap checks first. Before any Editor compile or test run, run the no-Editor checks that apply, in order: .claude/scripts/unity-csharp-syntax-check.sh on the changed .cs files (parse errors only, not a type check), then .claude/scripts/unity-static-ref-check.cjs refs|ids for prefab/asset/Addressables edits — both read disk, so both are parallel-safe and take no Editor lock — then ONE batched t1k unity recompile + t1k unity test, with a windowed Editor/Xvfb only when rendering is the need named above. A green static check never replaces the one Editor compile. Skill: t1k-unity-base-static-ref-check.
One Unity per project. Never launch a second on a project that already has one. Temp/UnityLockfile can survive a crash, so confirm liveness with t1k unity instance list or pgrep first. Never take over a user-owned open Editor: use the t1k unity CLI against it instead of launching another (unity-forbidden-operations.md).
Full detail
Section titled “Full detail”Task-to-mode table and flags: t1k-unity-editor-cli references/headless-vs-windowed.md. Rationale and batch-mode limits: docs/unity-headless-by-default.md.
Related
Section titled “Related”unity-forbidden-operations.md · ai-velocity-batch-compile-unity.md · t1k-unity-editor-cli SKILL.md