legame 1.0.2

Modules which aid in creating 2-dimensional games with pygame.

LeGame

Modules which aid in creating 2-dimensional games with pygame.

Intro

Playing around with pygame, I quickly found that I was doing the same thing over and over again. I figured it'd be a good idea to make a template for a game and reuse it. That quickly devolved to an obsession with making a whole game framework, with pieces and parts which all fit together and makes everything easy. And that's what eventually led to "LeGame".

Here's what's included (so far) and what each part does:

module	What it does
game	Framework with main loop, events, easy-to-use timers, state management
board_game	Basic framework for games with pieces on squares (like chess, checkers, etc.)
network_game	Create a game which is played over a network
joiner	Discover / connect with another computer over the network using a dialog
sprite_enhancement	Add motion to sprites; position sprites using their center point; boundary checking
resources	Load images, sounds, and sets of images for image flipping
flipper	Image flipping classes to animate the appearance of sprites
neighbors	Checks which sprites are close to one another when there many on the screen
callout	A debugging tool that follows a sprite on screen and displays some text
exit_states	Game states which are commonly used (See GameState below)
configurable	Simple cross-platform configuration save/restore functions
locals	Constants and functions which are needed by some of the above modules

Key classes / concepts

Game

The Game class intializes everything, incuding the inital background and the screen, and provides the main loop, as well as timer maintenance. The main_loop function of the "Game" class is extremely minimal however. Almost all events are dispatched to a GameState class for handling.

GameState

The base GameState class has a function, or "handler", for each of the possible event types that pygame produces, except for timers. For example, there are GameState functions for "keydown", "mousedown", and "quit" events. In the base GameState class, they're empty. When you need to handle these events, you subclass GameState and write the event handlers you need in there.

Your game can have more than one state, where what happens in response to pygame events are different in different states. You can change how your game responds to events by changing the current game state to one with a different set of handlers defined. All you need to do is instantiate a new GameState and the transition happens automatically. When it does, the old state has its "exit_state()" function called, and the new state gets "enter_state()".

It's possible to have just one game state. I wrote a space rescue game with a single game state, "GSPlay", and that was sufficient. A board game I wrote, in contrast, had a lot more states and managing them was actually a lot more complicated.

Sprites

The "sprite_enhancement" module includes the "MovingSprite" class which aids in moving sprites around the screen. Each sprite has a "position" and "motion" property which are used to update the position each time through the event loop.

The "flipper" module provides classes which flip the image of a sprite on a cyclical basis. Any sprite in your game which inherits Sprite can also inherit both "MovingSprite" and "Flipper". Inherit both "MovingSprite" and "Flipper" and you've got a pretty fancy little animated moving thing, with very little coding necessary.

Resources

The flipper module uses the "ImageSet" class of the "resources" module to manage images. An ImageSet is created by loading all of the images found in a sudirectory. They're sorted when loaded, and this sequence of images are flipped on a regular cyclical basis to create an animation.

Single images and sounds are also loaded using the Resources class, with cross-platform support. You don't have to worry about Windows paths breaking your code.

Timers

Timers in pygame are a little clunky, so I enhanced them in the Game class. Pygame provides up to eight timers which are identified by their event number. When you pull events from the pygame event queue, the number pops up. You're supposed to keep track of these numbers and do something or other depending upon what pops out.

I like the way timers work in JavaScript. You just call "setTimeout" with a function, and it gets called when the timer times out. So the Game class provides a "set_timeout" function which works the same. Implementing a timer is as simple as:

Game.current.set_timeout(self.generate_enemy, 2500, x=53, y=137)

... and in 2500 milliseconds, "self.generate_enemy()" will be called with "x=53" and "y=137" as arguments. No worrying about keeping track of pygame event numbers, because the Game class does all that for you.

Networking

The "joiner" module provides classes for connecting to a remote machine using a dialog rendered by pygame.

"BroadcastJoiner" uses UDP broadcast to announce over the network. You can see the other player's user and host names and invite someone or accept an invitation.

"DirectJoiner" allows you to connect to a specific ip address, (even the 127.0.0.1 loopback address), as either the "server" or the "client". Although the term "server" is used to describe the way you connect, there's nothing in the framework which as of now supports the creation of a game server which multiple clients connect with. It's not impossible. You can do it, if you're so inclined. But it's not included.

After a "JoinerDialog" connects to a remote machine, a Messenger sends Message objects between each game instance. LeGame uses fast, lightweight, and easy-to-use messaging provided by the "cable_car" package, which was written specifically for this application.

Quick start

I've provided some templates to quickly get you started on a game. You can find them in the "templates" folder. There, you'll find the following:

• game.py
• board-game.py
• network-game.py
• network-board-game.py

Reference

Most of the code is documented using python docstrings. It's all compiled into pdoc -generated html, which you can find in the "docs" folder.

Tip on using globals:

There's some variables which would be convenient to make global. You might like to declare them in your game module, or declare them "global" in your Game class. Either way, remember that python will assume you're using a local variable instead of a global if it's being assigned a value inside a function, in which case you need to declare that it's global. I got bit by that several times. Easy fix, but annoying.

Here's an example from a game that uses globals:

def __init__ (self, options):
	global game, board, resources, play
	self.set_resource_dir_from_file(__file__)
	BoardGame.__init__(self, options)
	NetworkGame.__init__(self, options)
	game = self
	board = self.board
	resources = self.resources
	play = self.play

def initial_state(self):
	global send
	send = self.messenger.send
	return GSSelectColor()

Now, to refer to the game, you use "game". To refer to the game board, use "board". To refer to the Resources of the game, you use "resources". To play a sound, just call "play". To send a message, use "send".

But note that you can't declare "send" in the __init__ function of the game. The "messenger" which does the "send" is still "None" until the game joiner dialog is shown and your game is actually started. The "initial_state" function is called after the game joiner is closed and a Messenger has been instantiated, so it's safe to attach the global "send" token to the "Messenger.send()" function there.