Software documentation

GameGenerator Documentation

GameGenerator (GG) is a simple 2D game engine for creating Flak games in Python. It provides a customizable game environment for pedagogical purposes, freeing you from having to write algorithms and use complex programming constructs. It was created by yours truly for Madison Middle School’s Young Engineers.

What’s a Flak game?

Flak, the style of game supported by GG, consists of a player on the ground (the bottom of the screen) attempting to shoot down enemy planes performing their bombing runs. The player and the ground structures the player defends must survive, with the player reloading every few shots when out of ammo (with unlimited reloads). It’s fast-paced, challenging, and exciting!

The player gets a number of points for hitting enemies and bombs, and loses points when ground structures are destroyed by bombs. There is an unlimited number of enemy planes, who will continue to spawn as long as the game is running. Once all the buildings are destroyed or the player has lost all her lives, the game is over. The only way to win? Beat the high score.

In case you’re itching to know: Flak is short for Flugzeugabwehrkanone (say it fast 10 times), which is German for “aircraft defense cannon.” Anti-aircraft artillery.

Getting started

Prerequisites

You need to have Python 3.x and Pygame installed in your machine in order to run GameGenerator and the games created with it.

Installing

The gg folder contains the full GameGenerator package; you might say it is the package. Copy that folder to your own game folder, or put it somewhere else and add it to the Python path using sys.path.append(full_path_to_folder_containing_gg) from the Python Shell.

Note to Madison Middle School students: As of July 31, 2018, each Raspberry Pi in the Young Engineers classroom has a copy of gg in the Documents folder. Simply copy and paste the gg folder into your own folder to create games.

Example game

The flak_example.py file in this repository contains a working game. Okay, not a very good one, but one you can still use for reference. The images required by the example game are in the example_pics folder. The background and splash screen images were created using nothing but Scratch.

Creating your first game

Images

For your game to look like a game, it needs images. These images are used to dress up the sprites (that is, the characters and objects) and backgrounds in your game. For testing purposes, you can simply draw colored circles, squares, or lines.

Using any drawing program that can save images, create a separate file for each of the following items:

• The player
• The enemy (a single enemy image will be applied to all the enemies, so you only need to draw it once)
• The missile fired by the player
• A bomb dropped by the enemy
• A ground building

There are also optional images you can draw, with no consequences if you don’t:

• The background (try to get the size in pixels as close as possible to the way you want it in the game)
• A destroyed building to display when a building gets hit
• A splash screen, possibly with your logo and credits, displayed before the game starts

Save your images with a descriptive file name in the same folder as your game code or, as I would recommend, in its own subfolder within the game folder.

GG can handle PNG, JPG, GIF, and all other image formats supported by Pygame. Make sure the sprite images are not so big that they cover the entire screen or make the game unplayable, and that they have a transparent background.

Note to Madison students: Although I haven’t found any good free Raspberry Pi software for creating images, you can use Scratch to draw sprites and backgrounds and then export them as images; or you can create images in a different computer and then bring them to class in a USB drive.

Programming

After putting the gg folder in the location of your choice, create a new .py file (you could call it flak.py, for example) in your folder and import the GG package from the top of the file:

import gg

Then create a variable to contain the game. For simplicity, let’s call it game:

game = gg.Game()

This variable contains your entire game environment: the player, enemies, images, text, behaviors, etc.

Next, customize your game at will by modifying whatever attributes of game you wish to customize using the variable_name.attribute_name = attribute_value syntax (notice the period or dot), often called “dot notation”:

game.name = 'My Shiny Flak Game'
game.player_image = 'good-guy.png'
game.enemy_image = 'bad-guy.png'
game.player_num_shots = 10
game.is_fullscreen = True

You can see the full list of attributes under the section called… well, Full attribute and method list.

All attributes other than image files come with useful defaults, so you don’t have to set any non-image attributes, but it’s way more fun if you make the game your very own.

Okay, images do have defaults: if you don’t specify an image file for a certain character, the file you specify doesn’t exist, or the image specified can’t be loaded for any reason, the missing image will be replaced by the Red Square of Doom, a red square with a white question mark inside. In spite of its ominous name, the RSOD is very useful: it makes it obvious to you that an image is missing and shows you where, saving you some guesswork.

The exception to the RSOD is the game background. If you don’t specify a file, you get a solid-black background.

Once you’re finished customizing your game, run it:

game.run()

That’s it! When you run your Python game file, your game should start.

Playing the game

Default keys

To play the game with its default set of keys, you’ll need to know the following:

• Move left: left arrow
• Move right: right arrow
• Shoot: space
• Reload ammo: control
• Pause the game: P or pause

All these keys are available for you to change. See Changing default keys for details.

High score

After the first time a player attains a score greater than 0, the game will automatically create a folder called gamedata to save that score as the high score. You don’t need to worry about this folder or its contents; the high score will be automatically updated as needed.

To reset the high score to 0, simply delete the folder.

Viewing the framerate

If you’re curious about the current framerate of your game, you can toggle displaying it by pressing F1. The maximum allowed framerate is 60 FPS and, since the graphics aren’t complex, it will probably remain really close to that unless there is some issue.

Closing the game

You can close the game at any time by pressing the window’s closing X icon (if not in fullscreen mode), the Esc key, or Alt+F4. A prompt will ask you to confirm.

Full attribute and method list

The following are all the attributes you can modify to make the game your own. Most likely, you’ll only need to modify a handful of these to get the results you want, but all of them are there for you to play with to your heart’s content. You’ll see that you are not limited to making a game in the way I described under What’s a Flak game? Be creative and break boundaries.

There is a single method (function) you need to call:

• run(): once all the modifiable attributes are set as desired, call this method to start the game.

Changing default keys

To change the default keys used to play the game, you must provide a list of keys as the attribute for a given behavior, even if your list contains a single key; providing more than one key allows each of the keys specified to perform the action.

See the pygame.key documentation for a list of key names under Pygame. All key names begin with K_ and must be prefixed with pygame. since they are internal to Pygame, which, in turn, means you need to import the pygame module into your game to be able to modify default keys.

Special thanks

A shout-out to all my Young Engineers students at Madison Middle School during the 2016–2017 and 2017–2018 school years for inspiring me to spend countless unpaid hours for about 4 grueling weeks in order to create this software. It was a labor of love. You guys are the best!