The SkeletonGame Event System

A major goal of SkeletonGame is to keep you from having to wrestle with implementing the logic that controls the typical pinball game state stuff (e.g., is a ball starting? stopping? drained? tilting?). The idea is that the majority of your code can live in “modes” and your modes will be notified about these game-play events firing. To be notified of these events, your mode should provide a method with the same name as the event, and your mode needs to be active (unless otherwise noted in the table). Your mode will be notified of the event by the framework calling your method. Modes with higher priority will receive the event first. Returning a number (of seconds) will slow the event propagation so that your mode can do whatever it needs to without interruption from a lower event. If an argument is specified, your method can receive that argument and use it to gain additional information about the specific event.

The following table summarizes the current events supported in SkeletonGame (dev branch) as of 3/18/2017:

event name	fired when…	return value delays…
evt_balls_missing	the trough reports insufficient balls, blocking the start of a game	no next function, so return value is irrelevant
evt_balls_found	a previous search for balls (that had blocked game start) has been resolved	nothing to delay
evt_game_starting	the user has pressed start from attract mode	return value delays the actual start of the game
evt_player_added$	called every time a player is added to the game. Will be called at least once (after evt_game_starting); argument is the newly created player	no delay
evt_ball_starting	called when a ball is about to start for a player (prior to the ball being placed in the shooter-lane, flipers being enabled, etc)	return value delays the actual start of the ball
evt_ball_saved	The moment a ball has been saved by the ball saver	no delay
evt_shoot_again$	a ball has drained but an extra ball is available; NOTE: evt_ball_starting WILL fire after this as a ball will be starting after this	delays the start of the ball
evt_ball_ending	the final “in-play” ball has drained; args=(shoot_again,last_ball) to indicate if the player has any extra balls, and/or if this is the player’s last ball.	the end ball process, which will initiate a bonus tally and eventually start the next ball
evt_tilt_ball_ending	ALTERNATIVE to evt_ball_ending when the game has been tilted. evt_ball_ending will NOT fire. This event indicates all balls are back. Good place to admonish the player (note that evt_tilt will have fired before this, if not also evt_tilt_warning)	either end of this ball or slam_tilt complete (game reset)
evt_single_ball_play	called when the number of balls in play decreases to 1. Indicates the game is no longer in a multiball mode	No return value
evt_tilt_warning	tilt switch has been tripped; arg is number of times the player has been warned	nothing
evt_game_ending	the game has ended. All balls are done. Will also fire following a slam-tilt	the game ending sequence follows; fire high score entry, then game ended
evt_initial_entry	if the player has been awarded a high score of some sort; this event will fire before each individual high score entry prompt. Arg is the category record of the specific award. This event may potentially multiple times after each entry has been entered.	blocks the actual entry of initials
evt_game_ended	after high score entry is complete (will fire even if high score entry does not occur)	this delays the call to reset() that puts the machine in a clean state before the start of the next game
evt_tilt	if the player has tilted the machine. the arg is a boolean indicating if the machine was slam tilted (True) or not (False)	n/a
evt_volume_up	the volume has been changed. Use this event to show something custom to the player. The arg is the system volume as an integer (0..10).	n/a
evt_volume_down	the volume has been changed. Use this event to show something custom to the player. The arg is the system volume as an integer (0..10).	n/a

$ –> means even inactive modes will receive this event.