uloop pause-point
A pause point captures locals at an exact frame without a source edit. Prefer it over sleeps or after-the-fact reads when input delivery, event ordering, or transition-frame fidelity matters.
Quick Check
- Enter PlayMode. If the game progresses on its own, pause it with
control-play-mode --action Pause, arrange the scenario while paused, and add--resume-playin step 2. - Arm the marker, fire the input, and wait for the hit in one foreground command:
bashuloop enable-pause-point --file Assets/Scripts/Enemy.cs --line 42 --timeout-seconds 60 --await --trigger "simulate-keyboard --action Press --key Space" # paused the game in step 1? add --resume-play, or the input never lands
- Read
CapturedVariablesin the hit response first, then gather extra evidence while still paused (execute-dynamic-code, one screenshot). - A
single-shotmarker (the default) disarms after the hit; clear other modes withuloop clear-pause-point.
Only CapturedVariables is evidence of the values at the patched line. Before deviating, read references/quick-check-template.md.
Parameters
Tables list Unity-accepted parameters plus clear's CLI-only --file/--line; other CLI-only flags (--await, --trigger, --resume-play, --expect, capture filters) are in the references.
enable-pause-point
Enable a pause point so Unity pauses when that code path is reached, either by a named UloopPausePoint.Pause marker (Id) or by resolving a source file and line (File+Line)
| Parameter | Type | Default | Description |
|---|---|---|---|
--id | string | - | Named pause point id passed to UloopPausePoint.Pause. Mutually exclusive with File/Line |
--file | string | - | Source file to patch a pause point into: Assets/..., Packages/<package-id>/..., a package folder path, or an absolute path. Requires Line; mutually exclusive with Id |
--line | integer | - | 1-based source line to resolve within File. Requires File; mutually exclusive with Id |
--timeout-seconds | integer | 30 | Seconds before the enable request expires and stops pausing late hits |
--mode | enum | single-shot | Capture mode: single-shot pauses once, continuous pauses on every hit, trace records hits without pausing |
--hit-when | string | - | Conditional capture expression (<name> <op> <literal>). Only matching hits are captured; requires File and Line |
--max-history | integer | 20 | Maximum number of captured hit frames to retain (1-100) |
--max-preview-elements | integer | 10 | Maximum elements in a captured collection's preview (1-1000). Also caps previews in later pause-point-status responses; status cannot change it. |
--max-caller-frames | integer | 2 | Maximum caller stack frames recorded per hit (0-8). 0 disables capture. Also caps later pause-point-status responses; status cannot change it. |
--method | string | - | Optional method simple name or Type.Method. When set, --line resolves only inside matching methods |
--snapshot-timing | enum | pre-line | pre-line captures before the resolved line runs; post-line captures after that line's statement finished, without arming the next line |
--persist | flag | - | Re-arm after a domain reload (compile, Play entry); re-arm result is reported in pause-point-status |
clear-pause-point
Clear one or all named UloopPausePoint.Pause markers. The response field ClearedCount is the number of markers this call transitioned to Cleared: 0 or 1 for --id, and the number transitioned for --all. Auto-disarmed and expired markers still count as 1; the record stays readable via pause-point-status (StatusBeforeClear keeps the prior state). Clearing the marker that owns the current pause releases the Editor pause and lets the game consume any state you arranged while paused: arm the next marker first, then clear the old id, or re-arm it with --await --resume-play instead of clearing.
| Parameter | Type | Default | Description |
|---|---|---|---|
--id | string | - | Named pause point id to clear |
--file | string | - | Project-relative source file of a file:line pause point. Requires --line; mutually exclusive with --id and --all |
--line | integer | - | 1-based source line of a file:line pause point. Requires --file; mutually exclusive with --id and --all |
--all | flag | - | Clear every non-cleared pause point marker (armed, auto-disarmed, or expired) |
enable-watch
Register a C# expression to evaluate on each paused Play Mode step
| Parameter | Type | Default | Description |
|---|---|---|---|
--id | string | - | Unique watch expression identifier |
--expression | string | - | C# expression returning an object; UloopPausePoint.TryGetCapturedValue can read the latest raw capture |
--max-history | integer | 20 | Maximum number of watch evaluations to retain (1-100) |
get-watch-values
Show registered watch expression values and bounded evaluation history
| Parameter | Type | Default | Description |
|---|---|---|---|
--id | string | - | Optional watch expression identifier; omit to return all watches |
clear-watch
Clear one or all registered C# watch expressions
| Parameter | Type | Default | Description |
|---|---|---|---|
--id | string | - | Watch expression identifier to clear |
--all | flag | - | Clear every registered watch expression |
Status, Timeouts, Hot Reload
uloop pause-point-status with no target lists every marker; inspect one with --id "<file>:<line>" or with --file/--line together (never both). await-pause-point and clear-pause-point take the same two forms; await always needs a target.
On a wait timeout, PAUSE_POINT_EXPIRED, or an enable failure, read Error.Details.Hint or the failure ErrorCode, then RecommendedNextAction. After hot reload, --line stays the editor's line number.
Requirements & Safety
- On the automatic Debug-switch warning: the pause point is already armed - do not interrupt or ask mid-flow.
- Patches drop on every compile or domain reload (the compile / Play-entry responses warn).
--persistre-arms automatically (references/persist.md). - Physics message methods, their helpers, and pre-bound delegates can miss hits on pre-existing GameObjects; enable warns where detectable.
- An
--idmarker waits on yourUloopPausePoint.Pause(id)call (using io.github.hatayama.UnityCliLoop.Runtime;); its hits record noCapturedVariables. - Every
--fileform resolves to the asset path (Packages/<package-id>/...for a package script), which the markerIduses; status, await, and clear find it by any form.
Reference Guides
Read the one whose trigger matches:
references/quick-check-template.md— full--trigger/--await/--resume-playloop, timeouts, hit fields.references/captured-variables.md— captures, name filters,--expectvalue forms, caller frames, raw values.references/capture-modes-and-history.md— modes, history,--max-history,--hit-when.references/line-placement.md— choosing the line: every-frame lines, held input, input+N frames.references/watch-expressions.md— watch rules.references/condition-triggered-pause.md— runtime-condition pauses.references/fast-progressing-games.md— freezing self-progressing games,--resume-play.references/persist.md— what--persistrestores, timeout restart, first-frame gap, the re-arm report.references/troubleshooting.md— timeouts, missed hits, hot reload, Debug switch, failure codes, path forms.
