Magazyn Exec 5/CD_Magazyn_EXEC_nr_5.iso/Programy/Programowanie/BASIC/BallMasterSrc.lha/BallMasterSrc/development.txt

Text File | 2000-12-29 | 5.6 KB | 165 lines

Short developer documentation for BallMaster
============================================

Copyright (C) 2000  Damir Arh


Distribution
------------

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Introduction
------------

I decided to release the source files for BallMaster under the terms
of GNU General Public Licence because I don't have time to work on it
any more. In this way I hope to give the possibility of modifying the
game graphics, levels or the game itself to everyone who might be
interested.

In the following lines I'll try to give a short description of the
files found in this archive to make the first steps in modifying the
game easier. I know that the source code might be a bit problematic
as most of the comments and identifier names are in Slovenian language
but you'll probably manage it anyway.

I don't intend to help in further development in any way but I am
prepared to answer any questions about the source code you might send
me (as long as they are in reasonable numbers). I'd also appretiate it
if you contact me regarding the modifications you might have made so
that we can prevent several different game versions popping up.


File description
----------------

There are several files in the source archive (you also need the binary
archive to have the complete set of game files):

BallMaster.asc is the main game source in Blitz 2 saved as ASCII file.
To compile it you need to set the current directory to the one where the
*.gfx and *.col files reside. By setting the constant #ecs to 0 or 1 you
decide to compile the AGA or ECS version respectively (conditional
compilation).

shapes.asc is the source file (also written in Blitz 2 and saved as ASCII
file) for the program which generates the *.gfx files which get included
in the final executable.

*.iff files are the graphics 'source' files. Use the shapes program to
generate *.gfx files from them. *.col files are the palette files for
these graphics. They also get included in the executable.


Changing graphics
-----------------

To change the in-game graphics you have to modify the included *.iff files.
Make sure you keep the same number of colors if you don't want to modify
the source, too.

To change the between-level graphics (they are only included in the binary
archive), you should change the files in the gfx folder. Check the loading
function at the beginning of the source code to see what gets checked in
the picture header to see if the file is valid. You should confirm to this
check or you can just remove the check from the source code (in this case
you should really include a more proper check for file validity there).
Make sure you don't use the last pen in the palette as it gets changed for
internal use.


Changing levels
---------------

The levels are described in two files, both in the lvl directory. The first
file is default.dat and describes level meta data. The first line contains
the complete number of levels, then every 8 lines describe one single level
in the following way:

- level title
- level time
- time between ball releases
- number of predefined colours to complete
- time interval between combination appearances
- time bonus for the combination
- percent of joker balls
- checksum

Details about the checksum can be found in the game source in the load_levels
routine. Of course you can also disable the checksum checking in the source
but in this case you should find another way for checking for the validity
of the level file.

The second file is default.map and this one contains the actual map data in
sequential order (ie. 70 bytes for each level - tiles from left to right from
top to bottom). The byte values are as follows:

00 - empty tile
01 - horizontal tube
02 - vertical tube
03 - revolver (counter-clockwise)
04 - revolver (clockwise)
05 - tube crossing
06 - up-right tube
07 - down-right tube
08 - down-left tube
09 - up-left tube
10 - arrow right
11 - arrow down
12 - arrow left
13 - arrow up
14 - red horizontal filter
15 - red vertical filter
16 - green horizontal filter
17 - gren vertical filter
18 - yellow horizontal filter
19 - yellow vertical filter
20 - blue horizontal filter
21 - blue vertical filter
22 - red horizontal colour
23 - red vertical colour
24 - green horizontal colour
25 - green vertical colour
26 - yellow horizontal colour
27 - yellow vertical colour
28 - blue horizontal colour
29 - blue vertical colour
30 - teleport
31 - auto revolver (counter-clockwise)
32 - auto revolver (clockwise)

I suggest you configure your favourite map builder to create maps. It will
certainly be the easiest way. And make sure that the map is valid or the
game could crash when playing it. You could also make the necessary checks
in the game source to prevent this.


Suggestions
-----------

At the end I'd like to give you some suggestions as to what could be improved
in the game:

- increased number of levels
- support for different level sets
- improved graphics
- graphics card support

Have fun playing with source code. I hope you'll succeed in making it better or
that you'll at least learn something from it.