class mpf.devices.ball_device.ball_device.BallDevice(*args, **kwargs)

Bases: mpf.core.system_wide_device.SystemWideDevice

Base class for a ‘Ball Device’ in a pinball machine.

A ball device is anything that can hold one or more balls, such as a trough, an eject hole, a VUK, a catapult, etc.

Args: Same as Device.

Accessing ball_devices in code

The device collection which contains the ball_devices in your machine is available via self.machine.ball_devices. For example, to access one called “foo”, you would use You can also access ball_devices in dictionary form, e.g. self.machine.ball_devices['foo'].

You can also get devices by tag or hardware number. See the DeviceCollection documentation for details.

Methods & Attributes

Ball_devices have the following methods & attributes available. Note that methods & attributes inherited from base classes are not included here.

add_incoming_ball(incoming_ball: mpf.devices.ball_device.incoming_balls_handler.IncomingBall)

Notify this device that there is a ball heading its way.

available_balls = None

Number of balls that are available to be ejected. This differs from balls since it’s possible that this device could have balls that are being used for some other eject, and thus not available.


Return the number of balls we expect in the near future.

cancel_path_if_target_is(start, target)

Check if the ball is going to a certain target and cancel the path in that case.


Return the ball capacity.

eject(balls=1, target=None, **kwargs) → int

Eject balls to target.

Return the number of balls found for eject. The remaining balls are queued for eject when available.

eject_all(target=None, **kwargs)

Eject all the balls from this device.

  • target – The string or BallDevice target for this eject. Default of None means playfield.
  • **kwargs – unused

True if there are balls to eject. False if this device is empty.


Event handler for entrance events.


Handle an expected ball.


Try to remove available ball at the end of the path.


Find next trough after device.


Find a path to a source device which has at least one available ball.


Find a path to this target.


Handle mechanical eject.


Event handler for hold event.

classmethod is_playfield()

Return True if this ball device is a Playfield-type device, False if it’s a regular ball device.


Handle an outgoing lost ball.


Lost an ball while the device was idle.


Handle lost ball which was confirmed to have left source.

raise_config_error(msg, error_no, *, context=None)

Raise a ConfigFileError exception.

remove_incoming_ball(incoming_ball: mpf.devices.ball_device.incoming_balls_handler.IncomingBall)

Remove a ball from the incoming balls queue.

request_ball(balls=1, **kwargs)

Request that one or more balls is added to this device.

  • balls – Integer of the number of balls that should be added to this device. A value of -1 will cause this device to try to fill itself.
  • **kwargs – unused

Return the number of requested balls.


Set the current device state.

setup_eject_chain(path, player_controlled=False)

Set up an eject chain.

setup_eject_chain_next_hop(path, player_controlled)

Set up one hop of the eject chain.


Set up a player controlled eject.


Return the device state.


Stop device.


Handle an unexpected ball.


Wait until this device is ready to receive a ball.