Mappy tutorial 1

Purpose:

To show how to use MappyWin32 and the playback libraries by going through an entire small game project. Source, graphics and maps are included. This has grown into quite a large tutorial and there are some complicated bits of code in the example source, so I have made a mini FAQ as well which answers common problems in a concise way. It is not necessary to understand all the source, it is there to give you ideas on how to use maps made with Mappy

Disclaimer/Licence

By using any of this you assume all risks, whatever they may be, ie the authors disclaim all responsibility for any consequences of using any of this material
All the files in this archive may be used by anyone, for anything. The only things you are not allowed to do are sell or pass any of this off as your own work
You are free to use any of the files in your own projects. Additionally the file suspiria.xm was included in this archive from www.modarchive.com and so copyright remains with its author (Jogeir Liljedahl).

Step 0 - Before starting

You will need:
A C compiler supported by one of the Playback libraries (MappyAL or MappyDX) along with the appropriate libraries.
You will need at least Allegro 3.9.x for MappyAL, DirectX3 SDK or better for MappyDX.
You will need a true colour paint package, or some 24bit tile and sprite graphics in BMP format.
You will need the SEAL sound library (optional).
The following list of tools are ALL freeware for what we want to do:

Click here to go to the Mappy homepage to download the MappyWin32 editor and MappyAL or MappyDX
If you don't have a 24bit paint package: Click here to get the Windows version of the excellent GIMP 24bit paint package
If you want music and sound with DirectX: Click here to get the SEAL multiplatform sound library
If you want music and sound with Allegro: Click here to get the JGMOD library
If you want to do the graphic conversion part of this tutorial (recommended if you are doing a 8bit/256 colour map): Click here to go to the Smacker homepage

Got all that installed properly? Then it is time to begin...

Step 1 - Design it

Whether its a solo project or not, you will have to plan out what you want to make and how to do it. It is up to you how you do this, but even a simple game can take a lot of time to make, fortunately for this tutorial this is already done. It is worth noting on how many sites there are games with very little done on them, please consider finishing the project :)

Right, lets make an above view 'gauntlet' style game then. Should be nice and easy. It'll be in 640*480*8, and have a panel at the bottom, for, er, other things. With such a design as that I cannot fail to make a superb game, so...

Step 2 - Make (at least some) graphics

There is a knack to making graphics for tiles, however you make them, you should make sure that things like walls and floors line up on the boundaries. Having decided on a theme, I'm going to draw some graphics, making sure they fit into 32*32 multiples. Lets see the first results then (this image shows the tiles 2:1):

The tile above was drawn with GIMP win32 in 24bit, like this:
1: original. Used File>Dialogs>Brushes to select a suitable small round brush with a fuzzy edge, set to 50% opacity and just drew randomly with the paintbrush in a sort of grey-blue colour. Then I selected black and drew the edges, then white for the highlights, this really only works well in true colour (24bit paint packages). The size of the image is, of course 32*32.
2: 2*2 grid of original tile. This shows the problem with this, the edges don't match when tiled, to solve it, brush a 32*32 piece from the center and...
3: 32*32 blended, smooth out the joins (which now form a '+' shape across the tile).
4: 2*2 grid of blended tile. It shouldn't be so obvious where the edges are now.

Make most of the tiles, you can improve them and add more later. For 256 colour games, if you want any transparent areas in the tiles, leave them black (RGB=000000). High/true colour games (15/16/24 or 32bit) usually use something like pink (RGB=FF00FF) for transparent. If you want non-transparent black, use a near-black (like RGB=040404). For this tutorial I haven't spent much time on them, but these are my tiles (when you have drawn them, they need to be put in a grid like this to import to the map editor, if you are going to leave gaps to fill in later, don't use black as this is ignored on import, see later in this tutorial):

I have also made some sprites and a parallax graphic in separate pictures files, the parallax must be a multiple of the block size, I chose 128*128, but 256*64 would work as well.

(you can skip this next part if you are going to wimp out and use 16bit colour or higher)
Ok, so I have some 24bit graphics, but the game is going to be in 8bit colour, what now? What you have to do is make a 256 colour colour palette, the best tool I have found to do this (and actually make a good job of it) is Smacker, which is free to use for this purpose. Make a new 24bit graphic and paste a copy of everything that will appear in the game on it, tiles, sprites, colours you want to use for fonts etc, save it in 24bit (I call it 'palette.bmp'). Now get smacker to convert it to a 256 colour bmp file (don't lose your 24bit originals!). You may find you have to specify only 255 colours (0 to 254) as I found DirectX wouldn't let me set the highest index to anything except white. Now convert all your 24bit graphics to 8bit BMP files (again, don't overwrite your original 24bit graphics!) but USE THE PALETTE from 'palette.bmp', this way you get a single optimised palette for all the graphics. Smacker also puts black as the first colour, index 0 - useful for transparency. If you add any more graphics you will either have to convert them using the palette of palette.bmp, or if new colours are used you will have to redo all the steps above.

To show how good Smacker is at reducing 24bit to 8bit, have a look at my Alien Epidemic game, a colour count of my original 24bit graphics shows nearly thirteen thousand colours, and the 256 colour graphics appear nearly identical.

First, generate the palette to use

Now convert the tiles, sprites, parallax etc using the palette you created (palette8.bmp in this case)

Step 3 - Make the map

The map made in this tutorial is called tut1.fmp and is in the tut1data directory, it is already made, but I suggest following the steps below to see how it was made

Load MappyWin32 and select 'New Map' from the File menu. Leave the defaults as they are, click OK. You should see a single black block in the right window, you are always given this in a new map and you can't erase it. It has a special property, it cannot be destroyed.
Time to import the graphics, select 'Import' from the File menu and select the file 'tiles8.bmp' or whatever you called the tile graphics. You will then be asked:
'Make all imported graphics into NEW block structures?'
As this is the first time we have imported the tiles into this map, click 'yes'. You should now see the tiles in the righthand window. If you have the grid on it is obscuring the highlights on the blue wall graphics, so turn it off by pressing Ctrl+G.
It is important to realize that the blocks in the righthand window are 'block structures', if you cut and paste them to move them in a different order, the graphics you imported are unaffected. Click on the white block to select it, then cut it with Ctrl+X (or use cut from the edit menu). Now double click the first (black) block, then the small black square above the letters 'BG'. You are now shown the raw graphics, scroll down and you will see the white square still exists! This is because however you change the block structures, the raw graphics are not changed, deleted or reordered. It is important to understand how Mappy works, there are four main parts:

The Map Array (and there can be up to 8, these are controlled in the 'Layers' menu) is show in the left hand window, this can reference block structures and anim structures. Anim structures reference one or more block structures. Block structures reference up to 4 graphics tiles (BG, FG, FG2 and FG3) and contain other useful game information. Altering something only affects others if they are higher up the chain, removing a graphic would affect everything, but cutting an animation would only impact the map arrays (if they were using it).
Cancel the 'pick block graphic' dialogue and get back to the 'block properties' one. Because I'm going to be using a parallax layer, I need to mark any blocks that have transparency. This is either the box labelled BG transparency, or the top left of the 'Other' boxes, depending on the version of the editor you are using, but they have the same function. You should still be showing block 0 properties, so click the box for transparency. Click OK, then double click the next block that needs transparency (this is the one shown below, note the block structure number in the bottom right) and click the transparency box

The very next block also needs transparency, but you can get to it more easily by clicking the button to the left of 'OK' that looks like a '>'. Check the transparency boxes for block structures 12,13,14,15,20,21,22 and 23. If you have a lot of consecutive blocks that need something done to them, use Range Edit Blocks from the MapTools menu, also on V1.3 or later, you can use Auto-set BG transparency to set BG transparency for any blocks that have a transparent pixel. There are 2 other blocks that look like they need transparency (33 and 36), but these are different, I want these to be displayed over the sprites (in a call to MapDrawFG). Get the block properties of block 32 (a yellow circle on brick), click the box above FG1, scroll down and select graphic 34 (graphic number is shown on right). You should now see FG1 superimposed on BG in the big pictures, if you can't either your black is not colour index 0, or trans8bit is set to non-0 in mapwin.ini. Get to block structure 36, click on the box above FG1 and select graphic 37. Click on the box above BG and select graphic 1. You can cut block structure 33 out (Ctrl+X) if you want.

As most of the map is going to be brick, select the block structure after the black block, move over the map window and press 'f' to fill it. Might as well save the map now, so select 'Save As' from the File menu, don't save over tut1.fmp, use a different name. You can now draw the map as you like. To test whether your tranparency works OK, go to Preview Setup in the MapTools menu, click the 'Show background with transparency box' and enter '38' as the Block graphic for parallax. OK it, then select MapTools: Anim Preview. Move the map by pressing the arrow keys, you should see if you have checked the right BG Transparency boxes as streaks or opaque areas will appear if you haven't. More advanced features are listed in the MappyWin32 documentation.

The pile of gold is animated, well it will be. Animated blocks are simple to do, change to the animated block list by right clicking in the righthand (still blocks) window, if there are any animated blocks, click on one. Select 'new' (Ctrl+N), then double click the new animated block. Click the 'reference image' in the top left and pick a graphic with the coins in, all animated blocks have a reference image that is shown when the block isn't animating (such as in the map editor). Now click the 'insert' button and click each of the five gold coin graphics in order, hit OK. Change the delay to 14 and the type from NONE to LOOPF. You can now put the block in the map just like a still block.

You can make the map how you like, but I put a solid 'wall' all round the outside as it stops sprites wandering off the map, which leads nicely to collision detection. In this game there are two sorts of collisions, one for tiles that can't be walked on, and one that stop bullets. All the blue wall tiles are solid, and stop sprites and bullets. The 'hole' tiles stop sprites, but not bullets, so I've checked the top two collision boxes on the wall tiles, but only the top left one on the 'hole' tiles (I'm using the topleft for sprite collision, and the topright for bullet collision, it's entirely up to you what you use the information in the block properties for).

Some tiles are going to be special, for example the pile of gold coins can be collected, and the switch can be pressed. I am going to use the bottom left number box in block properties to determine the type of tile. 0 (default) will mean normal, 1 = gold, 2 = switchopen, 3 = switchclosed, 4 = exit, 7 = crumbling block. I'm also going to use the next two boxes to indicate the offset to the door that will open/close when you use a switch, also the two boxes above can indicate the offset of the connected switch. Because I want blocks with the same graphics, I copied and pasted them, then changed the values of the boxes. Remember these values are in hex, the top two boxes are longs (8 digits), the two under them are short (4 digits), and the last 3 are char (the ones I used, 2 digits).

Lets say I forgot a graphic, like the 'exit', I would just change my graphics file, then import it again, but say 'no' to the make new block structures question, but 'yes' to the overwrite existing graphics. If you left the block structures from the first time you imported the graphics, you will see the new graphic in one of those, otherwise, click where you would like to put the new graphic, press Ctrl+N (to insert a new block structure), double click it, then select the graphic for the BG. For this reason it is better to start with a big picture for your blocks (say 640*480) filled with a colour other than black, then the first time you import it, make new block structures, then when you draw more blocks on the picture you can reimport it, don't make new block structures, but do overwrite existing graphics and they will appear in the corresponding block structure in the still blocks window. Remember when you have finished your map you can delete unused block structures, then block graphics and they will be removed from the map. One thing I've seen a lot is people altering their graphics, then importing them as new block structures and cutting the old ones, this is wasteful as all the old graphics remain in the map, and the blocks currently in the map array are lost. Also note you can export the graphics as a .BMP file.

Putting sprites in the map

Mappy is not a sprite editor, but you can achieve that purpose in some cases. There are two main sprite systems for 2D games.
1: Global coordinates. Sprites are help in a linked list or array and have an x and y position in pixels, when they are drawn, the map offset is subtracted from this, so they scroll with the map. This should be easy to understand. Collisions between sprites and map are determined by dividing the coordinates of one or more 'collision points' by the block size and examining the block properties with MapGetBlock. This system is good if you want free movement and don't have too many sprites.
2: Sprite array. This is the system used in the tutorial demo source, sprites are put in an array that corresponds to the map, it is easier to check collisions etc as you just examine neighbouring cells. You should be able to see how this works by looking at the tutorial source
To put sprites in your map using Mappy, choose 'Add layer' from the 'Layers' menu. Now alter the block properties of blocks for however many sprite types you are making so one of the fields has a number in it (look at tut1.fmp). Now place these blocks where you want the sprites to start. A useful feature here is onion skin. This allows you to see another layer ghosted so you can put sprites in the right place. Select 'Layer 1' from the 'Layers' menu, now select 'Onion Skin' from the Layers menu, click both boxes and leave the Background layer on 0. You can now edit layer 1 without changing layer 0, but still see where things are. Don't forget to turn Onion Skin off when you're done.

Step 4 - Write the game

There is complete source for a simple game in the source directory, it is documented with comments in the source files so you should read them to see how it works. You should uncomment USESOUND from tut1.h if you are using the SEAL audio library (MappyDX) or JGMOD (MappyAL). There is an already made executable called tut1dx.exe which you can run to see how it should work. Don't forget to unzip the appropriate Mappy playback library to your source directory. If the Release number is less than 7, you'll need to change the line in tut1.h from #define RBBLKINC 1 to #define RBBLKINC 32

Allegro and DJGPP/mingw
You will need to compile the following, example command:
gcc game.c alstuff.c mappyal.c -O2 -Wall -o tut1al.exe -ljgmod -lalleg
(If you aren't using JGMOD, don't type the jgmod part). The tut1al.exe file must be in the directory below the TUT1DATA directory in order to run (ie you should be able to see the tut1al.exe file and the TUT1DATA folder itself at the same level).

DirectX SDK
This is an example compile line for mingw32:
gcc game.c winstuff.c dxstuff.cpp mappydx.cpp -O2 -Wall -mwindows -fvtable-thunks -o tut1.exe -lwinmm -ldxguid -lddraw
For IDE compilers you will need to make a Win32 GUI project and add these files to it:
game.c (all game functions)
winstuff.c (windows startup and message handler)
dxstuff.cpp (directX and C++ interface to mappydx)
mappydx.cpp (from MappyDX playback lib, see note below)
ddraw.lib (part of your DirectX SDK)
audw32vc.lib (optional - part of SEAL, there is a Borland version of this in the extras folder)
The mappydx.cpp file needs to be changed at the top, change the corresponding lines to look like this:
#define MSCRH 352
#define MBSW 32 /* MappyDX R7 or lower */
#define MBSH 32 /* MappyDX R7 or lower */
The resulting exe file needs to be in the directory below TUT1DATA to run (ie you should be able to see the tut1.exe file and the TUT1DATA folder itself at the same level), note for Visual C users, this may not be where you expect! You will know if you run from the wrong directory as you will get a 'tut1.fmp not found' error.

Credits:
Tutorial by Robin Burrows