Getting Started

Getting Started

This guide walks you through installing Cade, writing your first table configuration, and exploring it in the interactive console.

Prerequisites

Cade is currently distributed as a prebuilt binary. To request access, reach out to John Dittmar on GitHub.

Verify your install:

cade --version

Your First Table

A table configuration is a .cade file written in HCL that describes your machine: its devices, events, variables, and scoring rules. Cade looks for .cade files in the current directory (or in a directory passed with -d).

Create a file named my-first-table.cade:

name    = "My First Table"
version = "0.1.0"

# A single switch that represents a pop bumper.
device "switch" "bumper" "pop_bumper_1" {
  id = 0x40

  debounce {
    activate_ms = 2
  }

  tags = ["pop_bumper", "playfield"]
}

# Track how many times the bumper has been hit.
variable "int" "bumper_hits" {
  initial = 0
  scope   = "ball"
}

# Score 100 points per hit and bump the counter.
score "event" "bumper_hit" {
  when   = device.pop_bumper_1.activated
  points = 100

  update {
    bumper_hits = var.bumper_hits + 1
  }
}

Validate the Configuration

Before running the table, check it for syntax errors, missing references, and structural issues:

cade validate my-first-table.cade

Validate every .cade file in the current directory:

cade validate

Validation reports missing references, type mismatches, circular dependencies, and more. See the configuration reference for the full set of blocks available inside a .cade file.

Run the Table

Launch Cade from the directory containing your table:

cade

By default, Cade loads every .cade file it finds in the current directory. To search subdirectories, pass -r:

cade -r

To point at a specific directory:

cade -d examples/

Explore in the Console

The interactive console is the quickest way to experiment with a table. It evaluates expressions, triggers events, inspects variables, and shows real-time state in a multi-panel TUI.

cade console --config my-first-table.cade

At the cade:debug> prompt you can:

See the console overview for a full tour of the panels, commands, and keyboard shortcuts.

Optional: Runtime Configuration

Table files describe what your machine is. A separate runtime configuration file, cade.conf, describes how to run it — which platform driver to use, whether to start the web server, and so on. Cade looks for cade.conf in the current directory or at $XDG_CONFIG_HOME/cade/cade.conf.

A minimal cade.conf that enables the web dashboard on port 8080:

web {
  enabled = true
  health {
    enabled = true
  }
}

logging {
  level = "info"
}

To bridge Cade to Visual Pinball X (or any gRPC-speaking front-end), declare a platform "grpc" block:

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

See the Cade config reference for every available setting.

Where to Go Next