Cade Runtime

First Steps with Cade

tutorial onboarding first-table scoring

First Steps with Cade

Level BeginnerTime 15 min

You’ll write the three pieces every table is built from — a device, a variable, and a scoring rule — and wire them together so one target awards points when it’s hit. By the end you’ll validate it, run it, and watch it score in the interactive console.

Before you start: have the cade binary on your PATH. If you don’t yet, walk through Getting Started first — it covers installing and verifying Cade. Everything else you need is below.

A table is a .cade file written in HCL that describes your machine — its devices, its variables, and the rules that turn play into points. We’ll add those three pieces one at a time, and run the table at the end to see them work together.

Create the table file and a device

Create a file named my-first-table.cade with a name, a version, and a single device — a switch standing in for a standup target:

my-first-table.cade
name    = "My First Table"
version = "0.1.0"

# A switch that represents a standup target on the playfield.
device "switch" "target" "pop_target" {
  id   = 54
  tags = ["standup", "playfield"]
}

Hold the point value in a variable

Add a variable that stores how much a target hit is worth:

my-first-table.cade
# Track the points a target hit is worth.
variable "int" "target_value" {
  initial = 1000
  min     = 100
  max     = 10000
  scope   = "global"
}

Score the hit

Now connect the device to the variable with a scoring rule. Add this block:

my-first-table.cade
# Award points each time the target is hit.
score "event" "target_hit" {
  when   = device.pop_target.hit      # the event that fires this rule
  points = var.target_value           # how many points to award
}

Your complete my-first-table.cade is now those three blocks together — a device, a variable, and a rule that ties them.

Validate it

Before running, check the file for syntax errors, missing references, and type mismatches:

cade validate my-first-table.cade
Checkpoint
Validation prints no errors. If it reports an unresolved reference, make sure the name in device.pop_target.hit matches the device’s name (pop_target), and that var.target_value matches the variable’s name. A mismatch here is the most common first-table slip.

Run it and watch it score

Launch the interactive console from the directory containing your table:

cade console

The console loads your table and drops you at a prompt where you can fire events and inspect state by hand — the quickest way to confirm a rule works without real hardware. Trigger the target’s hit event, then inspect the score:

cade:debug> trigger device.pop_target.hit
  → scored +1000  (score "target_hit")

cade:debug> inspect target_value
  target_value = 1000   [global]

cade:debug> eval ${target_value} * 2
  2000
Checkpoint
Triggering device.pop_target.hit reports +1000 and the player score goes up by the value of target_value. That’s the full loop working: a device event fired your rule, and the rule read your variable to award points.

The complete file

Here’s my-first-table.cade in full — the three blocks you added, together:

my-first-table.cade
name    = "My First Table"
version = "0.1.0"

# A switch that represents a standup target on the playfield.
device "switch" "target" "pop_target" {
  id   = 54
  tags = ["standup", "playfield"]
}

# Track the points a target hit is worth.
variable "int" "target_value" {
  initial = 1000
  min     = 100
  max     = 10000
  scope   = "global"
}

# Award points each time the target is hit.
score "event" "target_hit" {
  when   = device.pop_target.hit      # the event that fires this rule
  points = var.target_value           # how many points to award
}

Where to go next

You’ve built the smallest complete table there is: a device, a variable, and a rule. Everything else is more of the same shape.

  • Learn the building blocks — Table Design Basics goes deeper on scoring rules and introduces modes, the other half of most tables.
  • Grab ready-made features — Recipes has copy-paste blocks for bumpers, multiball, combos, and multipliers to drop into this table.
  • See every option — the Score reference and Variable reference document the full set of attributes.