game Submodule

The procgame.game submodule contains the core building blocks of a pyprocgame-based game. See pyprocgame Manual for a discussion on how to create a pyprocgame game.

Core Classes

AttrCollection

class procgame.game.AttrCollection

A collection of procgame.game.GameItem objects.

items_tagged(tag)

Returns a list of items with the given tag.

Driver

class procgame.game.Driver(game, name, number)

Represents a driver in a pinball machine, such as a lamp, coil/solenoid, or flasher.

Subclass of GameItem.

default_pulse_time

Default number of milliseconds to pulse this driver. See pulse().

disable()

Disables (turns off) this driver.

enable()

Enables this driver indefinitely.

Warning

Never use this method with high voltage drivers such as coils and flashers! Instead, use time-limited methods such as pulse() and schedule().

future_pulse(milliseconds=None, timestamp=0)

Enables this driver for milliseconds at P-ROC timestamp: timestamp.

If no parameter is provided for milliseconds, default_pulse_time is used. If no parameter is provided or timestamp, 0 is used. ValueError will be raised if milliseconds is outside of the range 0-255.

last_time_changed

The last time that this driver’s state was modified.

patter(on_time=10, off_time=10, original_on_time=0, now=True)

Enables a pitter-patter sequence.

It starts by activating the driver for original_on_time milliseconds. Then it repeatedly turns the driver on for on_time milliseconds and off for off_time milliseconds.

pulse(milliseconds=None)

Enables this driver for milliseconds.

If no parameters are provided or milliseconds is None, default_pulse_time is used. ValueError will be raised if milliseconds is outside of the range 0-255.

pulsed_patter(on_time=10, off_time=10, run_time=0, now=True)

Enables a pitter-patter sequence that runs for run_time milliseconds.

Until it ends, the sequence repeatedly turns the driver on for on_time milliseconds and off for off_time milliseconds.

schedule(schedule, cycle_seconds=0, now=True)

Schedules this driver to be enabled according to the given schedule bitmask.

state()

Returns a dictionary representing this driver’s current configuration state.

GameController

class procgame.game.GameController(machine_type)

Core object representing the game itself. Usually a game developer will create a new game by subclassing this class. Consider subclassing BasicGame instead, as it makes use of several helpful modes and controllers.

add_player()

Adds a new player to players and assigns it an appropriate name.

ball

The number of the current ball. A value of 1 represents the first ball; 0 indicates game over.

ball_ended()

Called by the game framework when the current ball has ended.

ball_starting()

Called by the game framework when a new ball is starting.

balls_per_game

Number of balls per game.

coils

An AttrCollection of Driver objects. Populated by load_config().

config

YAML game configuration loaded by load_config().

create_pinproc()

Instantiates and returns the class to use as the P-ROC device. This method is called by GameController‘s init method to populate proc.

Checks config for the key path pinproc_class. If that key path exists the string is used as the fully qualified class name to instantiate. The class is then instantiated with one initializer argument, machine_type.

If that key path does not exist then this method returns an instance of pinproc.PinPROC.

create_player(name)

Instantiates and returns a new instance of the Player class with the name name. This method is called by add_player(). This can be used to supply a custom subclass of Player.

current_player()

Returns the current Player as described by current_player_index.

current_player_index

Index in players of the current player.

dmd_event()

Called by the GameController when a DMD event has been received.

enable_flippers(enable)

Enables or disables the flippers AND bumpers.

end_ball()

Called by the implementor to notify the game that the current ball has ended.

end_game()

Called by the implementor to mark notify the game that the game has ended.

end_run_loop()

Called by the programmer when he wants the run_loop to end

game_data

Contains high score and audit information. That is, transient information specific to one game installation.

game_ended()

Called by the GameController when the current game has ended.

game_started()

Called by the GameController when a new game is starting.

get_events()

Called by run_loop() once per cycle to get the events to process during this cycle of the run loop.

is_game_over()

Returns True if the game is in game over. A game is in game over if ball is 0.

lamps

An AttrCollection of Driver objects. Populated by load_config().

load_config(filename)

Reads the YAML machine configuration file into memory. Configures the switches, lamps, and coils members. Enables notifyHost for the open and closed debounced states on each configured switch.

load_config_stream(stream)

Reads the YAML machine configuration in stream form (string or opened file) into memory. Configures the switches, lamps, and coils members. Enables notifyHost for the open and closed debounced states on each configured switch.

load_game_data(template_filename, user_filename)

Loads the YAML game data configuration file. This file contains transient information such as audits, high scores and other statistics. The template_filename provides default values for the game; user_filename contains the values set by the user.

See also: save_game_data()

load_settings(template_filename, user_filename)

Loads the YAML game settings configuration file. The game settings describe operator configuration options, such as balls per game and replay levels. The template_filename provides default values for the game; user_filename contains the values set by the user.

See also: save_settings()

log(line)

Deprecated; use logger to log messages.

logger

Logger object instance; instantiated in __init__() with the logger name “game”.

machine_type

Machine type used to configure proc in this class’s initializer.

modes

An instance of ModeQueue, which manages the presently active modes.

old_players

Copy of players made when reset() is called.

players

Collection of Player objects.

proc

A pinproc.PinPROC instance, created in the initializer with machine type machine_type.

process_config()

Called by load_config() and load_config_stream() to process the values in config.

reset()

Reset the game state as a slam tilt might.

run_loop(min_seconds_per_cycle=None)

Called by the programmer to read and process switch events until interrupted.

save_game_data(filename)

Writes the game data to filename. See load_game_data().

save_settings(filename)

Writes the game settings to filename. See load_settings().

shoot_again()

Called by the game framework when a new ball is starting which was the result of a stored extra ball (Player.extra_balls). The default implementation calls ball_starting(), which is not called by the framework in this case.

start_ball()

Called by the implementor to notify the game that (usually the first) ball should be started.

start_game()

Called by the implementor to notify the game that the game has started.

switches

An AttrCollection of Switch objects. Populated by load_config().

t0

Start time.time of the game program. I.e., the time of power-up.

tick()

Called by the GameController once per run loop.

user_settings

Contains local game configuration, such as the volume.

GameItem

class procgame.game.GameItem(game, name, number)

Base class for Driver and Switch. Contained in an instance of AttrCollection within the GameController.

game

GameController to which this item belongs.

label

Display name of this item.

name

String name of this item.

number

Integer value for this item providing a mapping to the hardware.

tags

List of string tags used to group this item.

yaml_number

Number string from YAML config file

Mode

class procgame.game.Mode(game, priority)

Abstraction of a game mode to be subclassed by the game programmer.

Modes are essentially a collection of switch even thandlers. Active modes are held in GameController.modes, an instance of ModeQueue, which dispatches event notifications to modes in order of priority (highest to lowest). If a higher priority mode’s switch event handler method returns SwitchStop, the event is not passed down to lower modes.

Switch event handlers are detected when the Mode initializer is called by the subclass. Various switch event handler formats are recognized:

sw_switchName_open(self, sw)
Called when a switch (named switchName) is opened.
sw_switchName_closed(self, sw)
Closed variant of the above.
sw_switchName_open_for_1s(self, sw)
Called when switchName has been open continuously for one second

Example variants of the above:

def sw_switchName_closed_for_2s(self, sw):
        pass

def sw_switchName_closed_for_100ms(self, sw):
        pass

def sw_switchName_open_for_500ms(self, sw):
        pass

Note

Presently only switch names with the characters a-z, A-Z, and 0-9 are recognized. If a switch name has an underscore in it, the switch handler will not be recognized.

Modes can be programatically configured using add_switch_handler().

add_child_mode(mode)

Add mode as a child of the receiver. Child modes are added and removed from the game’s mode queue when mode_started() and mode_stopped() are called, respectively.

If this mode is already on the mode queue (is_started() == True), then mode will be added (started) immediately.

Sets mode‘s parent_mode to the receiver.

Returns:mode
add_switch_handler(name, event_type, delay, handler)

Programatically configure a switch event handler.

Keyword arguments:

name
valid switch name
event_type
‘open’,’closed’,’active’, or ‘inactive’
delay
float number of seconds that the state should be held before invoking the handler, or None if it should be invoked immediately.
handler
method to call with signature handler(self, switch)
cancel_delayed(name)

Removes the given named delays from the delayed list, cancelling their execution.

delay(name=None, event_type=None, delay=0, handler=None, param=None)

Schedule the run loop to call the given handler at a later time.

Keyword arguments:

name
Switch name for this event. If using this method for a delayed method call, use None and a name will be generated for you. The generated name can be obtained from the return value.
event_type
‘closed’, ‘open’, or None.
delay
Number of seconds to wait before calling the handler (float).
handler
Function to be called once delay seconds have elapsed.
param
Value to be passed as the first (non-self) argument to handler.

If param is None, handler’s signature must be handler(self). Otherwise, it is handler(self, param) to match the switch method handler pattern.

Returns the name of the delay, which may later be used with cancel_delayed().

Example usage for delayed method invocation:

def delayed_handler(self):
        print 'thatButton was pressed 2 seconds ago!'

def sw_thatButton_active(self):
        # After 2 seconds, call delayed_handler() above.
        self.delayed_name = self.delay(delay=2.0, handler=self.delayed_handler)
        # Store name to cancel the delay later: self.cancel_delayed(self.delayed_name)
dispatch_delayed()

Called by the GameController to dispatch any delayed events.

is_started()

Returns True if this mode is on the mode queue (mode_started() has already been called).

mode_started()

Notifies the mode that it is now active on the mode queue.

This method should not be invoked directly; it is called by the GameController run loop.

mode_stopped()

Notifies the mode that it has been removed from the mode queue.

This method should not be invoked directly; it is called by the GameController run loop.

mode_tick()

Called by the GameController run loop during each loop when the mode is running.

mode_topmost()

Notifies the mode that it is now the topmost mode on the mode queue.

This method should not be invoked directly; it is called by the GameController run loop.

parent_mode

The parent mode for this mode. Set by add_child_mode() and cleared in remove_child_mode().

remove_child_mode(mode)

Remove mode as a child of the receiver. See add_child_mode() for a description of child modes. If this mode is already on the mode queue, the mode will be removed (stopped) immediately.

Sets mode‘s parent_mode to None.

See also: add_child_mode().

update_lamps()

Called by the GameController re-apply active lamp schedules

ModeQueue

class procgame.game.ModeQueue(game)

A queue of modes which dispatches switch events.

changed

True if the contents of the queue has changed since the last time this variable was set to False.

Player

class procgame.game.Player(name)

Represents a player in the game. The game maintains a collection of players in GameController.players.

extra_balls

Number of extra balls that this player has earned.

game_time

Number of seconds that this player has had the ball in play.

name

This player’s name.

score

This player’s score.

Switch

class procgame.game.Switch(game, name, number, type='NO')

Represents a switch in a pinball machine.

Switches are accessed using GameController.switches.

Subclass of GameItem.

debounce

True indicates switch events should only change the state when they are debounced events.

hw_timestamp

Hardware timestamp of the last state change of this switch. None until an event is received.

is_active(seconds=None)

True if the ball is activating this switch, or if this switch is somehow being activated. If seconds is not None (the default), only returns True if the switch has been active for that number of seconds.

is_inactive(seconds=None)

True if the ball is not activating this switch If seconds is not None (the default), only returns True if the switch has not been active for that number of seconds.

last_changed

time of the last state change of this switch. None if the GameController has not yet initialized this switch’s state.

reset_timer()

Resets the value returned by time_since_change() to 0.0. Normally this is called by the GameController, but it can be triggered manually if needed.

state

False indicates open, True is closed. In most applications the is_active() and is_inactive() methods should be used to determine a switch’s state.

time_since_change()

Number of seconds that this switch has been in its current state. This value is reset to 0 by the GameController after the switch event has been processed by the active Mode instances.

type

'NO' (normally open) or 'NC' (normally closed). Mechanical switches are usually NO, while opto switches are almost always NC. This is used to determine whether a switch is active (“in contact with the ball”) without ruleset code needing to be concerned with the details of the switch hardware.

Helper Classes

BasicGame

class procgame.game.BasicGame(machine_type)

BasicGame is a subclass of GameController that includes and configures various useful helper classes to provide:

  • A ScoreDisplay mode/layer at priority 1, available at self.score_display.
  • A DisplayController mode to manage the DMD layers, at self.dmd.
  • A Desktop helper at self.desktop configured to display the most recent DMD frames on the desktop, as well as interpret keyboard input as switch events.

It is a recommended base class to build your game upon, or use as a template if your game has special requirements.

dmd_event()

Updates the DMD via DisplayController.

get_events()

Overriding GameController’s implementation in order to append keyboard events.

reset()

Calls super’s reset and adds the ScoreDisplay mode to the mode queue.

score(points)

Convenience method to add points to the current player.

tick()

Called once per run loop.

Displays the last-received DMD frame on the desktop.

Constants

procgame.game.SwitchContinue

Used as a return value from a Mode switch handler to indicate that lower priority modes should receive this switch event.

procgame.game.SwitchStop

Used as a return value from a Mode switch handler to indicate that lower priority modes should not receive this switch event.

Table Of Contents

Previous topic

events Submodule

Next topic

highscore Submodule

This Page