Mappy

DISCLAIMER

THIS PROGRAMME IS SUPPLIED 'AS IS' WITHOUT ANY WARRANTY OR GUARANTEES.
BY USING THIS PROGRAMME YOU UNDERSTAND AND AGREE THAT I CANNOT BE HELD
RESPONSIBLE FOR ANY LOSS OR DAMAGE HOWEVER CAUSED BY THE USE/MISUSE OF IT.

CONTENTS
1 Introduction
2 Compiling Mappy and playback library
3 Starting Mappy
4 Map Editing Screen
5 Block Editing Screen
6 Animation Editing Screen
7 Using the playback library and examples
8 The FMP file format
9 Version history and The End

------------------------------------------------------------------------------
                                  MAPPY 1.01
------------------------------------------------------------------------------

Available from: http://www.geocities.com/SiliconValley/Vista/7336
Or:             http://www.rbsite.freeserve.co.uk
Author's email: rburrows()bigfoot.com

1 Introduction

   This documentation is for the DOS and WinAllegro (DirectX under Windows)
versions. Note that if you have Windows 95/98/NT or compatible, MappyWin32
is probably a better editor to use (available from the site above).

   If you got the mappywa EXE, there is a file called allegro.cfg which sets
the application to run in a window. If you want to run fullscreen, rename
this file to something else.

   Welcome to the latest update to Mappy, a utility for producing tile based
maps for games. It works by importing standard picture files (BMP, TGA, PCX)
and taking 'blocks' out of them. You can then make something called a 'block
structure' which holds information about this block. The block structure
Mappy uses looks like this:

typedef struct {                   /* Structure for data blocks */
long int bgoff, fgoff;             /* offsets from start of graphic blocks */
long int fgoff2, fgoff3;           /* more overlay blocks */
unsigned long int user1, user2;    /* user long data */
unsigned short int user3, user4;   /* user short data */
unsigned char user5, user6, user7; /* user byte data */
unsigned tl : 1;                   /* bits for collision detection */
unsigned tr : 1;
unsigned bl : 1;
unsigned br : 1;
unsigned trigger : 1;              /* bit to trigger an event */
unsigned unused1 : 1;
unsigned unused2 : 1;
unsigned unused3 : 1;
} BLKSTR;

Offsets to these block structures are placed in the 'map array'. This is a
grid containing short int values. By adding the value to the start of the
block structures memory, you now have all the necessary information about
the block contained there. You can think of the map array like a chessboard,
with each square containing a block structure offset.
If the value stored in the array is negative, it is an offset to an
animation structure, loop forward, reverse, pingpong are available through
a defined sequence of blocks. Each animated block can have it's own speed.

typedef struct { /* Animation control structure */
signed char antype; /* Type of anim, AN_? */
signed char andelay; /* Frames to go before next frame */
signed char ancount; /* Counter, resets to andelay */
signed char anuser; /* User info */
long int ancuroff; /* Points to current offset in list */
long int anstartoff; /* Points to start of blkstr offsets list */
long int anendoff; /* Points to end of blkstr offsets list */
} ANISTR;

Important:
As of V0.35, if a map exists when you try and save, the old file will be
renamed ?.BAK (where ? is the name of the map). If you need to get at this
handy backup, either rename it ?.FMP or type in the full name in the map
load file selector. A previous file named ?.BAK is replaced by the backup
when saving occurs (ie. deleted).

That's it! Obviously Mappy is a bit useless unless you can write
a game to use the maps it makes, although I think it's quite fun to play
about with. There are examples of how to use a Mappy made map included
in the Mappy playback library zip files. See the next chapter for details.

If you have any comments, bug reports, ideas or complaints, PLEASE e-mail
me at rburrows()bigfoot.com

------------------------------------------------------------------------------

2. Compiling Mappy

   If you downloaded the .exe file, you can skip this section, remember there
is a Windows application version (MappyWin32) and DirectX version (MappyWA).
   To compile Mappy, you need DJGPP 2.01 and Allegro WIP or later. You can
get DJGPP from http://www.delorie.com/djgpp/ and Allegro from
http://www.talula.demon.co.uk/allegro/
After installing the above programmes (email me if you have problems, but if
you follow the instructions in readme.1st you should be OK) simply make sure
you are in the directory you unzipped the Mappy files to and type:
buildit or buildwa
Or, you can double click buildit from Win '95 (DJGPP/Allegro)
Or, you can double click buildwa from Win '95 (mingw/Allegro).
Oh, if you're in DOS you'll probably want smartdrv enabled, and CWSDPMI in
your current directory.
If all went well you can now run Mappy!

------------------------------------------------------------------------------

3. Starting Mappy

   Just type 'mappy' or double click it. You'll need cwsdpmi.exe in the same
directory if running in DOS. If you already have a map you can type
'mappy project.fmp' where 'project' is the name of the map.

   If you didn't load a previously made map, you now get a screen to select
the resolution Mappy will run in. Choose something sensible, Mappy supports
all modes 320*200 and above, in any colour depth (number of colours), but
your graphics card probably won't. Mappy now (V1.01) can display 24bit maps
on 16bit screens etc. If you choose a really high res
mode and your monitor goes bananas, Press ESCAPE, then O (as in 'OK'), mappy
will exit.

   You should now see a requester asking if you want to load a project, or
start a new one. Click 'NEW'. The new requester is important, the things you
MUST get right are the block width and block height. This along with the
screen depth CAN'T be altered later on.

   In the very unlikely event of Mappy locking up, you can press ctrl-alt-end
to forcibly end it (as you can with most DJGPP made programmes).

   Note: in 256 colours, colour 0 is treated as transparent for foreground
blocks. In higher colour modes pink is transparent Red=MAX, Green = 0,
Blue = MAX.

   Tip: In Windows '95, associate .FMP files with Mappy, then you can just
double-click a .FMP file to load it into Mappy.

------------------------------------------------------------------------------

4. Map Editing Screen

   This is the main screen to edit the map, but you'll need some blocks to
put in it. What? You haven't made any graphics? Duh. Click the 'save' button
and type a name to save the map under, the extension '.FMP' (Flexible MaP) is
automatically added. Click 'exit', go into your paint programme and make some
blocks. Assuming 0,0 is the top left of your picture, you should arrange your
block graphics so they are on 'block boundaries'. Example: I chose blocks
of width 16 (pixels) and height 16 (pixels). Therefore I put the first block
top left at 0,0, the second at 16,0, the third at 32,0 until the end of the
row, then I put a block at 0,16, then 16,16, then 32,16 etc. Save the
picture in either .BMP, .PCX or .TGA (preferably at the correct colour depth,
although Mappy will adapt it if it isn't).
   Reload mappy (you can use the shortcut 'mappy project.fmp'). Make some
block structures (see next chapter). You can access the block structures by
right clicking, then left clicking on the structure you want to draw with.
NOTE: The preview hot keys (,./) don't work if you're using brushes.
   As from V0.33 you can create up to 8 layers on his screen, they all use
the same block structures and anims, it's good for putting things like item
blocks on the map where the background could be anything. Use key 9 to go
to previous layer and key 0 to go to next layer. If a layer doesn't exist
(you start off with only layer 0) you are asked if you want to create it.
Every layer created takes up mapwidth*mapheight*2 bytes of memory. A 100*100
block map uses 20,000 bytes for every layer. Unfortunately you can only see
the layer you are editing, but flipping between layers with the 9 and 0 keys
should let you line things up. Use the 8 key to delete the current layer,
try not to split the layers doing this (ie. don't create layers 0, 1 and 2
and then delete layer 1). The current layer is displayed just to the left of
the XY box.
   As from V0.35 you can add information about the project by pressing the
'i' key. This is stored in the .fmp file when you save. It isn't secure, so
any idiot can change it, but it's handy for noting who made the map, and
what it's called. Each line has max 64 characters. At present it's stored
near the start of the file, so it should be visible in a text viewer.

Right Mouse = Select a still block (left mouse on block, right mouse advances
              to animated blocks)
Left Mouse (on map area) = paste current block/brush (hold button to draw)

NEW  = New project (current project lost if not saved)
EXIT = Quit Mappy (Warning to save given)
LOAD = Load a Mappy (.FMP) file
SAVE = Save current project to a Mappy (.FMP) file
BLKS = (Says 'BLOCKS' on high res) Block Structure section (next chapter)
ANIM = (Says 'ANIMS' on high res) Animation Structure section
BRUSHES = Grab a brush, click this, then click a number (1-8), then brush
          the area you want from the screen (just like a paint programme).
          Any structure '0' blocks are transparent, so non-rectangular
          brushes are possible. You can get the brush by clicking on its
          number in the map editor, to go back to normal mode, right click
          and choose a block structure as normal. The brush will only be
          pasted on the map if it will ALL fit on the current screen. When
          you save your project, empty brushes are ignored, so when you reload
          the brush may be on a different number.
RESIZE = This is dead clever. Made your map too short/long? SAVE IT FIRST,
         then click 'resize'. Type the new width and height in the boxes,
         then select the 'map centering' (you can do that in any order).
         If you want the map to stay at the top left, click the top left
         button. The extra blocks will then be added to/taken away from the
         bottom and right of the map. You can work the rest out.
SCREEN = Allows you to change the screen resolution.
         NOTE: If you make the screen bigger and it reveals an area not
         on the map (easy to do if you are near the bottom or the right),
         Mappy will crash out.
EXPORT = Exports various bits of the project as follows:
         Colour Map = 256 * 3 bytes of 0xRRGGBBRRGGBBRRGGBB etc, note Allegro
         doesn't allow true 24bit palettes, so its better to get this from
         you original graphics file.
         Anim&BlockData = If you have animated blocks, the first long int is
         how big the animation data is, followed by the animation data, 
         followed by the block structure data. If no anims exist, only the
         block structure data is stored.
         blockwidth*blockheight*(blockdepth/8) big, one after the other.
         Map Array = Array of short ints (mapwidth*mapheight*2)
         Graphics TGA = Saves graphics blocks at the specified blocks per row.
         It's much better to use the .fmp file though!
12345678 = If you have a brush on one of these numbers, click to retrieve it.

Hotkeys:
i = Edit author information
g = grid on/off, very useful for lining things up, also handy for when you
    right click to select a structure.
p = pick block (still or animated) under mouse cursor for drawing.
r = reveal animated blocks. Shows an 'A' over any animated blocks in view
    until r is released.
d = dump screen minus control panel and pointer to scrndump.tga
SHIFT + d = dump entire map as one HUGE targa file (scrndump.tga). I tried
            one at 2080*2080 pixels and it was OK, but took it a while, and
            made a 4MB picture file! USE AT OWN RISK!
f = *NEW for 1.0BETA* Fill with current block/anim or brush, depending on
    what is currently selected. If you are filling with a brush, the top left
    of the brush will start below the mouse pointer, and the brush will repeat
    over and over in the fill area. If you hold down SHIFT and press f you can
    fill with random blocks from the brush, try it and see, useful for terrain
    etc, weight blocks by having more of one type in the brush...
SHIFT + z = Undo, will undo the last paint operation (such as Fill, and anything
            pasted with the left mouse button). Pressing SHIFT + Z again will
            undo the undo.
a = preview animation, it may flicker a bit, don't count on the speed!
2 = Go to Block section (same as clicking 'BLOCKS')
3 = Go to Anim section (same as clicking 'ANIM')
, = (comma) previous block/anim in sequence to draw with (preview shown)
. = (fullstop) next block/anim in sequence to draw with (preview shown)
/ = (forward slash) show current still/animated block ('A' denotes anim)
F1 = Show keyboard short cuts (hold F1 down)
8 = delete current layer (you are asked to confirm this).
9 = Previous map array layer
0 = Next map array layer

ESC = Same as EXIT
ARROW KEYS = Move screen one block in any direction.
SHIFT + ARROW KEYS = Moves a whole screen of blocks in any direction.

------------------------------------------------------------------------------

5. Block Editing Screen

   You will see the current structure in the top left, along with it's
number. The black shape is the collision mask of the block. The first thing
you will want to do is click 'IMPORT', select your block graphics file (.BMP,
.PCX, .TGA), and I recommend letting mappy assign each graphic into a new
structure, you can always cut the ones you don't want afterwards. IMPORTing
more pictures adds the graphics/block structures to the end of the existing
ones except in the situation listed below.
NOTE: You can click on any of the blocks in the middle slice of the screen
to select your current block.
   As from V0.34, if you click IMPORT, then answer 'NO' to making new
structures, you have the option of overwriting existing graphics. What use is
that? Well, as Mappy doesn't let you alter the graphics (maybe in a later
version?) you have to use a paint programme on the original picture file to
update them, and without this feature you could only import them on to the
end of the old graphics effectively giving you two lots of the same tiles.
The only way to replace them was to 'edit this' every block and change the
BG to the new graphic, then delete the old graphics in the 'G' section.
Not very good. Now, if you say 'YES' to the 'Replace existing graphics'
question, it will overwrite existing tiles starting at the 2nd block (after the
default blank tile that is always there). You can have more blocks than in
the original picture you imported, but bear in mind they won't automatically
get a new block structure (create with 'NEW'). You may get a better idea by
simply doing a test, just make sure you have saved your map first as you are
scrapping the existing tile graphics (but not block structures). The block
structures will now display the graphic that replaced the original one in
that position.
   As from V0.35 you can now alter the graphics without using a separate
paint package. Clicking on the 'G' or 'Graphics' button allows you to delete
or edit the raw graphics, the mode is changed with the edit/delete buttons
in the bottom left. In edit mode, clicking on 'new' will add a new graphic
to the end of the graphics, you are asked to choose a graphic to copy from
and this is copied to the new graphic. Clicking on a graphic in 'edit' mode
will bring up the graphic editor. Hold F1 down to see all the functions.
Sometimes buttons seem a bit unresponsive, needing a second click, I don't
know why this is but it isn't too bad (ie. I can't be bothered to sort it
out at the moment).

Click on a structure to get the current structure.

EDIT THIS = Allows you to alter the properties of the current structure.
            BGOFF = The main graphics block, pick from the graphics imported.
            FGOFF,2,3 = Overlayed blocks (allows sprites to move between
            bgoff and fgoff) also, imagine an overhead view, you could see
            the roofs from outside, but going into a building, the roof
            (fgoff) would disappear and you would see bgoff (inside).
            You can use the other parts for whatever you like.
< > = Next/Previous structure, better to click on the structures below.
IMPORT = Imports graphics blocks from a .BMP, .PCX or .TGA file.
         New in V0.34, you can overwrite existing graphics to update them.
PASTE = Paste a copy or cut block AFTER the current block.
COPY = Copy current block.
CUT = Cut current block.
MAP = Back to map editor screen.
NEW = Insert a new block structure AFTER the current block (the edit block
      dialogue starts immediately to let you define the new block).
G = View graphics blocks, allowing you to delete unwanted ones, you will be
    warned if you try to delete a graphic that is in use.

Hotkeys
g = grid on/off
e = edit current block
x = cut
c = copy
v = paste
n = new
ESC = back to map editor
1 = back to map editor
F1 = Show keyboard short cuts (hold F1 down)

Note: The block editor is quite intelligent if you are cutting, pasting etc,
will not muck up the map array.

------------------------------------------------------------------------------

6. Animation Editing Screen

   Don't get confused by this. You need to know what you are seeing on each
screen in the animation section. The first screen shows the blocks that
represent each separate animation below the white bar at the top. An 'E'
shows you the end. In the top left of the white bar is the reference block
for the currently selected animation, this is the same as the corresponding
block in the main part of the screen. To the right of this are the first few
blocks of that animation (these cycle through when the block is animating).
The reference block is not part of the animation, and is only shown when the
block is NOT animating.
NOTE: You can click on any of the anims in the middle slice of the screen
to select your current anim.
   Pressing 'e' or clicking on the white bar lets you edit that particular
animation. You will need to create animations with the 'NEW' button.
   When editing an animation, the reference block stays in the top left. You
can change what the reference block looks like by left clicking on it then
picking a new one. Remember, the reference block isn't part of the animation.
   The white triangle that appears shows where blocks are going to be added
or deleted. To add blocks to the animation sequence, right click. Left click
on the still blocks you want to add to the sequence, you can add as many as
you want before right clicking back to the anim edit screen. Click on the
'NONE' button to cycle through the animation options. Increase the delay to
slow the animation down, decrease to speed up. Click on the white triangle
to cut the block underneath out, click on a different block to move the
triangle. Right click to add more blocks at the triangle.
   Try loading the example file. If you go back to the main map editing
screen and place some of your new tiles, you can press 'a' to preview them,
if nothing happens it's likely that either:
The anim type is still 'NONE' for that block, or
you have placed a 'still' tile instead of an 'animated' one (right click
twice on the map screen to access them, the type of block you are placing is
indicated at the bottom), or
The delay value is too high in either the block or anim preview, or
You haven't added different still blocks to the anim sequence, see example.

Hotkeys
g = grid on/off
e = edit current anim
x = cut
c = copy
v = paste
n = new
ESC = back to map editor
1 = back to map editor
F1 = Show keyboard short cuts (hold F1 down)

------------------------------------------------------------------------------
7. Using the playback library.

The playback library has been moved to it's own zip and has it's own
documentation. Get MappyAL from the Mappy homepage.

------------------------------------------------------------------------------
8. The FMP file format.

The easiest way to see how it works is to look at LoadMap () in MappyAL
It is based on the old Amiga IFF format, the first 12 bytes are as follows:
4bytes ASCII = 'FORM'
long int = size of file less header (which is filesize-8)
4bytes ASCII = 'FMAP'

NOTE: The chunk size long ints like the one above are stored in 'Motorola' 
format, NOT Intel. You will have to byteswap to get the correct value, ie:
Bytes 1,2,3,4 need to become 4,3,2,1. See the byteswapl function in mappypb.c

The chunks in the file follow on one after the other, and consist of an 8byte
header, and the information specific to that chunk. See how MapLoad () reads
in the information. The chunks can be in any order, and some chunks may not
be used in a particular file.

Chunk header:
4bytes ASCII = ChunkID (example: 'MPHD')
long int = size of chunk data less header

These are the chunks as of V0.36:
ATHR - Up to 4 ASCII strings of author information, separated by 0 values,
       always an even size.
MPHD - Map header, see struct in mappy.c
EDHD - Editor information, see struct in mappy.c
CMAP - Colour palette for 8bit maps, red byte, green byte, blue byte for
       however many colours are needed (so usually 256*3 bytes).
BKDT - Block data. Contains BLKSTR structures for however many block
       structures were made.
ANDT - Animation data. Contains ANISTR structures for however many
       animation structures were made, and also animation data.
BGFX - The raw graphics in whatever format the map is in. Examples: 8bit:
       mapwidth*mapheight bytes per block, in forward format *numblocks
       16bit: mapwidth*mapheight*2 bytes per block, each word contains
       5 bits red, 6 bits green, 5 bits blue. See MapCorrectColours in
       mappypb.c
BODY - An array of short ints containing +ve offsets into BKDT, and
       -ve offsets into ANDT.
LYR? - Where ? is an ASCII number form 1 to 7. These are the same size and
       format as BODY, and allow object layers to be used.
You can add your own chunks to a map file, but if you load it into mappy, 
when you save it, those additional chunks won't be preserved.

------------------------------------------------------------------------------
9. Version history and The end.

Release version 1.01
Bigger (4mb) tile graphic buffer.
High colour maps can use any high colour depth (ie 24bit maps on 16bit screens)
Xenon2000.FMP now works.
You can now use windowed modes (mappywa)
Compiled with Allegro4.0

Release version 1.0
Inverted dialogue colours (now black on white)

Additions since 0.36
Fill functions (with still, anim or brush)
Undo function

Additions since 0.35
Several minor bugs fixed including:
* Lo-res High/True colour colour selector now works (was difficult to test
because
my card doesn't support these modes)
* Graphics block selection now works over mutliple screens, was broken for some 
reason
* Tidied main () up a bit so it returns a value.
* Corrected spelling mistake on exit ('wil').
Sped BG routines in mappypb up by about 80%
Modified readme to include FMP file format and more detailed playback info.
Added #ifdef to mappypb.h, hopefully this will allow linking with C++, can
someone let me know?
Source and binary zips contain different files than previously:
map036s.zip contains:
 readme.txt buildit.bat mappy.c mappypb.c mappypb.h 8bit.fmp 16bit.fmp
 pbdemo1.c pbdemo2.c pbdemo3.c
map036b.zip contains:
 readme.txt mappy.exe cwsdpmi.exe 8bit.fmp 16bit.fmp

Additions since 0.34
You can now edit graphic blocks (click 'g' or 'graphics' from block editor).
You can now add author info by pressing 'i' on the map editor.
?.BAK file kept of previous map (a backup).

Additions since 0.33
Made exe with Allegro3.0 (was using WIP)
Added the SHIFT + d function, dumps map as a HUGE graphic file (scrndump.tga)
Doesn't display 'no error' message (prevents 'Finished' window in Win '95)
Fixed major bug that crashed Mappy when brushing BR to TL.
Fixed minor graphic bug in Block editor.
Added the option to overwrite existing tiles (now easy to change graphics).
Recompiled exe with -O2 instead of -O3 (just for variety).
Added BUILDIT.BAT for easy generation of Mappy, playback and demos.
Default anim delay is now 3 instead of 7.

Additions since 0.32
You can now edit 8 layers in one 'map' (Keys 9 and 0 change layer), this
is good for putting things like objects over the background
In 256 colour mode, fgcolour is now set to the brightest colour in an
imported image's palette instead of colour 255
Added functions like MapDraw8BGT to the playback library, allows
transparent drawing for parallax or object layers etc.

Additions since 0.31
Playback library included! (It really is very good)
Map drawing is much much faster (thanks to Ryan Blazecka)
LoadProject now ignores chunks it can't understand instead of crashing

Additions since 0.30
Fixed a stupid bug in animation preview (when 'a' is pressed) where each
frame could last several minutes (preventing ESC working).
Fixed a stupid bug when no anims were present and you right clicked twice.
Minimum size of a block is now 8*8.
Some info on new map dialogue.
Added these hot-keys to map editor screen:
2 = Go to Block section (same as clicking 'BLOCKS')
3 = Go to Anim section (same as clicking 'ANIM')
, = (comma) previous block/anim in sequence to draw with (preview shown)
. = (fullstop) next block/anim in sequence to draw with (preview shown)
/ = (forward slash) show current still/animated block
F1 = Show shortcuts for current editor screen

Added these hot-keys to block and anim sections:
1 = Back to Map Editor screen
F1 = Show relevant help screen

For anyone who wants to make maps smaller than the screen, I suggest
making a larger than screen map, and altering it when you load it in
your own programme (leave unwanted parts blank).
NOTE: Sometimes the 'Resize' thing disappears when you click on the
'resize' button. If you go to a different section, or save the map
then load it, the problem should go away. This isn't a very important
bug, and doesn't do anything nasty, I'll fix it if I can be bothered
in a future version.

Additions since 0.23:
15bpp mode (32K colours) now works.
Lots of new hot keys.
Animation now works.
Some bugs fixed.
Major bug in Import fixed.

NOTE: using some keyboard shortcuts may leave slight changes in the screen
display, these are purely aesthetic and don't affect Mappy.

                               -------=======-------

   This documentation may still be quite poor, but at least it's better than
the last one! I really appreciate feedback on this, if you don't like it,
tell me why, and I'll try to improve it.

Robin Burrows rburrows()bigfoot.com
http://www.geocities.com/SiliconValley/Vista/7336

Acknowledgements:

Hopefully this will be correct when Mappy is finished:
DJ Delorie - DJGPP, an excellent 32bit C compiler> http://www.delorie.com
Shawn Hargreaves - Allegro, a fine gfx library> http://www.talula.demon.co.uk
Charles W Sandmann (sandmann()clio.rice.edu) - for CWSDPMI
Stefan Schimanski - WinAllegro http://1stein.home.pages.de
Anyone who actually bothered emailing me or will in the future (hint).

*** Notes on the AmigaOS port, it is designed for low screenmodes, 
and 320x200 gives the best result, so I recommend to use a windowed 320x200
screenmode.