Introduction

Welcome to the Cade Runtime API reference. This documentation covers the local HTTP surface the runtime exposes for health monitoring and debugging, along with the complete HCL configuration spec used to define tables, devices, scoring, audio, and more.

Base URL

http://localhost:8080

The web server is optional and disabled by default. Enable it with --web-server (short form -w), or with web { enabled = true } in cade.conf, and it binds to localhost:8080. Override the host and port with --web-host / --web-port, or the host and port attributes of the web block.

Authentication

Local connections do not require authentication. The web block exposes its endpoints directly without an auth scheme. For production deployments, bind the server to 127.0.0.1 and leave the debug endpoints disabled:

web {
  enabled = true
  host    = "127.0.0.1"
  port    = 8080

  health {
    enabled = true
  }

  debug {
    enabled = false
  }

  logging {
    enabled = false
  }
}

Each sub-block also has a matching flag — --health-enabled, --debug-enabled, --web-logging, --livetree-enabled — and every setting can be overridden by an environment variable using the CADE_ prefix with dots replaced by underscores (CADE_WEB_ENABLED, CADE_WEB_PORT, CADE_WEB_HEALTH_ENABLED).

Configuration Example

Cade uses HCL-based declarative configuration. Tables are defined in .cade files using composable blocks. Here is a pop bumper with a scoring rule that awards points every time it is hit:

variable "int" "bumper_value" {
  initial = 1000
  min     = 100
  max     = 10000
  scope   = "player"
}

device "switch" "bumper" "pop_bumper" {
  id = 10

  settings {
    pulse_ms    = 20
    pulse_power = 60
    recycle_ms  = 100
  }
}

score "event" "bumper_hit" {
  when   = device.pop_bumper.hit
  points = var.bumper_value
}

The when attribute names the event that fires the rule, written bare — device.<name>.hit, where <name> is the device’s third label. Events come from switch-category devices; coil devices are driven by the runtime and do not emit events of their own.

Cade Configuration

The Cade CLI is configured through a layered system that supports HCL files, YAML files, environment variables, and command-line flags. Only the settings you need to change must be specified; all others use sensible defaults.

Configuration Files

Cade looks for configuration in the following locations:

• ~/.cade.hcl or ./.cade.hcl (HCL format)
• ~/.cade.yaml or ./.cade.yaml (YAML format)

If both HCL and YAML files exist, the HCL file takes precedence.

Configuration Precedence

Settings are resolved from highest to lowest priority:

Environment Variables

Environment variables use the CADE_ prefix with underscores representing nested keys:

Top-Level Blocks

web

Controls the built-in web server for health monitoring and debugging. For what the endpoints serve and how to monitor a running table, see Web Dashboard & Observability.

web {
  enabled = false          # Enable the web server (default: false)
  host    = "localhost"    # Bind address (default: "localhost")
  port    = 8080           # Listen port (default: 8080)

  health {
    enabled = true         # Health monitoring endpoints (default: true)
  }

  debug {
    enabled = false        # Debug/visualization endpoints (default: false)
  }

  logging {
    enabled = false        # Web server access logging (default: false)
  }
}

logging

Controls application-level logging.

logging {
  level  = "info"    # Log level: debug, info, warn, error (default: "info")
  format = "text"    # Log format: text, json (default: "text")
}

game

Configures game session parameters.

game {
  players            = ["player1"]   # Player IDs, 1-6 unique, non-empty (default: ["player1"])
  max_players        = 4             # Max players allowed per game, 1-6 (default: 4)
  balls_per_game     = 3             # Balls each player gets per game (default: 3)
  credits_per_player = 1             # Credits deducted when a player joins (default: 1)
}

credits

Configures the credit and coin-op system.

credits {
  coins_per_credit = 1       # Coins needed for one credit (default: 1)
  max_credits      = 99      # Maximum credit balance (default: 99)
  free_play        = false   # Skip credit deductions on game start (default: false)
}

audio

Controls the audio subsystem.

audio {
  disabled = false         # Disable audio entirely (default: false)
}

analytics

Configures the analytics and telemetry system.

analytics {
  enabled            = false                    # Enable analytics (default: false)
  chunk_size_limit   = 10485760                 # Chunk size in bytes (default: 10MB)
  chunk_ttl          = "24h"                    # Chunk time-to-live (default: "24h")
  max_disk_usage     = 1073741824               # Max disk usage in bytes (default: 1GB)
  chunk_storage_path = "/tmp/cade-analytics"     # Storage path

  realtime_patterns = [                         # Events sent immediately
    "ACHIEVEMENT_*",
    "MODE_*",
    "MULTIBALL_*"
  ]

  backend_type    = "noop"                      # noop, memory, logging, http, grpc (default: "noop")
  backend_url     = ""                          # Endpoint for http/grpc backends
  backend_timeout = "30s"                       # Request timeout (default: "30s")

  realtime_enabled  = true                      # Real-time event dispatch (default: true)
  chunking_enabled  = true                      # Chunk-based storage (default: true)
}

platform

Declares platform driver instances. See the Platform page for driver-specific settings.

platform "grpc" "vpx_bridge" {
  port              = 50051
  enable_gateway    = true
  enable_reflection = true
}

Minimal Example

A working configuration only needs the settings you want to change. Everything else uses defaults:

web {
  enabled = true
}

This enables the web server on localhost:8080 with health endpoints active and debug endpoints disabled.

Full Example

web {
  enabled = false
  host    = "localhost"
  port    = 8080

  health {
    enabled = true
  }

  debug {
    enabled = false
  }

  logging {
    enabled = false
  }
}

logging {
  level  = "info"
  format = "text"
}

game {
  players            = ["player1"]
  max_players        = 4
  balls_per_game     = 3
  credits_per_player = 1
}

credits {
  coins_per_credit = 1
  max_credits      = 99
  free_play        = false
}

audio {
  disabled = false
}

analytics {
  enabled            = false
  chunk_size_limit   = 10485760
  chunk_ttl          = "24h"
  max_disk_usage     = 1073741824
  chunk_storage_path = "/tmp/cade-analytics"

  realtime_patterns = [
    "ACHIEVEMENT_*",
    "MODE_*",
    "MULTIBALL_*"
  ]

  backend_type       = "noop"
  backend_url        = ""
  backend_timeout    = "30s"
  realtime_enabled   = true
  chunking_enabled   = true
}

Table Configuration

Table configuration files (.cade files) define the game-specific behavior of a pinball machine. They use HCL syntax and contain blocks for devices, events, variables, scoring rules, signals, fragments, platform bindings, assemblies, and modules.

Top-Level Blocks

A table configuration is composed of these block types:

Every device is declared with three labels — device "<category>" "<type>" "<name>" — for example device "coil" "bumper" "bumper_1". Variables, scores, signals, and flows take two labels; assemblies, modules, event handlers, lightshows, and display shows take one.

Top-Level Attributes

Alongside the blocks, a table file carries a few plain attributes at the top level:

Ad-hoc host switches

Some hosts send switch events for names no device block declares — a browser-hosted table’s synthetic tilt switch is the typical case. A device.<name>.<action> binding to such a switch works, but validation cannot tell it apart from a typo, so it warns on every load. Declaring the name in ad_hoc_switches marks the binding as intentional and silences the warning:

ad_hoc_switches = ["tilt"]

event_handler "tilt_warning" {
  when = device.tilt.hit
  emit = "game.tilt_warning"
}

An undeclared switch’s activation arrives as device.<name>.hit (and its release as device.<name>.released), so bind those actions.

A declared name does not become a device: it gets no autofire rule and no hardware handshake entry — exactly the two things a synthetic, host-only switch must not have. Use a real device block for anything physical.

An entry may also be written as a fully qualified device reference, which gives the switch the category and subtype coordinates a bare name has no room for:

ad_hoc_switches = [device.switch.virtual.tilt]

Both spellings are accepted permanently — a bare "tilt" behaves exactly as it always has.

Expression Syntax

The rule of thumb across .cade files is write everything bare; quote only a literal string. Bare names and dotted references are resolved to their underlying value or event name, so quoting them is unnecessary — a quoted form still parses (for back-compat), but bare is the canonical style used throughout this reference.

Expression-valued fields (points, condition, variable references, and update/modify values) are written bare, using the var. prefix for variables. ${...} interpolation is a parse error:

points    = var.bumper_value * var.combo_multiplier / 100
condition = var.balls_in_play == 0

Event-matching fields (when, signal, event) and reference lists (switches, signals, devices) name an event or device, also written bare:

when     = device.bumper_1.hit
switches = [orbit_entry, orbit_exit]

Example

This table wires a pop bumper and an orbit shot, awards points, grows a combo multiplier, and flashes lights on a hit:

name    = "Ramp Runner"
version = "1.0.0"

# Game session
game {
  max_players    = 4
  balls_per_game = 3
}

# Typed game-state variables with bounds and scope
variable "int" "bumper_value" {
  initial = 1000
  min     = 100
  max     = 10000
  scope   = "global"
}

variable "int" "combo_multiplier" {
  initial    = 100    # 100% = 1.0x
  max        = 500    # 500% = 5.0x
  scope      = "ball"
  decay_rate = 10
  decay_to   = 100
}

# Hardware devices: category / type / name
device "coil" "bumper" "bumper_1" {
  id = 10

  hardware {
    coil   = "C10"
    switch = "S10"
  }

  settings {
    strength     = 60
    trigger_time = "50ms"
  }
}

device "switch" "lane" "left_orbit_entry" {
  id   = 70
  tags = ["orbit", "playfield"]
}

device "switch" "lane" "left_orbit_exit" {
  id   = 71
  tags = ["orbit", "playfield"]
}

# Indicator lights for the bumper
device "light" "led" "b1l1" { id = 128 }

# Table-wide event names
global_events {
  bumper_1_hit {
    description = "Bumper 1 hit"
  }

  left_orbit_complete {
    description = "Left orbit shot completed"
  }
}

# A signal detects a two-switch shot and awards points on completion
signal "shot" "left_orbit" {
  switches = [
    left_orbit_entry,
    left_orbit_exit,
  ]
  time_window        = "3s"
  points             = 2000
  each_switch_points = 50
}

# Scoring rule: react to an event and update a variable
score "event" "bumper_hit" {
  when   = device.bumper_1.hit
  points = var.bumper_value * var.combo_multiplier / 100

  update {
    combo_multiplier = var.combo_multiplier + 10
  }
}

# General-purpose reaction: pulse the coil and flash the light on a hit
event_handler "bumper_1_flash" {
  when = device.bumper_1.hit

  actions {
    pulse_coil "bumper_1" {}

    flash_light "b1l1" {
      duration = "200ms"
    }
  }
}

Reusing Configuration

Two blocks help avoid copy-pasting repeated hardware and logic.

An assembly is a parameterized template stamped out per flipper, target, or lane. Body blocks use param.<name> for the values supplied by each use:

assembly "flipper" {
  parameter "int" "button_id" { required = true }
  parameter "int" "coil_id"   { required = true }

  device "switch" "standard" "button" { id = param.button_id }
  device "coil"   "standard" "power"  { id = param.coil_id }

  variable "int" "flip_count" {
    initial = 0
    scope   = "ball"
  }
}

use "flipper" "left_flipper" {
  button_id = 17
  coil_id   = 1
}

use "flipper" "right_flipper" {
  button_id = 18
  coil_id   = 2
}

A module bundles a game feature — a mode plus its scoring, variables, and handlers. The module name is the mode name; a module with no mode block is always-on infrastructure:

module "multiball" {
  description = "Multi-ball play"

  mode {
    priority = 500
  }

  variable "int" "balls_in_play" {
    initial = 0
    scope   = "global"
  }

  stacking {
    allow_multiple = false
  }
}

See the Assembly and Module pages for the full attribute reference.

Pragma

The pragma block provides fine-grained control over validation, optimization, and runtime behavior in Cade table configurations. Pragmas enable gradual migration between validation modes, performance tuning, and feature gating.

Syntax

A table has a single pragma block that defines global settings and optional component-specific overrides:

pragma {
  mode               = "strict"
  optimization_level = 2
  experimental       = false
  deprecated_ok      = false

  errors_as_warnings = ["undefined_variable", "type_mismatch"]
  disable_checks     = ["expression_complexity"]

  variables {
    cache_expressions    = true
    preallocate          = true
    type_checking        = "strict"
    max_dependency_depth = 10
  }

  scoring {
    mode                = "normal"
    optimization_level  = 3
    parallel_evaluation = true
    cache_size_mb       = 20
  }

  events {
    mode                = "normal"
    parallel_processing = true
    max_workers         = 4
    queue_size          = 1000
    timeout_ms          = 5000
    dedupe_window       = "250ms"
  }

  devices {
    validation_level  = "strict"
    debounce_defaults = true
  }
}

The pragma block is read from your .cade table files — not from cade.conf. Cade scans the table directory and the first pragma block it finds applies to the whole table, so keep a single pragma block in one file rather than spreading settings across several. When no table file declares one, the defaults below apply.

Global Directives

These six directives are the entire global surface. Caching, pre-allocation, and parallelism are configured per component, in the sub-blocks below.

Downgradable Error Types

These error types can be listed in errors_as_warnings:

• undefined_variable – reference to an undefined variable
• type_mismatch – type conversion errors
• unused_variable – declared but never referenced
• deprecated_usage – use of deprecated features
• overflow_risk – potential integer overflow
• expression_complexity – expression exceeds complexity limits
• performance_warning – a performance-related advisory
• style_warning – a style advisory

These checks cannot be downgraded or disabled:

• syntax_error, circular_reference, duplicate_definition, missing_required

In strict mode, syntax_error, circular_reference, and duplicate_definition cannot be listed in disable_checks.

Validation Modes

strict

All validation errors are fatal. No undefined variables allowed. No implicit type conversions. All warnings promoted to errors. Maximum runtime safety checks.

normal

Syntax errors are fatal. Type mismatches produce warnings. Undefined variables default to zero values. Basic runtime safety checks. Suitable for active development.

relaxed

Only critical syntax errors are fatal. Minimal type checking. Maximum compatibility. Minimal runtime checks. Suitable for rapid prototyping.

Optimization Levels

Component Sub-Blocks

variables

scoring

events

devices

These four sub-blocks — variables, scoring, events, and devices — are the only ones a pragma block accepts. Noise behavior is configured per stream with noise_context blocks instead — a noise_generation sub-block is rejected as not implemented.

Validation

Pragma blocks are checked when the table loads, and cade validate applies the same checks — a file that validates clean will not be rejected later by the runtime over its pragma:

• Unknown blocks are load errors at any depth. The four sub-blocks above accept only attributes, so any block nested anywhere inside pragma { } — pragma { debug { } }, or a stray block inside variables { } — is rejected with a located diagnostic rather than silently dropped.
• A malformed attribute expression is a load error. An attribute that fails to evaluate (an undefined reference, 1 + "abc") is reported with its location, instead of silently behaving as if the attribute were absent and falling back to the default.

Examples

Development Configuration

pragma {
  mode        = "normal"
  experimental = true

  errors_as_warnings = ["undefined_variable", "unused_variable"]

  variables {
    cache_expressions = false
  }

  scoring {
    optimization_level = 1
  }
}

Production Configuration

pragma {
  mode               = "strict"
  optimization_level = 2

  variables {
    cache_expressions = true
    preallocate       = true
    type_checking     = "strict"
  }

  scoring {
    optimization_level  = 3
    parallel_evaluation = true
    cache_size_mb       = 50
  }

  events {
    parallel_processing = false
  }

  devices {
    debounce_defaults  = true
    validation_level   = "strict"
  }
}

Gradual Migration

Move from legacy to strict validation in phases:

# Phase 1: Identify issues
pragma {
  mode               = "normal"
  errors_as_warnings = ["undefined_variable", "type_mismatch", "deprecated_usage"]
}

# Phase 2: Fix critical issues, remove fixed error types
pragma {
  mode               = "normal"
  errors_as_warnings = ["deprecated_usage"]
}

# Phase 3: Full strict mode
pragma {
  mode = "strict"
}

Fragment

Fragments are reusable bundles of configuration values that scoring rules pull in by name, so you define a value once and reference it from many rules. There are two kinds: static fragments hold fixed values, and dynamic fragments compute values from parameters supplied at the point of use.

Fragments are applied in score "event" rules through a fragments attribute.

Attributes

A fragment block takes two labels — the kind (static or dynamic) and the name. A small set of attributes are structural; every other attribute you set becomes a value the fragment supplies to the rules that reference it (for example points).

description, fragments, params, and variables are reserved: they configure the fragment itself and are never passed through as values. Any other attribute name is.

fragment "static" "combo_scoring" {
  description = "Shared combo-target award"
  points      = 2500
}

Static fragments

A static fragment defines fixed values under a static label and a name:

fragment "static" "combo_scoring" {
  points = 2500
}

A scoring rule that references it inherits those values:

score "event" "combo_hit" {
  when      = device.combo_target.hit
  fragments = ["static.combo_scoring"]
}

The rule above awards 2500 points on every combo target hit, with the value sourced from the fragment. Reference a static fragment by its qualified name (static.<name>) as a bare string.

Dynamic fragments

A dynamic fragment declares params and computes its values from them. Computed expressions use the expr( ... ) form:

fragment "dynamic" "scaled_points" {
  params {
    base = "int"
  }

  points = expr(var.base * 100)
}

Supply the parameters where the fragment is referenced, using the object form of a reference ({ name = ..., <param> = ... }):

score "event" "ramp_made" {
  when = device.ramp.made
  fragments = [
    { name = "dynamic.scaled_points", base = 50 },
  ]
}

Here base = 50 resolves expr(var.base * 100) to 5000 points. Expressions support arithmetic and functions such as min/max:

fragment "dynamic" "capped_combo" {
  params {
    combo = "int"
  }

  points = expr(min(var.combo * 1000, 5000))
}

params may also be written in attribute form, which is equivalent:

fragment "dynamic" "scaled_points" {
  params  = { base = "int" }
  points  = expr(var.base * 100)
}

Writing computed expressions

Use the expr( ... ) form for computed values. A bare ${ ... } is not supported here: ${ ... } is the configuration language’s own interpolation syntax, so it is evaluated when the file is loaded — before the fragment’s parameters exist — and the value is dropped (Cade logs a warning). If you prefer interpolation syntax, escape it as $${ ... }:

points = expr(var.base * 100)       # preferred
points = "$${var.base * 100}"       # equivalent (escaped interpolation)
points = "${var.base * 100}"        # WRONG — evaluated too early, value is dropped

The expr( ... ) form works quoted or unquoted — expr(var.base * 100) and "expr(var.base * 100)" behave identically.

Composition

A fragment can build on others by listing them in fragments. The composing fragment inherits their values:

fragment "static" "base_award" {
  points = 250
}

fragment "static" "ramp_award" {
  fragments = ["static.base_award"]
}

A rule that references static.ramp_award receives the inherited points = 250.

Override precedence

Values resolve in a clear order, from lowest to highest priority:

1. Values from composed fragments
2. Values from the referenced fragment
3. Explicit values set directly on the scoring rule

So an explicit value on the rule always wins over a fragment-supplied one. No special syntax is needed — set the value directly on the rule:

fragment "static" "default_award" {
  points = 100
}

score "event" "jackpot" {
  when      = device.jackpot.hit
  points    = 50000                       # wins over the fragment's 100
  fragments = ["static.default_award"]
}

Examples

Shared scoring constant

Define a point value once and reuse it across rules:

fragment "static" "standard_target" {
  points = 1000
}

score "event" "left_target" {
  when      = device.left_target.hit
  fragments = ["static.standard_target"]
}

score "event" "right_target" {
  when      = device.right_target.hit
  fragments = ["static.standard_target"]
}

Parameterized award

One dynamic fragment, different values per rule:

fragment "dynamic" "ramp_bonus" {
  params {
    level = "int"
  }

  points = expr(var.level * 2500)
}

score "event" "ramp_level_1" {
  when      = device.ramp.made
  condition = var.ramp_level == 1
  fragments = [{ name = "dynamic.ramp_bonus", level = 1 }]
}

score "event" "ramp_level_3" {
  when      = device.ramp.made
  condition = var.ramp_level == 3
  fragments = [{ name = "dynamic.ramp_bonus", level = 3 }]
}

Variable

Variables hold game state values that change during gameplay. Each variable has an explicit type, an initial value, and a scope that determines its lifetime. Variables are referenced in expressions throughout the configuration using the var. prefix.

Declaration Syntax

A variable block requires two labels: the type and the name. The body contains the initial value and optional constraints.

variable "int" "bumper_value" {
  initial = 1000
  min     = 100
  max     = 10000
  scope   = "player"
}

String, list, and map constraints are additional flat attributes on the same block — see the constraint sections below.

Types

Integer Constraints

variable "int" "bumper_value" {
  initial = 1000
  min     = 100        # Minimum allowed value
  max     = 10000      # Maximum allowed value
}

Float Constraints

variable "float" "ramp_multiplier" {
  initial = 1.0
  min     = 0.5
  max     = 10.0
}

Float variables accept integer values and promote them automatically.

String Constraints

String constraints are flat attributes written directly on the variable block — not a nested constraints {} sub-block:

variable "string" "player_code" {
  initial        = "ABC"
  scope          = "player"
  min_length     = 2                 # Minimum characters
  max_length     = 8                 # Maximum characters
  pattern        = "^[A-Z0-9]+$"     # Regex the value must match
  allowed_values = ["ABC", "XYZ"]    # Whitelist of valid values
  case_sensitive = false             # Compare values case-insensitively
}

List and Map Constraints

List and map constraints are also flat attributes on the variable block — there is no nested operations {} sub-block. max_size and min_size apply to both lists and maps; the remaining attributes are list-only:

variable "list" "combo_tags" {
  initial         = ["ramp", "loop"]
  scope           = "global"
  max_size        = 10        # Maximum elements
  min_size        = 1         # Minimum elements
  unique_elements = true      # Reject duplicate values
  allow_empty     = false     # Reject an empty list
  sorted          = true      # Keep elements sorted
}

Map Variables

variable "map" "mode_scores" {
  initial = {
    normal    = 1000
    multiball = 5000
    wizard    = 10000
  }
  scope = "player"
}

Distribution Variables

A distribution variable performs weighted random selection. Instead of an initial value, its body holds a buckets block; each bucket has a relative weight, an integer value, and a label. Selecting the variable draws a bucket at random, with higher weights chosen proportionally more often:

variable "distribution" "jackpot_fanfare" {
  scope = "player"

  buckets {
    bucket {
      weight = 60
      value  = 0
      label  = "normal_fanfare"
    }
    bucket {
      weight = 25
      value  = 1
      label  = "extended_fanfare"
    }
    bucket {
      weight = 10
      value  = 2
      label  = "epic_fanfare"
    }
    bucket {
      weight = 5
      value  = 3
      label  = "legendary_fanfare"
    }
  }
}

A bucket missing its label, or with a zero or negative weight, is skipped rather than aborting the variable — the remaining buckets still load.

Scopes

Variables have a scope that controls their lifetime and reset behavior:

If scope is omitted, the variable is unscoped and behaves as game-scoped — it resets at game start.

Scope Lifecycle

• Ball start: All ball-scoped variables reset to their initial values. Player, session, and game variables are unchanged.
• Player turn start: On a player’s first turn, both player and ball variables initialize to defaults. On subsequent turns, only ball variables reset.
• Game end: player, ball, and session variables reset to their initial values. global-scoped variables are preserved. Resets happen during the game-over phase — variable-driven lights and other dependent state clear immediately, not at the next game start.
• Game start: player, ball, and session variables reset again (idempotent safety net).

Session vs Game Scope

The session scope fills a gap between global (persists forever) and player (per-player turn). Session variables reset at game boundaries but are shared across all players within a game — they are not player-keyed. Use session for state that should survive player switches but clear when the game ends.

# Resets every ball
variable "bool" "skill_shot_active" {
  initial = true
  scope   = "ball"
}

# Persists across balls for one player
variable "int" "bonus_multiplier" {
  initial = 1
  scope   = "player"
  max     = 10
}

# Shared across players, resets each game
variable "int" "table_bonus_level" {
  initial = 0
  scope   = "session"
  max     = 5
}

# Persists across all games
variable "int" "high_score" {
  initial = 0
  scope   = "global"
}

Computed Variables

Computed variables derive their value from an expression referencing other variables. They recalculate automatically when dependencies change. Setting formula marks the variable computed even without an explicit computed = true:

variable "int" "ramp_progressive_value" {
  formula  = var.ramp_base_value + (var.ramp_count * 1000)
  computed = true
}

variable "int" "total_multiplier" {
  formula  = var.base_multiplier * var.mode_multiplier
  computed = true
}

Change Events

When a variable’s value changes, Cade emits a variable.<name>.changed event. This allows event handlers to react to variable mutations from any source — gameplay actions, lifecycle resets, or player switches.

Event Shape

The reason field indicates the mutation source:

Events are only emitted when the value actually changes — a set_variable that writes the same value produces no event.

Synchronizing Lights with Variables

The change event is particularly useful for keeping physical lights in sync with variable state. Without it, lights set by an event handler would go stale on player switches and game-end resets — the variable resets but the light stays in its last state.

An assembly can opt into synchronization by listening for the change event:

assembly "rollover_logic" {
  parameter "int" "switch_id" { required = true }
  parameter "int" "light_id"  { required = true }
  parameter "int" "points"    { default = 5000 }

  device "switch" "standard" "rollover" {
    id = param.switch_id
  }

  device "light" "standard" "lamp" {
    id = param.light_id
  }

  variable "bool" "lit" {
    initial = false
    scope   = "player"
  }

  score "event" "rollover_scored" {
    when   = device.self.rollover.hit
    points = param.points
  }

  event_handler "turn_on" {
    when      = device.self.rollover.hit
    condition = var.self.lit == false

    actions {
      toggle_variable = "self.lit"
      set_light "self.lamp" {
        state = "on"
      }
    }
  }

  event_handler "turn_off" {
    when      = device.self.rollover.hit
    condition = var.self.lit == true

    actions {
      toggle_variable = "self.lit"
      set_light "self.lamp" {
        state = "off"
      }
    }
  }

  # Re-sync light state when the variable changes for any reason
  # (game-end reset, player switch, external set)
  event_handler "sync_on" {
    when      = variable.self.lit.changed
    condition = var.self.lit == true

    actions {
      set_light "self.lamp" {
        state = "on"
      }
    }
  }

  event_handler "sync_off" {
    when      = variable.self.lit.changed
    condition = var.self.lit == false

    actions {
      set_light "self.lamp" {
        state = "off"
      }
    }
  }
}

Inside an assembly, an instance addresses its own generated blocks with the self prefix — device.self.rollover.hit, var.self.lit — so three instances of this assembly never cross-talk. See Assembly.

With this pattern:

• Game end: the player-scoped lit resets to false → the change event fires → sync_off turns the physical light off
• Player switch: P1 has lit = true, P2 has lit = false → change event fires → the light reflects the new player’s state
• Player restore: when P1’s turn resumes, lit restores to true → the light turns back on

Expression Syntax

Variable References

Variables are referenced with the var. prefix. Expression-bearing attributes take a bare expression — write it directly, with no quotes or wrapper:

points    = var.bumper_value
condition = var.skill_shot_active

Expressions with operators or multiple variables are written the same way — bare:

points    = var.base_value * var.multiplier
condition = var.loop_count >= 3

The fully-quoted form (condition = "var.loop_count >= 3") still parses for back-compat, but bare is canonical. The old ${ ... } interpolation form is no longer accepted in expression fields and is rejected at load.

Operators

# Arithmetic
+  -  *  /  %         # Basic math
**                     # Exponentiation

# Comparison
==  !=  <  >  <=  >=  # Comparisons

# Logical
&&  ||  !             # Boolean logic

# Ternary
condition ? true_value : false_value

Built-in Functions

min(a, b, ...)              # Minimum value
max(a, b, ...)              # Maximum value
abs(x)                      # Absolute value
clamp(value, min, max)      # Constrain to range
round(x, [precision])       # Round to nearest, optional decimal places
floor(x)                    # Round down
ceil(x)                     # Round up
sqrt(x)                     # Square root
pow(base, exponent)         # Exponentiation

There is no conditional function — use the ternary operator (condition ? a : b) instead.

Random, statistical, and noise functions (random, random_range, weighted_choice, normal, uniform, noise, perlin, …) are also available; see Noise Context for the seedable ones. String and list helpers are namespaced — string.length, string.concat, list.length, list.append, list.random, and so on.

Examples

Integer Percentage Multipliers

Cade uses integer-based percentage multipliers to avoid floating-point precision issues. A value of 100 represents 1.0x:

variable "int" "combo_multiplier" {
  initial = 100     # 100% = 1.0x
  min     = 100     # Never below 1.0x
  max     = 1000    # Cap at 10.0x
  scope   = "ball"
}

score "event" "bumper_hit" {
  when   = device.bumper.hit
  points = (var.bumper_value * var.combo_multiplier) / 100

  update {
    combo_multiplier = min(var.combo_multiplier + 50, 1000)
  }
}

Decaying Variables

Continuous decay uses decay_rate (a per-second amount) and produces smooth value changes toward decay_to:

variable "float" "combo_multiplier" {
  initial    = 1.0
  min        = 1.0
  max        = 10.0
  scope      = "player"

  decay_rate = 0.5    # Lose 0.5 per second
  decay_to   = 1.0    # Stop decaying at 1.0
}

For int variables, decay_rate amounts are truncated to integer before application. Decay always respects both decay_to and the variable’s min constraint — whichever is higher acts as the effective floor.

Map Access in Expressions

variable "map" "mode_scores" {
  initial = {
    normal    = 1000
    multiball = 5000
  }
  scope = "player"
}

# Access map value by key
score "event" "mode_bonus" {
  when   = device.target.hit
  points = var.mode_scores[var.current_mode]
}

Constant

A constant is a named, fixed value you define once and reference throughout your configuration by name. Unlike a variable, a constant never changes at runtime — it has no scope, no bounds, and no per-ball or per-player lifetime. Use constants for tuning values that several rules share: a base point award, a timer duration, a feature flag.

constant "int" "jackpot_base" {
  value       = 50000
  description = "Starting jackpot value, shared across modes"
}

Syntax

A constant block takes two labels — the value type and the name:

constant "<type>" "<name>" {
  value = <value>
}

Types

Attributes

A constant with no value is a configuration error.

Examples

Shared tuning values

constant "int" "ball_save_ms" {
  value       = 15000
  description = "Ball-save grace period in milliseconds"
}

constant "bool" "tournament_mode" {
  value = false
}

constant "string" "default_music" {
  value = "main_theme"
}

Reference a constant from any expression by its name, the same way you reference a variable.

Inside an assembly or module

Constants can be declared at the top level, inside an assembly body, or inside a module. A constant declared inside a module is scoped to that module.

module "multiball" {
  constant "int" "starting_balls" {
    value = 3
  }
}

Score

The scoring system defines how points are awarded, modified, and accumulated during gameplay. Scoring rules compile ahead of play, so awarding points during a game stays fast and predictable. Scoring configuration uses four block types: score "event" for event-triggered point awards, score "signal" for awards triggered by a signal completion, score "modifier" for conditional variable changes, and score "accumulator" for special-purpose score tracking like combos and jackpots.

Any other label is a load error. "event", "signal", "modifier", and "accumulator" are the only score block types. An unknown label used to be silently discarded — the file loaded, validation passed, and the block awarded nothing — but now rejects at load with a file/line/column diagnostic. In particular, score "hardware" (which older examples authored with devices = / tags = selectors and a transition =) was never implemented and is no longer accepted: author a score "event" whose when binds the device or tag group directly instead — when = tag.pop_bumpers.activated for a tags selector, when = device.left_ramp_entry.activated for a device selector (transition = "active" is the activated action).

Score Event

Score events define point awards triggered by game events. A score event block takes the label "event" and a unique name. It fires whenever the event named by when occurs and its condition (if any) evaluates true.

score "event" "ramp_complete" {
  when      = device.ramp.cleared
  condition = var.multiball_active
  points    = var.ramp_base_value * var.ramp_count
  priority  = 50
  emit      = ramp_scored

  update {
    ramp_count = var.ramp_count + 1
  }
}

Properties

trigger, signal, and event are accepted synonyms for when. Older tables commonly bind the event with trigger =, and signal = reads naturally on a score "signal" block; all four spellings load and mean the same thing. when is canonical — prefer it in new rules. If a rule carries more than one, they resolve in the fixed order when > trigger > signal > event, so the same file parses the same way every time.

Naming the event

A device event is written in three parts:

device.<identifier>.<action>

The identifier is either a device name or a device subtype — the second label of a device declaration. This is the part most worth internalizing, because a subtype scores across a whole class of devices without writing one rule per device.

Given these declarations:

device "coil" "bumper" "bumper_1" { id = 10 }
device "coil" "bumper" "bumper_2" { id = 11 }
device "coil" "bumper" "bumper_3" { id = 12 }

both of these are valid, and they mean different things:

# Subtype — fires for ANY bumper. One rule covers all three.
score "event" "bumper_hit" {
  when   = device.bumper.activated
  points = 1000
}

# Device name — fires only for that one bumper.
score "event" "left_bumper_hit" {
  when   = device.bumper_1.activated
  points = 2500
}

There is no syntax marking which kind you wrote. device.bumper.activated looks exactly like a device reference, so a rule bound to a subtype reads as though it targets a device that does not exist. It resolves, and it fires.

Binding a tag group

A rule can also bind every device carrying a tag, with the tag. prefix:

tag.<group>.<action>

Given three bumpers all declaring tags = ["pop_bumpers"]:

score "event" "pop_hit" {
  when   = tag.pop_bumpers.activated
  points = 750
}

fires whenever any of them is hit. Prefer a shared tag over an expanded device list when several devices should score identically — it keeps one rule per concept, and adding a device to the group later is a one-line tags edit.

Two shapes near this one do not bind, deliberately:

• device.tag.<group>.<action> (four segments) is rejected at load — the correct spelling is tag.<group>.<action>.
• device.<group>.<action> where <group> is only a tag does not match — the device. prefix resolves names and subtypes, the tag. prefix resolves groups. A device literally named tag is still bindable as device.tag.<action>.

Precedence. A device event fires exactly one rule, chosen by specificity: name > tag > subtype. Explicit beats implicit — a name designates exactly one device, a tag is a group the author deliberately opted the device into, and a subtype is structural (every bumper has it whether or not scoring was on the author’s mind). The winner takes the device wholesale: lower-specificity rules contribute nothing for that device, even for actions the winner does not cover. There is no fan-out — a device never fires both its own rule and its group’s.

When a device belongs to two tagged groups that both have a rule, the lexicographically first tag wins (the order you wrote the tags = [...] list does not matter — it reads as an unordered set). Cade logs a warning at load whenever a tag group is shadowed or does the shadowing — for example when a device that already has its own named rule joins a tagged group and silently stops contributing to the group award — so check the log if a group rule seems to skip a member.

Event actions

The action is the third segment, and it comes from a fixed vocabulary. The mapping below is what the Visual Pinball driver understands:

An unrecognized action silently falls back to hit. A typo such as device.spinner.spinn does not fail to load and does not warn — it quietly binds to the hit event instead. If a rule fires on the wrong edge, or fires when you expected nothing, check the action spelling against the table above first.

Nested blocks

An update block assigns new values to variables after the award is applied — the right-hand side is an expression evaluated with current game state in scope:

update {
  ramp_count       = var.ramp_count + 1
  combo_multiplier = min(var.combo_multiplier + 50, 1000)
}

A structured condition block accepts all_of / any_of lists as an alternative to the scalar condition attribute:

condition {
  any_of = [
    var.combo_multiplier >= 300,
    mode.wizard.active,
  ]
}

To make a scoring rule play a sound, author a top-level route{} (and, if the rule has more than one candidate clip, a selection{}) that names the rule as its owner. A nested audio {} block under a score block no longer parses:

route {
  owners = [score.ramp_complete]
  source "audio_clip" "ramp_award" { weight = 1 }
}

See Routing and selection.

Score Signal

A score "signal" block is the same rule shape as score "event" — the same attributes, the same update block — with a label that documents intent: the rule scores off a signal completion rather than a raw device event. Bind the completion event with signal = (or any of the other synonyms):

signal "shot" "left_orbit" {
  switches    = [orbit_entry, orbit_exit]
  time_window = "3s"
}

score "signal" "orbit_award" {
  signal = shot.left_orbit.complete
  points = var.orbit_value * var.combo_multiplier / 100

  update {
    orbit_count = var.orbit_count + 1
  }
}

Score Modifier

Modifiers change variable values based on conditions or timers. They do not award points directly. A score modifier block takes the label "modifier" and a unique name.

score "modifier" "multiball_bonus" {
  type      = "conditional"
  condition = mode.multiball.active

  apply {
    bumper_value = var.bumper_value * 2
  }
}

Properties

The variable changes go in an apply block (modify is accepted as a synonym). A modifier makes sound the same way a score event does — a top-level route{} with owners = [modifier.<name>].

Examples

# Conditional modifier: doubles values during multiball
score "modifier" "multiball_bonus" {
  condition = mode.multiball.active

  apply {
    bumper_value    = var.bumper_value * 2
    slingshot_value = var.slingshot_value * 2
    base_multiplier = 200
  }
}

# Timer modifier: decays combo multiplier every second
score "modifier" "combo_decay" {
  type     = "timer"
  interval = "1s"

  apply {
    combo_multiplier = max(var.combo_multiplier - 10, 100)
  }
}

# Event-triggered modifier: resets state on ball start
score "modifier" "ball_start_reset" {
  when = game.ball_start

  apply {
    skill_shot_active = true
    combo_multiplier  = 100
    ramp_count        = 0
  }
}

Score Accumulator

Accumulators track score across multiple events using patterns like sequences, progressive jackpots, and thresholds. A score accumulator block takes the label "accumulator" and a unique name.

score "accumulator" "bumper_combo" {
  type   = "sequence"
  events = ["bumper.*"]
  window = "5s"

  on_collect         = game.combo_collected
  collect_multiplier = var.combo_multiplier
  reset_on_collect   = true

  on_increment {
    update {
      combo_count = "var.combo_count + 1"
    }
  }

  on_break {
    update {
      combo_count = "0"
    }
  }
}

Accumulator expressions must be quoted. Unlike score "event" and score "modifier" — where points, condition, and update values are written bare — an accumulator reads its expression-valued fields as plain values. A bare reference such as collect_multiplier = var.combo_multiplier resolves, but anything containing an operator or a call (var.combo_count + 1, score_event.value >= 5000) does not: it is silently dropped and the field behaves as if it were never set. Write those in quotes. This applies to filter, contribute_when, collect_multiplier, and every value inside an on_increment / on_break update {} block — including bare numbers, so use combo_count = "0", not combo_count = 0.

Accumulator Types

Properties

Nested blocks

An on_increment block runs each time the accumulator advances, and on_break runs when a sequence is interrupted. Each holds an update block that assigns variables — quoted, per the note above:

on_increment {
  update {
    combo_count = "var.combo_count + 1"
  }
}

An accumulator makes sound the same way a score event does — a top-level route{} with owners = [accumulator.<name>].

Examples

Basic Scoring

variable "int" "bumper_value" {
  initial = 1000
  min     = 100
  max     = 10000
}

variable "int" "slingshot_value" {
  initial = 500
  min     = 100
  max     = 5000
}

score "event" "bumper_hit" {
  when   = device.bumper.hit
  points = var.bumper_value
}

score "event" "slingshot_hit" {
  when   = device.slingshot.hit
  points = var.slingshot_value
}

Progressive Scoring

variable "int" "combo_multiplier" {
  initial = 100
  min     = 100
  max     = 1000
  scope   = "ball"
}

variable "int" "ramp_count" {
  initial = 0
  scope   = "ball"
}

variable "int" "ramp_base_value" {
  initial = 5000
}

score "event" "ramp_shot" {
  when   = device.ramp.cleared
  points = (var.ramp_base_value + (var.ramp_count * 1000)) * var.combo_multiplier / 100

  update {
    ramp_count       = var.ramp_count + 1
    combo_multiplier = min(var.combo_multiplier + 50, 1000)
  }
}

Sequence Accumulator

variable "int" "combo_count" {
  initial = 0
  scope   = "ball"
}

score "accumulator" "bumper_combo" {
  type   = "sequence"
  events = ["bumper.*"]
  window = "5s"

  on_increment {
    update {
      combo_count = "var.combo_count + 1"
    }
  }

  on_break {
    update {
      combo_count = "0"
    }
  }
}

Progressive Jackpot

score "accumulator" "super_jackpot" {
  type               = "progressive"
  contribute_percent = 5
  contribute_when    = "score_event.value >= 5000"

  on_collect         = game.super_jackpot_collected
  collect_multiplier = var.combo_multiplier
  reset_on_collect   = true
}

Signal

A signal detects a pattern of device activity — an ordered shot through a sequence of switches, a combo of completed shots, or a bank of targets all knocked down — and emits a completion event when the pattern is satisfied. Other rules (scoring, event handlers, modes) subscribe to that event.

signal "shot" "left_orbit" {
  switches    = [orbit_entry, orbit_exit]
  time_window = "3s"
  points      = 2000
}

When the ball trips orbit_entry then orbit_exit within three seconds, the signal completes and awards 2000 points.

Syntax

A signal block takes two labels — the signal type and the name:

signal "<type>" "<name>" {
  # ...
}

Signal types

Attributes

Quote points and each_switch_points when they compute. A plain number (points = 2000) works bare, and so does a lone reference (points = var.jackpot). But an expression containing an operator or a call must be written as a quoted string — points = "25000 * var.combo_multiplier". Left bare, it is silently dropped and the signal awards nothing. enabled is the exception: it accepts a bare expression (enabled = var.tournament == false).

Completion handlers

A signal may carry nested action blocks that fire at lifecycle points:

signal "combo" "super_combo" {
  signals     = [shot.left_ramp.complete, shot.left_orbit.complete]
  time_window = "5s"

  on_complete {
    emit = combo.super_combo.complete
  }
}

A signal may also carry a validation block that rejects physically impossible input. Its min_time attribute sets the shortest allowed gap between steps — a sequence completed faster than this is discarded:

signal "shot" "left_ramp" {
  switches = [ramp_entry, ramp_exit]

  validation {
    min_time = "80ms"
  }
}

Completion events

Each signal emits a completion event named <type>.<name>.complete — for example shot.left_orbit.complete or bank.drop_targets.complete. Subscribe to it from a scoring rule or event handler:

score "event" "orbit_award" {
  when   = shot.left_orbit.complete
  points = 5000
}

To emit a custom event name instead, set emit inside on_complete.

Examples

One-way ramp shot

A shot that only counts in the forward direction:

signal "shot" "left_ramp" {
  switches   = [ramp_entry, ramp_exit]
  reversible = false
  points     = 1500
}

Drop-target bank

Complete when every drop target in the bank is down:

signal "bank" "drop_targets_complete" {
  all_down = ["drop_1", "drop_2", "drop_3"]
  points   = 10000
}

Expression-valued points

Scale the award by a runtime multiplier. An expression that contains an operator must be quoted — see the note under Attributes:

signal "combo" "mega_combo" {
  signals     = [shot.left_ramp.complete, shot.center_ramp.complete, shot.right_ramp.complete]
  time_window = "10s"
  points      = "25000 * var.combo_multiplier"
}

Replay

A replay awards the player something — a credit or an extra ball — when their score crosses a threshold, the classic “free game for a high score” of mechanical and solid-state pinball. Define the thresholds once with a top-level replay block and the runtime grants the award and fires an event each time a player passes one.

replay {
  max_per_game = 1

  threshold {
    score  = 5000000
    reward = "credit"
  }

  threshold {
    score  = 15000000
    reward = "extra_ball"
  }
}

Syntax

The replay block takes no label — a table has one:

replay {
  max_per_game = <n>
  threshold {
    score  = <n>
    reward = "<type>"
  }
  # ... more thresholds
}

Attributes

Thresholds

Each threshold block defines one score level and the reward granted when a player’s score crosses it. List as many as you need; they are evaluated independently.

reward must be "credit" or "extra_ball" — any other value is a configuration error.

Award event

When a player crosses a threshold, the runtime grants the reward and emits a system.replay.award event. Subscribe to it from an event handler to react — flash a lamp, play a fanfare, or update a display:

event_handler "replay_celebration" {
  when = system.replay.award

  actions {
    flash_light "replay_lamp"
  }
}

Examples

Single replay at a fixed score

replay {
  max_per_game = 1

  threshold {
    score  = 2000000
    reward = "credit"
  }
}

Tiered rewards

Award a credit at the first level and an extra ball at a higher one, with no per-game cap:

replay {
  threshold {
    score  = 1000000
    reward = "credit"
  }

  threshold {
    score  = 3000000
    reward = "extra_ball"
  }
}

Global Events

The global_events block declares the table-wide events your machine recognizes, optionally giving each one a priority. Think of it as a catalog — one place to name the events that flow through the game (flipper presses, plunger fires, nudges, custom game events).

It does not define what happens when an event fires. A global event performs no action on its own; declaring it registers the name (and priority) with the engine. To react to an event, pair it with an event handler or a scoring rule.

global_events {
  left_flipper_press {
    description = "Left flipper button pressed"
    priority    = 100
  }

  plunger_fire {
    description = "Plunger released"
  }
}

Syntax

Each event is a block whose name is the event name — there is no quoted label and no leading keyword:

global_events {
  <event_name> {
    description = "<text>"   # optional
    priority    = <int>      # optional
  }

  # ... more events ...
}

Attributes

Each event entry accepts two optional keys; any other key is ignored.

Examples

Cataloging input events

The common use is a single block that names the physical inputs and physics events a table produces, so they read as one catalog. priority is optional — omit it and the event defaults to 100:

global_events {

  # --- Flipper control ---
  left_flipper_press {
    description = "Left flipper button pressed"
    priority    = 100
  }

  left_flipper_release {
    description = "Left flipper button released"
    priority    = 100
  }

  left_flipper_collide {
    description = "Ball collided with left flipper"
  }

  # --- Plunger ---
  plunger_fire {
    description = "Plunger released"
  }
}

Event naming conventions

Events follow a hierarchical dot-separated naming pattern:

Device vs signal suffixes

Device events use action-specific suffixes based on device type:

Coils, lights, flippers, and ball devices produce no device event of their own.

Signal events use the .complete suffix for higher-level pattern detection:

signal.shot.left_orbit.complete
signal.combo.super_jackpot.complete

Variable change events

Variable events use the pattern variable.<name>.changed and are emitted automatically whenever a variable’s value changes. The event carries a payload with name, old, new, scope, and reason fields. See Variable — Change Events for the full event shape and usage examples.

variable.l6_lit.changed            # Boolean rollover light state changed
variable.bonus_multiplier.changed  # Player multiplier updated

Related blocks

Legacy aliases

global_events is the current spelling. Two older forms still parse for backward compatibility and behave identically:

• global_event { ... } — singular block name
• event { ... } — bare singular

Prefer global_events in new tables.

Event Flow

A flow block orchestrates relationships between events over time — a sequence that must occur in order, a set that can be completed in any order, and so on. When the flow’s condition is met it fires an on_complete callback; if a time window is set and expires first, it fires on_timeout.

flow "sequence" "skill_shot" {
  events = ["ball_plunged", "upper_loop", "skill_target"]
  window = "3s"

  on_complete {
    emit   = skill_shot_made
    points = 25000
  }

  on_timeout {
    emit = skill_shot_missed
  }
}

Syntax

A flow block takes two labels — its type and its name:

flow "<type>" "<name>" {
  events = ["<event>", ...]   # events the flow watches
  window = "<duration>"       # optional time limit, e.g. "3s"

  on_complete { ... }
  on_timeout  { ... }
}

Flow types

The first label selects the matching strategy:

An unknown type is a parse error.

Attributes

Blocks

Each callback accepts:

Examples

Sequence flow

Events must occur in a specific order within a time window:

flow "sequence" "skill_shot" {
  events = ["ball_plunged", "upper_loop", "skill_target"]
  window = "3s"

  on_complete {
    emit   = skill_shot_made
    points = 25000
  }

  on_timeout {
    emit = skill_shot_missed
  }
}

Parallel flow

Events can occur in any order to complete a set:

flow "parallel" "drop_target_bank" {
  events = ["drop_1", "drop_2", "drop_3", "drop_4"]
  window = "30s"

  on_complete {
    emit   = bank_cleared
    points = 10000
  }
}

Related blocks

Event Handler

An event handler runs a block of actions in response to an event. Where a scoring rule is built around awarding points, an event handler is the general-purpose reaction: pulse a coil, set a variable, play a sound, emit another event.

event_handler "launch_ball" {
  when = device.plunger.released

  actions {
    pulse_coil "trough_eject" {}
  }
}