README.game-modules

Sun Sep 29 10:58:02 CEST 2002 stas Z <stas.zytkiewicz@gmail.com>

A brief description of the conditions for a game module.

General:
The game field is 800x500 pixels.
Escape and quit stuff is handled by the controller class in childsplay.
utils.py provides some useful functions and classes.
If a 'fatal' error occurs, then the module __MUST__ raise the 'MyError' exception
found in utils.py.
The MyError class, name attr. must be set to module.__name__, and optional extra info
can be given along with this exception.
Info must be a string of text lines which begins with two spaces.

Look also at the README.develop.

The games-module must provide a class called 'Game' and the constructor
must take four arguments:
1 - main screen = a pygame surface object.
2 - main background screen = a pygame surface object.
3 - background color = a RGB tuple _None, if the background isn't a solid
                       color).
4 - base path = a string; the base path of the current working dir. 
                (the childsplay dir.).

The class 'Game' must export two members and three methods.
Members:
'gamelevels' - a sequence (max 5 items).
'gameitems' - a sequence of anything or any length.

These sequences are used by the two loops in the childsplay controller
class from which the method 'start' is called with the items of the 
members as arguments. The gamelevels is used as the outer loop and
gameitems as the inner.

Methods:
'start'(level,item) - start is called len(gameitems) times, every
                      gamelevel[item] time. 
Optional 'start' can export a doc string which is printed to stderr.

'loop'(eventlist) - called from the controllers mainloop with a copy of
                    the event-queue as the argument.
                    The mandatory return value is a 2-item tuple
                    consisting of a status value and a score value or
                    None. The status value is check to determine the 
                    controllers action.
Possible return values (status[0])
 0 = continue the event loop (do nothing).
-1 = clear screen and return to the event loop.
 1 = reserved for future use.
 2 = stop the game.

'helptitle' - Used for the title (duhh) of the help text. 

'help' - Is called when the user hits the question mark.
         Must return a list of strings where every string is a line
         of text (max 72 chars).
         This text will be converted to a surface and displayed, on top
         of the main screen, also a ok-button is added.
         Meanwhile the game is 'frozen' until the user hits the button.