GameGenerator Documentation

An anti-aircraft cannon near Dover Castle

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:

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

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:

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.

AttributeDescriptionTypeDefault value
nameThe name of the game, displayed on the window title bar, if there is one.String'GG Flak'
images_dirThe path of the directory where the images are.StringNone
window_iconFile name of the icon to display next to the name.StringNone
splash_imageThe image that covers the screen at the beginning.StringNone
screen_widthThe window width in pixels if not fullscreen.Number800
aspect_ratioThe aspect ratio of the window if not fullscreen.Number1.7778
is_fullscreenWhether the window covers the entire screen.BooleanFalse
font_colorThe color of the text that appears on the screen.Tuplegg.colors.WHITE
screen_font_sizeThe point size of the info text on the screen.Number36
background_colorA solid color used if no image is specified.Tuplegg.colors.BLACK
background_imageFile name of the image to put as background.StringNone
player_imageThe image file for the player object.StringNone
player_num_livesNumber of tries the player gets before losing.Number3
player_num_shotsNumber of shots per reload. 0 means no reloading.Number10
player_speedHow far the player moves left or right in one second.Number800
player_x_posThe initial x-coordinate of the player’s top left.NumberNone
player_y_posThe initial y-coordinate of the player’s top left.NumberNone
has_player_sprite_dirFlip the player sprite when moving?BooleanTrue
missile_imageThe image file for the missile fired by the playerStringNone
missile_speedHow fast the player missile travels.Number2000
is_missile_upwardDoes the missile move up or down? Up if true.BooleanTrue
enemy_imageThe image for all the enemy objects.StringNone
enemy_speedHow fast the enemy airplanes move.Number600
enemy_countMax number of enemies on the screen at any given time.Number5
enemy_top_edgeTop of the boundary where enemies can spawn.NumberNone
enemy_bottom_edgeBottom of the boundary where enemies can spawn.NumberNone
bomb_imageThe image file for the bomb dropped by the enemy.StringNone
bomb_speedHow fast the enemy bombs travel.Number800
is_bomb_downwardDoes the bomb move down or up? Down if true.BooleanTrue
building_imageThe image file for the ground structure objects.StringNone
building_razed_imageOptional image for buildings that are hit.StringNone
building_countHow many buildings to start game with. Must be > 1.Number4
building_y_posY-coordinate of buildings; None means near bottom.NumberNone
score_posThe position where the score is displayed on the screen.Tuple(10, 10)
score_factorHow many points the player gets per hit.Number1
score_loss_factorPoints lost when a building is destroyed.Number10
high_score_posWhere to display highscore; None means top-center.TupleNone
num_lives_posThe location of the player’s remaining lives panel.Tuple(10, 40)
num_shots_posThe location of the player’s remaining shots panel.Tuple(10, 74)
thumbnails_heightThe height of the lives and shots thumbnails.Number24
message_high_scoreMessage to show when the player gets highscore.String'You beat the high score!'
message_game_overMessage to show when the player loses.String'Game over'
keys_move_leftList of keys that move the player left.List[pygame.K_LEFT]
keys_move_rightList of keys that move the player right.List[pygame.K_RIGHT]
keys_shootList of keys that fire the missile.List[pygame.K_SPACE]
keys_reload_ammoList of keys that reload the ammo when out.List[pygame.K_LCTRL, pygame.K_RCTRL]
keys_pauseList of keys that pause the game.List[pygame.K_p, pygame.K_PAUSE]

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

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!