Starting Multiball

Multiball is a mode that begins when an extra ball is put into play and ends when play returns to a single ball. The pieces are: a mode to represent the multiball state, an action that ejects the extra ball, and a rule that ends the mode when the balls drain.

The multiball mode

Declare the mode inside a module so it owns its own rules and state. stop_events lists the events that end it:

module "multiball" {
  mode {
    priority    = 200
    stop_events = ["multiball.ended"]
  }
}

Starting it

When the lock kicker fires, eject a ball, bump the in-play count, and start the mode:

event_handler "lock_kicker_hit" {
  when = device.lock_kicker.activated
  actions {
    eject_ball {
      device   = ball_release
      angle    = 90
      strength = 8
    }
    increment  = "balls_in_play"
    start_mode = "multiball"
  }
}

eject_ball creates and launches a new ball; use kick_ball instead when a ball is already held and you only want to fire it without changing the count.

Ending it

When a drain brings play back down to the last ball, emit the event that the mode listens for:

event_handler "multiball_drain" {
  when      = device.drain.activated
  condition = mode.multiball.active && var.balls_in_play <= 1
  actions {
    emit = multiball.ended
  }
}

How it works

Multiball leans on the ball lifecycle (system.ball.* / system.play.* events) and the eject-vs-kick distinction. For the full lifecycle and how Cade tracks balls in play, see Multiball and Ball Lifecycle Events. For how modes are scoped to modules, see Organizing Modes into Modules.