Visual Pinball

Visual Pinball Driver (gRPC)

The gRPC driver bridges Cade to Visual Pinball X (VPX) and other gRPC-capable clients. External simulators send switch events into Cade and receive coil, light, flipper, and autofire commands back over a bidirectional event stream, so you can run a full Cade configuration against a simulated table without any physical hardware.

How Events Flow

• Inbound (simulator to Cade): switch activations, ball-device captures, and other input events are sent from the client. Cade treats them exactly like events from a physical driver.
• Outbound (Cade to simulator): coil, light, flipper, and autofire commands are streamed back to every connected client, so the simulator mirrors what Cade would drive on real hardware.

Because inbound events flow through the same path as physical hardware events, scoring and game logic behave identically whether you are running on hardware or against VPX.

Hybrid Control Model

Flippers and autofire rules use a hybrid control model:

• VPX handles physics locally for zero-latency response. The client processes flipper button presses and autofire triggers (bumpers, slingshots) directly within the simulator.
• Cade controls the lifecycle. Cade sends enable/disable commands — for example, flippers are enabled at ball start and disabled on tilt — and receives the resulting flipper and autofire events for scoring and state tracking.

This split keeps the simulator responsive while keeping game-state management centralised in Cade.

Configuration

The gRPC driver is configured in a platform block within your Cade configuration file.

platform "grpc" "vpx" {
  port              = 50051
  enable_gateway    = true
  enable_reflection = true
  enable_tls        = false
  enable_cors       = true
}

Properties

Supported Capabilities

The gRPC driver supports the core device capabilities you would find on a physical platform:

• Switches. Switch events are received from the client. No pre-configuration is required — switches are registered dynamically as events arrive.
• Coils. Pulse, enable, and disable commands are streamed to the client.
• Lights. Set, off, flash, and fade commands are streamed to the client, including batch updates for atomic delivery within a single simulator frame.
• Flippers. Enable/disable lifecycle is managed by Cade; the client handles physics locally.
• Autofire rules. Enable/disable lifecycle is managed by Cade; the client handles bumper/slingshot physics locally.
• REST gateway. When enable_gateway is on, the driver exposes the same operations over HTTP for tooling and dashboards.

Platform Capabilities

Ball Device Commands

Cade distinguishes two ball-device operations so score and ball-in-play counters stay consistent:

• eject_ball — creates a new ball and kicks it. A held ball is not required. Angle and strength are carried on the command.
• kick_ball — fires an already-held ball without creating a new one and without incrementing the ball-in-play counter. Angle and strength for kicks are configured once per kicker and applied by the client.

If the client receives a kick_ball for a kicker with no ball held, it logs a warning and ignores the command.

Getting Started

Cade includes example clients and a sample VPX table configuration in the source repository:

• examples/grpc_event_client/ – A reference gRPC event client with implementations in Go and Python.
• examples/vpinball_example_table/ – A sample VPX table with a Cade configuration file.

To connect a gRPC client:

1. Configure the gRPC driver in your Cade configuration file with the desired port.
2. Start Cade. The gRPC server begins listening on the configured port.
3. Connect your client to the gRPC server and establish a bidirectional event stream.
4. The client sends switch events to Cade and receives device commands back.