self.machine.modes.game

class mpf.modes.game.code.game.Game(machine, config, name, path)

Bases: mpf.core.mode.Mode

Base mode that runs an active game on a pinball machine.

Responsible for creating players, starting and ending balls, rotating to the next player, etc.

Accessing the game mode via code

You can access the game mode from anywhere via self.machine.modes.game.

Methods & Attributes

The game mode has the following methods & attributes available. Note that methods & attributes inherited from the base Mode class are not included here.

active

Return true if mode is active.

add_mode_event_handler(event, handler, priority=0, **kwargs)

Register an event handler which is automatically removed when this mode stops.

This method is similar to the Event Manager's add_handler() method, except this method automatically unregisters the handlers when the mode ends.

Parameters:
  • event -- String name of the event you're adding a handler for. Since events are text strings, they don't have to be pre-defined.
  • handler -- The method that will be called when the event is fired.
  • priority -- An arbitrary integer value that defines what order the handlers will be called in. The default is 1, so if you have a handler that you want to be called first, add it here with a priority of 2. (Or 3 or 10 or 100000.) The numbers don't matter. They're called from highest to lowest. (i.e. priority 100 is called before priority 1.)
  • **kwargs -- Any any additional keyword/argument pairs entered here will be attached to the handler and called whenever that handler is called. Note these are in addition to kwargs that could be passed as part of the event post. If there's a conflict, the event-level ones will win.
Returns:

A GUID reference to the handler which you can use to later remove the handler via remove_handler_by_key. Though you don't need to remove the handler since the whole point of this method is they're automatically removed when the mode stops.

Note that if you do add a handler via this method and then remove it manually, that's ok too.

award_extra_ball()

Called when the same player should shoot again.

ball_drained(balls=0, **kwargs)

Ball drained.

ball_ended(ev_result=True, **kwargs)

Called when the ball has successfully ended.

This method is called after all the registered handlers of the queue event ball_ended finish. (So typically this means that animations have finished, etc.)

This method also decides if the same player should shoot again (if there's an extra ball) or whether the machine controller should rotate to the next player. It will also end the game if all players and balls are done.

ball_ending()

Start the ball ending process.

This method posts the queue event ball_ending, giving other modules an opportunity to finish up whatever they need to do before the ball ends. Once all the registered handlers for that event have finished, this method calls ball_ended().

Currently this method also disables the autofire_coils and flippers, though that's temporary as we'll move those into config file options.

ball_started(ev_result=True, **kwargs)

Ball started.

ball_starting(is_extra_ball=False)

Called when a new ball is starting.

Note this method is called for each ball that starts, even if it's after a Shoot Again scenario for the same player.

Posts a queue event called ball_starting, giving other modules the opportunity to do things before the ball actually starts. Once that event is clear, this method calls ball_started().

balls_in_play

Return balls in play.

configure_logging(logger, console_level='basic', file_level='basic')

Configure the logging for the module this class is mixed into.

Parameters:
  • logger -- The string name of the logger to use
  • console_level -- The level of logging for the console. Valid options are "none", "basic", or "full".
  • file_level -- The level of logging for the console. Valid options are "none", "basic", or "full".
debug_log(msg, *args, **kwargs)

Log a message at the debug level.

Note that whether this message shows up in the console or log file is controlled by the settings used with configure_logging().

error_log(msg, *args, **kwargs)

Log a message at the error level.

These messages will always be shown in the console and the log file.

game_ended(**kwargs)

Actually ends the game once the game_ending event is clear.

Eventually this method will do lots of things. For now it just advances the machine flow which ends the Game mode and starts the Attract mode.

game_ending()

Called when the game decides it should end.

This method posts the queue event game_ending, giving other modules an opportunity to finish up whatever they need to do before the game ends. Once all the registered handlers for that event have finished, this method calls game_end().

game_started(ev_result=True, **kwargs)

All the modules that needed to do something on game start are done, so our game is officially 'started'.

info_log(msg, *args, **kwargs)

Log a message at the info level.

Whether this message shows up in the console or log file is controlled by the settings used with configure_logging().

player_add_success(player, **kwargs)

Called when a new player is successfully added to the current game.

This includes when the first player is added.

player_rotate()

Rotate the game to the next player.

This method is called after a player's turn is over, so it's even used in single-player games between balls.

All it does really is set player to the next player's number.

Args:

player_turn_start()

Called at the beginning of a player's turn.

Note this method is only called when a new player is first up. So if the same player shoots again due to an extra ball, this method is not called again.

player_turn_stop()

Called when player turn stopped.

request_player_add(**kwargs)

Called by any module that wants to add a player to an active game.

This method contains the logic to verify whether it's ok to add a player. (For example, the game must be on ball 1 and the current number of players must be less than the max number allowed.)

Assuming this method believes it's ok to add a player, it posts the boolean event player_add_request to give other modules the opportunity to deny it. (For example, a credits module might deny the request if there are not enough credits in the machine.)

If player_add_request comes back True, the event player_add_success is posted with a reference to the new player object as a player kwarg.

start(mode_priority=None, callback=None, **kwargs)

Start this mode.

Parameters:
  • mode_priority -- Integer value of what you want this mode to run at. If you don't specify one, it will use the "Mode: priority" setting from this mode's configuration file.
  • **kwargs -- Catch-all since this mode might start from events with who-knows-what keyword arguments.

Warning: You can safely call this method, but do not override it in your mode code. If you want to write your own mode code by subclassing Mode, put whatever code you want to run when this mode starts in the mode_start method which will be called automatically.

stop(callback=None, **kwargs)

Stop this mode.

Parameters:**kwargs -- Catch-all since this mode might start from events with who-knows-what keyword arguments.

Warning: You can safely call this method, but do not override it in your mode code. If you want to write your own mode code by subclassing Mode, put whatever code you want to run when this mode stops in the mode_stop method which will be called automatically.

warning_log(msg, *args, **kwargs)

Log a message at the warning level.

These messages will always be shown in the console and the log file.