Commands

Command Reference

The Cade Console provides commands for expression evaluation, event simulation, variable management, engine control, and debugging.

Command Summary

Command	Syntax	Description
`eval`	`eval <expression> [--vars k=v]`	Evaluate an expression with current game state
`trigger`	`trigger <event\|switch> [--player <name>]`	Trigger a scoring event or switch
`set`	`set <variable> <value>`	Set a variable value for the current player
`unset`	`unset <variable>`	Remove a variable
`inspect`	`inspect <target> [--json\|--hcl]`	Inspect a variable or event in detail
`watch`	`watch <variable>`	Monitor a variable for changes
`unwatch`	`unwatch <variable>`	Stop monitoring a variable
`player`	`player [number]`	Show or set the active player
`status`	`status`	Display current debug session state
`engine`	`engine <start\|stop\|status\|restart>`	Control the scoring engine
`load`	`load <path>`	Load a game configuration file
`list-events`	`list-events [--source <source>]`	List available events
`validate-event`	`validate-event <event>`	Check if an event is valid
`event-info`	`event-info <event>`	Show detailed event information
`profile`	`profile <start\|stop\|status\|export\|reset>`	Manage the scoring profiler
`scenario`	`scenario <list\|run\|status\|warp>`	Manage scenario testing
`cascade`	`cascade [show\|list\|clear\|stats]`	Manage event cascades
`trace`	`trace`	Manage execution tracing
`breakpoint`	`breakpoint <set\|remove> <location>`	Set or remove breakpoints
`watchpoint`	`watchpoint <set\|remove> <variable>`	Set or remove watchpoints
`debug-mode`	`debug-mode <off\|live\|simulation>`	Set the debugging mode
`step`	`step`	Step to the next breakpoint
`continue`	`continue`	Continue execution after a breakpoint
`theme`	`theme [name]`	Show or change the TUI theme
`timestamps`	`timestamps [on\|off]`	Toggle timestamp display
`filter`	`filter <pattern>`	Filter log output
`log-level`	`log-level <level>`	Set the log verbosity level
`tui`	`tui`	Switch to TUI mode
`history`	`history [count]`	Show command history
`help`	`help [command] [--interactive]`	Show help information
`clear`	`clear`	Clear the screen
`exit` / `quit`	`exit`	Exit the console

Expression Evaluation

The eval command evaluates expressions using the current game state. Variables are referenced with ${variable.name} syntax.

cade:debug> eval 100 + 50
Result: 150

cade:debug> eval ${score} * 2
Result: 2000

cade:debug> eval ${score} + (${bonus.multiplier} * 500)
Result: 2500

cade:debug> eval ${score} > 1000 && ${multiball.active}
Result: false

Additional variables can be passed inline:

cade:debug> eval ${x} + ${y} --vars x=10,y=20
Result: 30

See the Expressions page for the full expression language reference.

Event Triggering

The trigger command fires events into the scoring engine. It supports both named scoring events and hardware switch triggers.

cade:debug> trigger target.hit
Event: target.hit
Player: 1
Total points: 500
New score: 1500

cade:debug> trigger switch.ramp_entry
# Triggers the ramp_entry switch through the switch handler

cade:debug> trigger bumper.hit --player 2
# Triggers bumper.hit for player 2

When an event is triggered, the console captures the resulting event cascade. Press F7 to view it in the cascade panel.

Variable Management

Setting Variables

cade:debug> set score 1000
Set score = 1000 for player 1

cade:debug> set bonus.multiplier 3
Set bonus.multiplier = 3 for player 1

cade:debug> set multiball.active true
Set multiball.active = true for player 1

Inspecting Variables

The inspect command shows detailed information about a variable or event. Output format can be switched with --json or --hcl.

cade:debug> inspect score
Variable: score
Type: int
Scope: player
Current value: 1,000
Initial value: 0

cade:debug> inspect score --json
# Outputs JSON representation

cade:debug> inspect events
# Lists all available events

cade:debug> inspect bumper.hit
# Auto-detects and inspects as event, showing triggers, conditions, and actions

cade:debug> inspect events --live
# Shows recent live events from the hardware bridge

Watching Variables

cade:debug> watch score
Now watching variable: score

# When score changes:
[WATCH] score changed from 1000 to 1500 for player 1

cade:debug> unwatch score
Stopped watching variable: score

Player Management

cade:debug> player
Current player: 1

cade:debug> player 2
Active player set to: 2

Engine Control

The engine command manages the scoring engine lifecycle.

cade:debug> engine start
cade:debug> engine stop
cade:debug> engine status
cade:debug> engine restart

Configuration Loading

cade:debug> load my-game.cade

Profiler

The profile command controls the scoring profiler, which tracks event and expression evaluation performance.

cade:debug> profile start
Profiling started

cade:debug> profile status
Scoring profiler: ACTIVE
  Event types tracked: 12
  Expression types tracked: 8

  Top events by P95 latency:
    bumper.hit                                P95:       45.2 us

cade:debug> profile export ./my-profiles/
Profile exported to: ./my-profiles/scoring_profile_20250315_143022.json

cade:debug> profile stop
cade:debug> profile reset

Scenario Testing

The scenario command runs predefined test scenarios against the scoring engine.

cade:debug> scenario list
cade:debug> scenario run tests/basic_scoring.yaml
cade:debug> scenario run --all tests/
cade:debug> scenario status
cade:debug> scenario warp tests/multiball_setup.yaml

The warp subcommand loads a scenario’s initial state into the engine without running assertions, useful for quickly setting up complex game states for manual testing.

Session Information

cade:debug> status
Debug Session Status
==================
Active Player: 1
Total Players: 4
Variables Set: 3
Watched Variables: 1 (score)
Commands Executed: 15

Tab Completion

The console provides context-aware tab completion for commands, variables, event names, and expression tokens.

cade:debug> he<Tab>
help     history

cade:debug> set bo<Tab>
bonus.active    bonus.multiplier    bonus.value

cade:debug> eval ${sc<Tab>
${score}    ${scoreMode}

cade:debug> trigger tar<Tab>
target.hit    target.dropped    target.raised

Interactive Help

The help -i flag opens an interactive help browser where you can navigate commands with arrow keys, search with /, and view detailed help with Enter.

cade:debug> help -i