# Bubble Train

- Game Overview
- Game play
- Fastest Times
- Game options
- Game design
- Level design
- Theme design
- Contact Details

## Game Overview

Welcome to Bubble Train, a fast paced arcade game. Bubble Train as the name suggests is a train of bubbles travelling along a track where the last carriage is the driving force instead of the front one. The bubbles come streaming along the track trying to reach the end of the line. The objective is to remove all of the bubbles from the train before it reaches the end of the track.

## Game play

### Game Select

When you start a game you are presented with a box of games which are available to play. Either double click on a game or highlight it and click ok. The default games are Easy, Normal, Hard, Bubble Train and everything.

### Controls

The game can be controlled by either the mouse or the keys.

### Keys

Default keys

- k - toggle between the mouse / keys during game play
- p - pause the game
- left cursor - rotate the cannon to the left
- right cursor - rotate the cannon to the right
- up cursor - fire loaded bullet

### Mouse

- Move left / right - rotates the cannon left and right
- Left mouse button - fire loaded bullet

### Bubbles

Below are the bubbles used for the train carriages or bullets from the cannon.

Bubble | Description | Carriage / Bullet
| A plain old Bubble | Both
| " | Both
| " | Both
| " | Both
| " | Both
| A special bubble which blows up carriages within the blast radius | Cannon
| A special bubble which blows up all of the carriages in a train which are the same colour as one hit | Cannon
| A special bubble which speeds up or slows down the speed of the train | Both

## Fastest Times

The fastest times are made up of the level and the time. So the higher the level and the faster the time the better the result. This does not group the times by game. So some of the games with fewer levels might not appear.

## Game options

### Credits

Defines the number of re-tries you get during a game. The default is 5, set to -1 for infinite retries

### Sound

You can enable / disable the sound. There are slider controls which allow you to adjust the volume of the music and sound effects.

### Mouse Controls

You can enable / disable using the mouse (This can be changed at run time by pressing 'k'). The slider allows the sensitivity of the mouse to changed.

### Key Controls

The keys used during game play can be re-configured by clicking the "Assign Keys" button and then press the key you want assigned to each action when the prompt appears.

## Game design

A game is made up by specifying levels to be part of the game. There isn't an interface for creating games so you must create / tweak the game file by hand. The setup for a game should create a game file "something.gms" with a .gms extension. Place this in levels folder. Then create a folder with the same name as the game (this is not necessary but makes it cleaner). Then start creating your levels. Once a level is created enter the level file location into the game file along with the theme you would like to use for that level. Now load up Bubble Train and play your game. Once your happy with it then send it to me (adam@dwarfcity.co.uk) and I'll make it available for download from my website. The following is the format for the game xml:

    	<game>
    		<level theme="sky" src="easy/easy-1.lvl" />
    		<level theme="sky" src="easy/easy-2.lvl" />
    		<level theme="beach" src="easy/easy-3.lvl" />
    		<level theme="beach" src="easy/easy-4.lvl" />
    		<level theme="beach" src="easy/easy-5.lvl" />
    	</game>

## Level design

### Over view

This is a very basic level editor for creating new or editing existing levels. A level is made up of a single cannon and one or more trains/tracks. Use the mouse to initially create the tracks and then edit the positions of each of the track sections. Below is a screen shot:

### Managing Tracks

Tracks can be made up of three different types of components, line, arc or spiral. Buttons for these can be found on the track toolbar shown above. Click the corresponding button to add a component of that type. You can also delete the last component from the current track. A property window appears in the bottom right hand corner which allows the editing of the currently selected track section (see below for details about each component property window). The current track section is highlighted in yellow. The start / end of a track is also highlighted with a solid green disc for the start of the track and a solid red disc for the end of the track. If this is not the current selected track then the discs become circles. Next to the remove track section button on the toolbar is the track section selector this changes which track is currently selected.

Note: A track should not overlap itself because the bubble will not follow the track as expected

### Lines

There are two main points for a line, the start and end position these are separated out into the x and y components for each. To edit an item click the mouse in the text box to highlight it (the cursor will always appear after the last character, you can not highlight or copy/paste into the text boxes) and then delete or insert the new value. The line will automatically update along with any a joining components.

### Arcs

The arc property window is similar to the line except you can change the rotation and flip it as well. The rotation defines whether the bubbles will flow in a clockwise or anti-clockwise from the starting position. Flip defines which side of the start / end position the centre is located. When the start / end positions are updated the radius is automatically re-calculated to fit (Note: set the start end positions before trying to get the correct radius, I did say the level editor was basic).

### Spirals

The spiral property window is similar again to the arc except the spirals main points are the start and centre position. The radius for the spiral is for reference only and cannot be changed. Again the spiral is automatically re-calculated when either the start or centre positions are updated. The rotation of the spiral can be altered.

### Multiple Trains/Tracks

You can have as many trains as possible to fit onto the screen and they can also overlap because each train is completely independent of each other. The control for multiple trains is via the buttons at the bottom of the screen. You can add, remove and change the currently selected train. The train which is current selected with have solid discs at the start and end of the track and one of the track sections should be highlighted.

### Managing Train Properties

The train properties control the number, speed etc of the carriages which appear on the track. The track colour can also be changed although this is only needed when the track colour conflicts with a particular theme.

### Managing Cannon Properties

The cannon properties define the type of bullets which can be fired. To start with the number of colours can be defined, this should match the highest number of colours in your trains otherwise it might be a bit of a hard level to play. Then define the speed of bullets in pixels per frame ()

### Loading / Saving a level

The load / save can be found next to the exit button on the toolbar at the bottom left. The load / save dialog appears and presents the current directory, to change into a directory then you have to double click on the directory or the ".." to move up a directory. Once you have change to the required directory then you can double click again on the file you want to load or simply type in the name of the file to save to. Then click load / save and you should be away.

### Grid

The grid allows track sections to be aligned, click the grid like button (the button on the right of show / hide buttons above) to display the grid properties. From here you can switch the grid on/off as well as change the horizontal and vertical spacing.

## Theme design

A theme defines the graphics, fonts, sounds and music for a level. To design a new theme first you must create a folder with the name of your theme. And then create or re-use the following graphics. If any item is missing from your theme then it won't work and the game will quit, look in the log.txt in the bin folder for errors. Once your happy with it then send it to me (adam@dwarfcity.co.uk) and I'll make it available for download from my website.

### Graphics

Defines the main graphics used for a level. For examples look in the themes folder. The graphics used in Bubble Train are all png (portable network graphic) with alpha transparency. The SDL image library used can support many different types of graphic formats bmp, png etc - other libraries might be required for certain formats, but I'm not sure how they will look with the transparency.

Graphic | Dimensions (W x H) pixels | Description
GFX_BUBBLE_RED | 30 x 30 | A Bubble
GFX_BUBBLE_ORANGE | 30 x 30 | A Bubble
GFX_BUBBLE_GREEN | 30 x 30 | A Bubble
GFX_BUBBLE_BLUE | 30 x 30 | A Bubble
GFX_BUBBLE_YELLOW | 30 x 30 | A Bubble
GFX_BUBBLE_BOMB | 30 x 30 | A Special Bubble
GFX_BUBBLE_COLOURBOMB | 30 x 30 | A Special Bubble
GFX_BUBBLE_SPEED | 30 x 30 | A Special Bubble
GFX_CANNON | 40 x 60 |
GFX_BACKGROUND | 800 x 600 |
GFX_HUD | 800 x 36 | Area to display the time, level etc

Note: To make images transparent the colour at location 1,1 is assumed to be the background colour. So if you graphic fills the image including 1,1 then you might want to expand your image to leave a 1 pixel gap all around it so none of the image is lost.

### Fonts

The fonts used in Bubble Train are all graphical fonts. So a font containing a specific character list rendered to an image. Bubble Train's font engine scans the graphic and separates characters based on a single blank column (Note: if a single character contains a blank column then this will be registered as two characters and the following items will be out of sync). The following character list can be used to create your own fonts.

`ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!"£$%^&*()_+-=[]{};'#:@~\\/|?,.<>`

The following items must be supported in your theme

Font | Description
FONT_DEFAULT_LARGE | General Font
FONT_DEFAULT | General Font
FONT_DEFAULT_SMALL | General Font
FONT_SCORE | Displayed on the hud during game play
FONT_MENU | Used on the main menu, message boxes, Exploding Text on the end game
FONT_BUTTON | Used for buttons, list boxes, controls
FONT_DIALOG | Used for labels on dialog boxes

### Sound effects

The sounds effects are in wav format, which is the default format for Bubble Train. They can be off any length. The following items must be supported in your theme

Sound | Description
SND_FIREBULLET | Played when a bullet if fired
SND_CANNONMOVE | Played when the cannon is moved
SND_CANNONRELOAD | Played when the cannon is reloaded
SND_REMOVEDGROUP | Played when you make a group of 3 bubble in a train and they explode
SND_GAMEOVER | Played when you lose a level
SND_GAMEWON | Played when you win a level
SND_BOMB | Played when a bomb hits the train
SND_COLOURBOMB | Played when a colour bomb hits the train
SND_CLICK | Played when a button is clicked

### Music

Music is played in the background for a level. The current format supported is wav, but once I've figured out how to compile the library then it should support mp3, ogg etc. The theme can specify more than one piece of music which it will play in sequence. The music repeats from the first track when it reaches the end of the last track.

### Theme XML

The details for your new theme should be stored in a file called "theme.xml" under your theme folder. A template for this can be found in the default theme folder. The xml is of the following format:

    	<theme>
    		<graphics>
    			<graphic id="GFX_BUBBLE_RED" src="" />
    			<graphic id="GFX_BUBBLE_ORANGE" src="" />
    			<graphic id="GFX_BUBBLE_GREEN" src="" />
    			<graphic id="GFX_BUBBLE_BLUE" src="" />
    			<graphic id="GFX_BUBBLE_YELLOW" src="" />
    			<graphic id="GFX_BUBBLE_BOMB" src="" />
    			<graphic id="GFX_BUBBLE_COLOURBOMB" src="" />
    			<graphic id="GFX_BUBBLE_SPEED" src="" />
    			<graphic id="GFX_CANNON" src="" />
    			<graphic id="GFX_BACKGROUND" src="" />
    			<graphic id="GFX_HUD" src="" />
    		</graphics>
    		<fonts>
    			<font id="FONT_DEFAULT_LARGE" src="" />
    			<font id="FONT_DEFAULT" src="" />
    			<font id="FONT_DEFAULT_SMALL" src="" />
    			<font id="FONT_SCORE" src="" />
    			<font id="FONT_MENU" src="" />
    			<font id="FONT_BUTTON" src="" />
    			<font id="FONT_DIALOG" src="" />
    		</fonts>
    		<sounds>
    			<sound id="SND_FIREBULLET" src="" />
    			<sound id="SND_CANNONMOVE" src="" />
    			<sound id="SND_CANNONRELOAD" src="" />
    			<sound id="SND_REMOVEDGROUP" src="" />
    			<sound id="SND_GAMEOVER" src="" />
    			<sound id="SND_GAMEWON" src="" />
    			<sound id="SND_BOMB" src="" />
    			<sound id="SND_COLOURBOMB" src="" />
    			<sound id="SND_CLICK" src="" />
    		</sounds>
    		<music>
    			<track src="music1.wav"/>
    			<track src="music2.wav"/>
    		</music>
    	</theme>

## Contact Details

Bubble Train was brought to you by:

- Dwarf City (Adam Child)
- Craig Marshall

If you have any themes, levels or games you have created and would like to distribute then send them to adam@dwarfcity.co.uk and I'll make them available to download for everyone.