sootsim debug
sootsim debug
Toggle engine debug channels, capture snapshots, and diff internal state from the terminal while targeting any connected sim.
terminal
Options
| flag | description |
|---|---|
--sim <sim> | target a specific connected sim |
--port <number> | bridge port (defaults to 7668) |
--json | emit compact JSON for machine consumption |
--pretty | emit formatted JSON for human inspection |
Examples
terminal
What Debug Owns
debug is for engine state, not user-facing UI summaries. It owns:
- channel toggles like
sheets,portals,touch, andrender - snapshots and diffs
- recent event history
- on-demand inspectors for complex runtime structures
If you want to know what is on screen, use inspect. If you want to know what the engine thinks just happened, use debug.
Subcommands
Run sootsim debug <verb> --help for the flags and examples of any subcommand.
state
| subcommand | description |
|---|---|
state <kind> [args] | runtime dumps (shell, worker, keyboard, hit, gesture, ownership, …) |
eval
| subcommand | description |
|---|---|
eval <expression> | alias for js |
js <expression> | evaluate JS in the engine realm (reach into SootSim.*) |
profiling
| subcommand | description |
|---|---|
get memory | live object counts + heap sampler |
sample-color <x> <y> [w] [h] | average canvas color over a rect |
trace shell [on [limit]|off|status|clear|<recentLimit>] | per-tick animation + shell frame trace |
snapshot
| subcommand | description |
|---|---|
clear-snapshots [label] | discard captured snapshots |
diff <labelA> <labelB> | compare two snapshots |
snapshot [label] | capture tree snapshot for later diff |
snapshots | list captured snapshot labels |
inspectors
| subcommand | description |
|---|---|
find sheets | list engine-internal nodes by category |
events
| subcommand | description |
|---|---|
clear-events | reset the debug event ring buffer |
recent | last N debug events |
record [on|off] | toggle the debug event ring buffer |