# BomberMaze Documentation

# Contents

1. Introduction
2. Controls
3. Rules
4. Gameplay
5. Power-ups
6. Custom Mazes
7. Themes

# Introduction

BomberMaze is a multiplayer action game in which players run around in a square-grid maze while dropping time-delayed bombs. When a bomb explodes, it can destroy certain maze blocks, but will leave others unscathed. Any players caught in a bomb explosion are removed from the game. Some blocks, when destroyed, leave behind power-up tokens that players can pick up to enhance their abilities in various ways. The last surviving player wins.

# Controls

The game can be played entirely from the keyboard. The following are the default key mappings:

General controls
F2 | Start new 2 player game
F3 | Start new 3 player game
F4 | Start new 4 player game
Pause/Break | Pause/unpause game
ESC | Quit game in progress, or quit program if no game is in progress
Space bar | Dismiss match status dialog and continue game

The above keys can be customized by selecting the Settings/Preferences menu option and going to the General page of the dialog box that pops up.

Player controls
player | Move Up | Move Right | Move Down | Move Left | Drop Bomb | Special Action
player 1 | up arrow | right arrow | down arrow | left arrow | right control | right shift
player 2 | w | d | s | a | q | 1
player 3 | keypad 8 | keypad 6 | keypad 2 | keypad 4 | keypad Enter | keypad +
player 4 | i | l | k | j | h | y

Player keys can be customized using the appropriate Player page from the Settings/Preferences dialog.

The Drop Bomb key can be configured to auto-fire so that by holding it down and running, a player can drop a continuous line of bombs. By default, you must press and release the Drop Bomb key for each bomb you want to drop.

The Special Action key is used to invoke special actions as enabled by certain power-ups.

# Rules

The object of the game is for each person playing to attempt to win a match by winning a predetermined number of rounds. To win a round, a player must be the only player left on the map. By default, 2 wins are necessary to win a match, but this can be changed via the General page of the Settings/Preferences dialog.

This game is based on a square grid of arbitrary dimensions. Each square in the grid may be empty, or may contain one or more objects or entities. Each entity type is described below along with their associated rules.

#### Player | Each person playing the game controls the actions of a player. Players may move into any of the four squares adjacent to their current square, provided that the destination square does not contain a Bomb, Brick, or Wall (see below). A player dies if the square occupied by that player is ever simultaneously occupied by fire. Players may drop Bombs, but each player cannot have more than a certain number of bombs in the play area at any given instant. When the maximum bomb-drop count for a player is reached, that player cannot drop any more bombs until some of that player's bombs have exploded. Initially, by default, each player can only drop one bomb at a time. This can be changed by selecting the Preferences/Settings menu option and then going to the Numeric page of the dialog box that pops up.
#### Wall | A Wall is a fixed object that can be neither moved nor destroyed. No other object can exist in the same square as a Wall.
#### Brick | Like Walls, no objects can exist in the same square as a brick. However, a brick can be destroyed by fire.
#### Bomb | Bombs are objects dropped by players. Players cannot move into a square occupied by a bomb, but they can move out of a square that contains a bomb (sort of makes sense, because otherwise, dropping a bomb would be automatic suicide). After a certain time delay, a bomb will explode, filling a pattern of squares with Fire. A bomb will also explode if another bomb's explosion hits it, and in this way, explosion chain reactions can be set up. The size of a bomb's explosion depends on the player who dropped it (see below). You can customize the time delay before a bomb explodes by going into the Numeric section of the Preferences menu option.
#### Fire | When a bomb explodes, it will fill its own square with fire and fire will also be propagated from the central square in the four cardinal directions. The maximum radius to which the fire extends varies depending on the player who dropped the bomb in the first place. Initially, by default, each player has a bomb blast radius of 2 squares beyond the central square. You can, however, change this by choosing the Numeric tab from the Settings/Preferences dialog. Regardless of its maximum range, an explosion cannot extend past a square occupied by a Brick, Wall, or Power-up. However, any Brick or Power-up that is hit by an explosion will be destroyed. Players are vulnerable to fire as well.
#### Power-up | When a brick is destroyed, there is a chance that a power-up will appear in its place. When a player moves into a square occupied by a power-up, the player gains certain benefits as described in the Power-ups section. The power-up itself disappears after being touched. To change the probability of getting power-ups, use the Numeric page from the Preferences dialog.

# Gameplay

### Starting a game

Games are multiplayer, and can support 2 to 4 players. Simply select the desired number of players from the Game menu, or hit F2, F3, or F4. A new game with the specified number of players will be started. Note that the keys used to start a new game can be customized via the General page of the Settings/Preferences menu option.

You can start a new game at any time. If you attempt to start a new game while a game is already in progress, the current game will be abandoned and a new one started.

### Pausing the game

While a game is in progress, hit the Pause/Unpause key to toggle the pause status. The game will auto-pause if the game window loses the keyboard focus.

### Match Status

The status bar shows the status of a match. The number of the current round is shown first, followed by the number of wins that each player has.

### Game Over

A round is over when there are one or no players left. At the end of a round, the winner of the round is announced along with the total number of wins that each player has had so far in the match. To continue to the next round, click the button labeled "Continue", or hit the Continue key on the keyboard (the space bar by default, but this can be changed via the General preferences page).

The match is over when a player reaches the required number of victories as set out in the Wins per match entry in the General page of the Settings/Preferences dialog.

The game remains frozen in the Game Over state until you either start a new game, press the Quit Game key, or press the Continue key.

### Network support

Network support is not implemented at this time, but I plan to include it for version 2.

### Computer-controlled players

There is currently no support for computer-controlled players, although they may be added later.

# Power-ups

Whenever a brick is destroyed, there is a chance that a power-up will appear in its place. By default, this probability is 30%, but you can change it by selecting the Settings/Preferences menu option and going to the Numeric tab.

You can also change the probability of getting any particular type of power-up by going to the Power-ups page.

There are several different types of power-ups that you may find. Their effects are described below:

#### Extra Bomb | Adds one to the maximum number of bombs that you can have active at any given time. Extra bombs allow you to set up huge chain reactions, but be careful, or you may toast yourself!
#### Extra Blast Radius | Increases the blast radius of your bombs by one square. It is possible to have bombs whose explosions extend from one end of the maze to the other.
#### Trigger Bomb | The Trigger ability removes the timer on your bombs. Bombs that you drop will not explode until either another explosion hits them, or you hit the Special Action key.
#### Extra Speed | Increases your running speed.
#### Kick Bomb | Any bombs that you run into will be kicked in the same direction as that in which you were moving at the time of collision. A kicked bomb will keep moving until it hits an obstacle. Note that its timer is not disabled by a kick, so it can still explode while moving. The Kick power is extremely useful for bombing your opponents from a distance and for freeing yourself from tight situations.

# Custom mazes

### Wall perimeter setup

By default, the maze is rendered with a line of wall squares at the top edge of the display. This is done so that players at the top of the map will not have the tops of their heads outside of the display area. For those of us who'd like a more symmetrical layout, there is an option to have the wall squares surround the entire maze, not just the top edge. To enable this option, go to Settings/Preferences and uncheck the Show top wall only box in the General section. To totally turn off the wall perimeter, uncheck the Show wall perimeter option.

### Selecting a map

The layout of the maze that you see in-game is determined by a particular file, which is specified in the General section of the Settings/Preferences dialog. By default, this file is `15x13_random`. You will note that there are a number of other map files to choose from. If the default is too large for your screen (or not big enough), you can choose a smaller (or bigger) one. Changes to the map file selection will take place at the beginning of the next round.

The list of selectable maps is obtained by scanning all files located in `INSTALL_PREFIX/share/bombermaze/maps`(1) and in `~/.bombermaze/maps` whose names do not begin with the "`.`" character. File extension is ignored.

### Map file format

To allow users to create their own maps, the format of a maze map file is quite simple. It is a text file consisting of a number of rows whose columns are all of the same length. Each non-carriage-return character in the file specifies a square on the map. Allowable characters are as follows:

. | Empty square
= | Brick
# | Wall
- | Random: square has a 50/50 chance to be either a brick or empty
| | Random: square has a 50/50 chance to be either a wall or empty
+ | Random: square has a 50/50 chance to be either a brick or wall
* | Random: square has a 1 in 3 chance to be empty, a brick, or a wall
1 | Starting location of player 1; empty square
2 | Starting location of player 2; empty square
3 | Starting location of player 3; empty square
4 | Starting location of player 4; empty square

If the map file contains formatting errors (invalid characters or unequal line lengths), the map will not be loaded and no game can be started using that map. Note that the file extension is unimportant.

# Themes

### Theme Selection

The appearance of the graphics in the game can be changed by selecting a theme from the General page of the Preferences dialog.

The list of selectable themes is obtained by scanning all folders located in `INSTALL_PREFIX/share/bombermaze/themes`(2) and in `~/.bombermaze/themes` whose names do not begin with the "`.`" character.

### Theme Creation

You can create a new theme by creating a new folder that contains appropriately named image files. To make the new theme selectable, simply place its folder in either of the two directories listed above. Each theme must contain the following files:

    bomb.png
    brick.png
    fire.png
    floor.png
    player1.png
    player2.png
    player3.png
    player4.png
    powerup.png
    wall.png

The PNG file format is used for all graphics because it supports 24-bit color and alpha channels. Alpha channels are used to encode transparency information. Exact details of each these files are given below.

### Frame Layout in Images

For objects that have more than one frame of animation, the corresponding images themselves contain more than one "frame". Although the appearance of each frame is entirely arbitrary, the actual number of frames is fixed, as is the position of each frame in the pixmap file.

Each image is structured as a grid-like layout of frames, and is a certain number of frames in width and a certain number of frames in height. The exact height and width depends on the image being considered. For example, the image for a floor tile consists of a single frame. On the other hand, the image for a player sprite consists of 25 different frames arranged in a 5 by 5 grid.

For all sprites, each frame must be no more than twice the height of `floor.png`, and the frame width must be the same as or smaller than the width of `floor.png`.

The table below lists the complete set of image files required to constitute a pixmap theme, along with a description of the frames for each one.

### Image | ### Width | ### Height | ### Frame | ### Description
#### floor.png | 1 | 1 | 1 | The image `floor.png` is used as the bottom tile for every single map square. As such, the dimensions of every other tile and sprite is constrained by the dimensions of the floor tile. In particular, no image can have a frame width greater than the floor tile's width, and no image can be taller than twice the floor tile's height. If an image is between 1 and 2 times the height of the floor tile, then it will be rendered in-game with the top portion overlapping the map square immediately above it. The player sprites use this scheme. Most images, however, look better when their height and frame width are exactly equal to those of the floor tile. The default floor tile is 45 pixels wide and 40 pixels high.
#### player*.png | 5 | 5 | 1-5 (row 1) | Player facing up
5-10 (row 2) | Player facing right
11-15 (row 3) | Player facing south
16-20 (row 4) | Player facing left
1,6,11,16 (column 1) | Player walking, right foot in front
2,7,12,17 (column 2) | Player walking, left foot in air
3,8,13,18 (column 3) | Player walking, left foot in front
4,9,14,19 (column 4) | Player walking, right foot in air
5,10,15,20 (column 5) | Player standing still
21-25 (row 5) | Player being hit by an explosion
#### wall.png | 1 | 1 | 1 | Wall
#### brick.png | 4 | 1 | 1 | Brick
2 | Brick shattering when hit by an explosion, first frame
3 | Brick shattering when hit by an explosion, second frame
4 | Brick shattering when hit by an explosion, last frame
#### bomb.png | 6 | 1 | 1 | Normal bomb, frame 1
2 | Normal bomb, frame 2
3 | Normal bomb, frame 3
4 | Normal bomb, frame 4
5 | Triggerable bomb
6 | Inactive bomb
#### powerup.png | 9 | 1 | 1 | Extra bomb
2 | Extra blast radius
3 | Trigger bomb
4 | Kick bomb
5 | Extra speed
6 | reserved; ignore for now
7 | Power-up being hit by an explosion, first frame
8 | Power-up being hit by an explosion, second frame
9 | Power-up being hit by an explosion, last frame
#### fire.png | 16 | 1 | 1-16 | To individually describe all 16 fire tiles would be tedious and repetitive. There is actually a pattern to follow, so I'll describe that instead. If, however, you can't count in binary, I would recommend that you take a look at the image itself and just follow the pattern you see there. Think of each fire frame as a visual representation of a 4-bit integer, starting with 0 and going up to 15 (or in binary, 0000 to 1111). The top edge of each frame codes for the least significant bit, the right edge for the 2's bit, the bottom edge for the 4's bit and the left edge for the 8's bit. If a bit is 0, there is no fire on that edge, and if a bit is 1, then there is a fire on that edge. For example, frame number 0 (0000) is blank. Frame number 14 (1110), on the other hand, is a T-shaped intersection of fire.

1, 2: If you installed the RPM package for this game, then `INSTALL_PREFIX=/usr` by default, unless you used the `rpm --relocate` option. If you installed from source, then `INSTALL_PREFIX` is whatever you passed to the `configure` script in the `--prefix` option. If you did not supply the `--prefix` option, then `INSTALL_PREFIX` should be `/usr/local`. See the file `INSTALL` for details.