Uloop Compile

uloop compile

Execute Unity project compilation.

When to use

• After C# edits, to check for compile errors and make the change live in the Editor (Play Mode, tests, a tool call): to land edits you finished trying with hot reload, or to apply structural changes hot reload cannot.
• To try an edit in the running Editor, especially during Play Mode, run uloop hot-reload instead: a compile drops every hot-reload patch and discards the Play session.

Usage

bashCopy code
uloop compile [--force-recompile] [--no-wait-for-domain-reload] [--stop-on-external-scene-changes] [--timeout-seconds <seconds>]

Parameters

When to use --force-recompile

--force-recompile is almost never needed. Detecting changed files is Unity's job: even when files were edited outside the Editor, a plain uloop compile refreshes assets and runs every recompilation the changes require. "The files were changed externally, so recompile everything just in case" is not a valid reason.

Why to avoid it:

• On large projects a full recompile plus domain reload can freeze Unity for a long time.
• The result crosses a domain reload, so it often comes back as COMPILE_RESULT_UNKNOWN and does not work as a verification step.
• It puts the Editor into the unstable just-after-reload state for no benefit.

The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full build. Otherwise always run plain uloop compile.

Output

Returns JSON:

• Success: boolean or null
• ErrorCount: number or null
• WarningCount: number or null
• Warning (string, optional): set when the compile was requested during Play Mode (the Play session is discarded), while pause points were armed in either Play Mode or Edit Mode (the domain reload drops every pause point patch; those enabled with --persist are counted separately and re-armed from their saved enable request after the reload), or while hot-reload changes were active (a successful compile drops every patch; the edited sources are compiled in).
• Message: string
• ErrorCode: string or null. COMPILE_ALREADY_IN_PROGRESS / COMPILE_EDITOR_UPDATING when Unity was still compiling or updating after the CLI waited for it and sent the compile again (it does so twice before giving up; run uloop compile again), COMPILE_RESULT_UNKNOWN after a forced recompile that did not return a definitive result.
• NextActions: string array or null. Corrective steps derived from the errors, e.g. the assembly that declares an unresolved namespace (CS0234), or, for CS0246 in a script under an asmdef, a reminder to check that asmdef's references (the type may instead be a typo — decide from the error).

When Unity stops compiling before the finish callback (Success: null, indeterminate), Message keeps the get-logs pointer and appends Recent Console errors: with the last few Console errors (typically the asmdef or compiler error that aborted the compile), so fix from that list before reaching for uloop get-logs.

Troubleshooting

When Unity's API Updater asks for consent to rewrite source files during a CLI compile (the 'Script Updating Consent' dialog), uloop declines automatically — source files are never rewritten without explicit user consent — and the response's Warning discloses the decline. The obsolete-API errors the updater would have fixed appear in Errors; fix them in code, or have the user accept the dialog in an interactive Unity session. Outside CLI compiles, and for the separate 'API Update Required' dialog, the modal can still appear and uloop cannot click it: if compile times out while the Editor looks idle, ask the user to answer the dialog — never auto-dismiss it.

A compile that outlives your shell's output window keeps running inside Unity: the call may return with empty or truncated output while the compile is still in progress, and the next uloop command is rejected with "Unity is busy running 'compile'" until it finishes. That rejection is normal single-flight behavior, not a failure — wait and rerun the command; do not restart Unity or rerun compile to recover.