Resources‎ > ‎Pygame Skeleton‎ > ‎


Module Structure

The structure of the system is shown below.  There is a link to each module for more information.
  1. pygameskeleton
    1. lib
      1. engine
        1. cpuspinner
        2. events
          1. Event
          2. Listener
          3. EventManager
        3. model
          1. Model
          2. GameObject
          3. State
        4. pygameeventsmanager
        5. pygameview
        6. systemevents
          1. TickEvent
          2. QuitEvent
          3. KeyboardEvent
          4. MouseButtonEvent
          5. MouseMotionEvent
          6. DrawRequestEvent
          7. SystemEventListener
          8. SystemEventManager
      2. gamestate
      3. gui
        1. ButtonClickedEvent
        2. ButtonMouseOverEvent
        3. GUIEventManager
        4. GUIEventListener
        5. Image
        6. Button
        7. Text
        8. TextInputBox

This is the main script used to launch the game.  It doesn't take any command line options.

It is used to initialize the system components and start the CPU Spinner.

It contains the following constants:

 GAME_NAME  String  This string will be used as the title of the display window.
 FPS  Int  The number of TickEvents dispatched each second.
 SCREEN_SIZE  (x,y)  Tuple representing width and height of the display window.
 BG_COLOR  (r,g,b)  Tuple representing the r, g, b values for the background.


This directory is used to contain the code referenced by


The engine sub-system contains the core modules needed to implement the Model View Controller pattern.

The Model is used to store data describing the state of the game.

The Views are used to output the current state of the game to external devices.  Currently only the 
pygameview has been implemented but the system can be adapted for file logging and network access.

The controllers are used to accept input from the system and dispatch relevant system events.  

Currently there are two controllers.  
  1. CPUSpinner - This controller generates TickEvents at the rate specified in
  2. Pygame Events Manager - This controller processes pygame events and dispatches relevant system events.

CPU Spinner

The CPU Spinner is used to keep the game looping.

Its run method is an infinite loop which uses the pygame clock to wait for the time specified in and
then post a TickEvent.

It listens for a QuitEvent and will terminate the loop when it is received.


The events module contains the classes needed to implement the event driven system communication.


This class acts as an abstract marker interface.  Events should inherit this or some more specialized
sub-class as event identification is based on type.

Sub-classes can provide additional fields for event data.  E.g. The KeyboardEvent includes data such as 
which key was pressed.


The listener interface allows an object to listen for events from an EventManager.

Its init method takes an 'event_manager' argument, which is a reference to the event manager this
particular listener should register itself with.  Sub-classes of the listener should override the init
method in order to register with the correct event manager.

The interface consists of a single 'notify' method with a single 'event' parameter, which is the
event that was dispatched.  Classes that implement the interface should define how they react
to events here.


This is an abstract class that defines the behaviour of an EventManager.  

The event manager has one class field 'listeners', which is a WeakKeyDictionary.  As this is used as a 
static field (in order to avoid passing references to the event manager to every listener) all sub-classes
need to define this field.  An example of how to do this can be found in the SystemEventManager.

The class has methods to register and unregister listeners.

There is also a 'post' method, which can be called by any object that wishes to post an event for
listeners to receive.

It is intended for this class to be treated as abstract and for more concrete sub-classes to be
created for specialized purposes.  E.g. a system event manager, GUI event manager or a game event manager.


The Model stores the data for the current state of the game.  


The model is a static object.  It stores all the variables and objects that describe the state of the game.

It is a Finite State Machine.  The State field that it contains is used to hold all of the data.  The primary
function of the Model object is to keep a reference to the current state.


This is an interface which must be implemented by all objects which are to be visible on screen.

The interface specifies a single 'render' operation which is called by the PygameView when it is time
to draw the object on screen.

The object itself specifies how it should be drawn.


This is a marker interface which marks implementing classes as a state that the Model can be in.


The Pygame Events Manager is a controller that listens for a TickEvent and then gets all the events
from the Pygame events queue, converts them into the relevant SystemEvent and then posts them


The Pygame View is a controller that listens for a DrawRequestEvent and then calls 'render' on all
the GameObjects that are listed as 'visible_objects' in the event's fields. 

The objects will be drawn in the order they appear in the 'visible_objects' list - so this list can be
used for z-ordering.


This module contains the definition of the System Events that are used to provide communication
between system components.


This event is posted by the CPU Spinner at the beginning of each loop.  Objects that are expected
to do something each frame should listen for this event.


This event is posted when the user tries to quit the game either by closing the game window or by some
action within the game's GUI.  Posting it will cause the system to exit.


This event is generated by the PygameEventsManager when it receives keyboard input from the pygame
events queue.

It has the following parameters:
  • type - Either pygame.KEYUP or pygame.KEYDOWN
  • key - The key that was pressed - as defined in the pygame constants.


This event is generated by the PygameEventsManager when it receives mouse button events from the pygame
events queue.

It has the following parameters:
  • type - Either pygame.MOUSEBUTTONUP or pygame.MOUSEBUTTONDOWN
  • button - The number of the button that was pressed.
  • pos - The position of the mouse at the time of the event


Posted by the model when it wishes for the screen to be updated.

It has the following parameters:
  • visible_objects - The GameObjects which are to be drawn on screen - in the order they should be drawn.


An abstract listener which should be inherited by any object wishing to listen to System Events.

Its init method will register itself with the SystemEventManager.


Provides a dedicated EventManager for System Events.


This file is an example of how a game can be created using the components provided by the Pygame Skeleton.

It shows how a State can be used for gameplay and how to create a dedicated EventManager for the game.

It consists of a few of the GUI components and a man that can be moved around on screen with the arrow keys.

This file is where most of the work should be done when creating a unique game with the Pygame Skeleton.


This module contains some basic GUI components for use within games.


This event is posted to the GUIEventManager when a Button is clicked.

It has one parameter:
  • button - A reference to the button that was clicked.


This event is posted to the GUIEventManager when the user first moves their mouse within the bounds of a Button.

It has one parameter:
  • button - A reference to the button that was mouse-overed.


A dedicated EventManager for the GUI system.


A Listener interface for objects that need to listen to GUI events.


This class is for displaying an image (i.e. a Surface) on screen.  It is inherited by all the other GUI components.

It has two parameters:
  • rect - The Rect on screen that the surface should be drawn to.
  • surf - The surface that should be blitted on screen.


This component is an area on screen that the user may click.

It will post a ButtonClickedEvent when it is clicked and a ButtonMouseOverEvent when the user moves their mouse
within its bounding rect.

It has the following parameters:
  • rect - The Rect on screen that the button occupies.
  • normal_surf - How the button should appear when not mouse-overed.
  • mouse_over_surf (optional) - How the button should appear when the mouse is within its bounds.


This component allows a string to be drawn on screen.

It has the following parameters:
  • text - The string to be displayed
  • colour - The colour the text should be rendered.
  • fontsize - The size of font to use
Note: The position of the text should be set by using its 'rect' field (inherited from Image).


This component provides an area on screen into which text can be input by the user.

It has the following parameters:
  • topleft - A tuple specifying the position of the top left corner of the TIB.
  • width - The width in pixels.
  • initial_text - The string that should be displayed before any user input.
  • fg_color - The colour of the text, cursor and border
  • bg_color - The colour of the background.
  • fontsize - The fontsize of the text.
  • border_width (default = 2) - The thickness of the border around the TIB.
The text that the user has entered so far is stored in the object's 'text' field.