The ball tracker also generates new per-device events. The name of
the event includes the name of the device: for example,
dev_trough_enter.
The enter event is generated when the current count goes up by 1. Game code should normally always register handlers for the enter events rather than individual switches. Note that a switch closure does not always indicate enter: consider an eject that is trying to kick out but the kicker is weak, so that the ball falls back in immediately. Also, when a ball trough releases a ball, a whole series of switch closures occur rapidly, but eventually it stabilizes. The ball tracker waits a little while after switch change before it begins to take action.
When a release is necessary, the module first generates a kick_request event. This is a boolean event; handlers can return FALSE if the request should be postponed for some reason. In that case, the module will retry again later. Once the request is allowed, a kick_attempt event is generated just before the solenoid is pulsed. This is typically caught in order to play a sound effect. If the pulse fails, the attempt event may be thrown multiple times.
The kick_success event is generated when the release is deemed successful: when the device count goes down by 1. The kick_failure event is instead thrown when an attempts fails repeatedly and the device is abandoned.