Welcome to probably the first generic map editor for the Archimedies
Designed & programmed by Nicholas Kingsley
This is version 2.02 
Updated : 26/4/96, 27/4/96, 28/4/96 by Nicholas Kingsley
--------------------------------------------------------------------

1.  INTRODUCTION
----------------

!Mapper is a program for designing game maps.  
"Whats a game map", I hear you cry...  Well, when your designing a 2D game 
like Chaos Engine, Lemmings etc, you need a way of storing the background 
graphics.  You could type in all the data manually, design your own
custom map editor, or you could do things the easy way and let !Mapper do
all the hard work for you...  Being generic it can handle sprites in either
mode 12, 13 or 15 and handle a 255 * 255 game map.

THIS SOFTWARE IS SHAREWARE.  TO OBTAIN THE NEXT VERSION, SEND 5 TO
THE ADDRESS AT THE BOTTOM OF THIS FILE, WITH YOUR NAME & ADDRESS (AND 
E-MAIL ADDRESS IF YOU HAVE ONE).

2.  THE FILES
-------------

In order to run this program, you need the following files :

!Boot
!Mapper
!Run
!Sprites
GRAPHICS - Shapes 
MODULES  - MenuUtils
DEMO     - NumShapes - Optional
         - Obeyfile - Optional
ROUTINES - Clear

The program takes up 255K to allow for editing of 255 * 255 maps!

3.  THE IMPROVEMENTS
--------------------

Following from the success of V1.00, !Mapper has been updated to make it
even more OS friendly.  The improvements are :

I)   2 Editing modes - NORMAL and ABSOLUTE
II)  Drag and drop for all loading and saving
III) Save data without the header
IV)  All options are in windows

3.  THE PROGRAM
---------------

Once the !Mapper icon has been placed on the icon bar, pressing the MIDDLE
mouse button will display the following options :

1.  Info - Gives information about the program
2.  Main menu - Displays two options.  See "MAIN MENU"
3.  Mode - Selects the type of mode the sprites were created in.  See "MODES"
4.  Map size - Defines how large the map is.  See "MAP SIZE"
5.  Save map - Saves map.  See "SAVING DATA"
6.  Clear map - Clears the map.  See "CLEARING MAP"
7.  Edit map - Allows you to edit map.  See "EDITING MAPS"
8.  Quit - Exits program, and allows you to save any modified data before you do so.

In addition, the following items are displayed when you select "EDIT MAP":

1.  On the bottom left of the screen is an arrow pointing left.  Use this
to scroll the sprites left (if possible)
2.  On the bottom right of the screen is another arrow, this time pointing
right.  Again it is used to scroll the sprites right (if possible)
3.  On the bottom row between the left and right arrows, are your sprites
that can be used for a given mode.  Move the pointer to one of these
sprites to select it for plotting in the map.

The following status items will now be explained :

1.  X=000/000/000 - The first 3 digits represent the UDG X position
                    The next 3 represent the map X position
                    The last 3 describe the size of the map in the X 
                    direction (so, if it says 041, you have defined a map
                    of 41 bytes running from 0 to 40)
2.  Y=000/000/000 - The first 3 digits represent the UDG Y position 
                    The next 3 represent the map Y position
                    And the last 3 describe the size of the map in the Y
                    direction, running from 0 to number-1
3.  Pos=0000      - This is the actual location in the map data
4   Select=000/000/xxxxxxxxxxxx - The first 3 digits describe which sprite
    or                            you have currently selected
    Select=000/000/000            The next 3 represent the maximum number of
                                  sprites that are valid.  The remaining set
                                  of characters are different according to
                                  which mode you are using.  If you are using
                                  the normal mode, then the x's 
                                  represent the sprites name.  However, if
                                  you are using absolute mode, then 3 digits
                                  are displayed.  These represent the value
                                  stored in the map area.
                                  
Note : Valid means the number of sprites that can be used for a given mode.
Although you may have more sprites in the sprite area than those listed,
a sprite is only valid if it is 16 * 16 pixels, and has been designed in
the mode as given by the "MODE" option.

4.  CONTROLS
------------

Mouse Up/Down/Left/Right - Move pointer up/down/left/right and if in map 
                           area, will also move the flashing positioning 
                           cursor
SELECT - If in map area, place current select sprite in map, else either
         select sprite under pointer or scroll sprites left or right
MENU   - Delete sprite at given location, and, if in normal mode then put a 
         '0' at the pointers location.  However, if you are in absolute mode
         then the delete value as specified in the Main Menu window is used.
         If a sprite exists with the delete value, then the sprite is 
         displayed, otherwise the pointer position is cleared.
ADJUST - Return to desktop
HOME - Position map at the top left
CURSOR LEFT - Scroll map left
CURSOR RIGHT- Scroll map right
CURSOR UP   - Scroll map up
CUSROR DOWN - Scroll map down

5.  GRAPHICS
------------

In order to edit a map, you need some sprites.

These MUST be designed in either modes 12, 13 or 15, MUST be 16 pixels
by 16 and the sprite mode MUST equal selected mode.

Any sprites that do not conform to this will be ignored, and you will not
be able to use them.

If the number of sprites exceed the number that can be displayed, use the
left and right arrows to scroll through the list.

6.  MAIN MENU
-------------

The MAIN MENU allows you to select the editing type, whether the 8 byte
header is saved along with the map data, and which delete value you would
like to use.

Absolute mode can only be used if all the valid sprites are between 0 
and 255.  This mode is designed to be used with the FastSpr module, and
as such with ignore all animations apart from the first one.

When a sprite is to be plotted, using absolute mode, then the sprite number
is the value stored in the map area.  When a sprite is to be deleted, then
a delete value is used.

Normal mode works differently.  The value store in the map is the index
value in the sprite list.  For example the first sprite would store a value
of 1, the second 2, and so on.  The delete value is 0.

Selecting the HEADING option, will prevent the 8 byte header from being
saved.

7.  MAIN MENU
-------------

There are three valid sprite modes, which can be used in this program.  
These are modes 12, 13 and 15.  If any sprites don't match one of these
modes, then it is ignored.

8.  MAP SIZE
------------

These two values define how large the map area is.  The minimum value is
1, while the maximum value is 255

9.  SAVING DATA
---------------

To save your map, drag the data icon to your directory, or alternatively
just press RETURN, or the OK button.

The map data will then be saved, and if the HEADING option is not set, then
the data will be prefixed by a header.  See Appendix A for a detailed
description of the header.

NOTE : If the HEADING option has been set then the program wil assume
you will want to use all the current values for editing. 
 
NOTE : This program is NOT designed to be used over a network.  If you do,
then you may not see some of th filing messages as described in APPENDIX A.

10.  CLEARING MAP
-----------------

This option will clear the map area with either a zero (if absolute mode is
not switched on), or the value held in the DELETE option.

If you have modified a map, you will be asked to confirm your choice.

11.  EDITING MAPS
-----------------

This option takes you out of the WIMP, and puts you in the editing screen.
The top area shows the map, which the bottom few lines show the status and
all selectable sprites.  See CONTROLS.

NOTE : When you first start, the program will select MODE 13 sprites,
switch off ABSOLUTE and skip HEADING modes.
 
APPENDIX A - HEADER FORMAT
--------------------------

If you save a map with a header, this is it's format :

+ 0 - Version * 100 + improvement value (in this case 150)
+ 1 - Map X Size
+ 2 - Map Y Size
+ 3 - Mode that the map was defined in
+ 4 - > 0 if ABSOLUTE mode was set
+ 5 - Delete value
+ 6 - Reserved for future enhancement (must be 0)
+ 7 - Reserved for future enhancement (must be 0)
+ 8 onwards - Map data (When not in ABSOLUTE mode : 0 - No sprite to plot
                                                  > 0 - Sprite to plot)

Note : If absolute mode is not switch on, then the number store in the map 
is the order number of the selected sprite.  If absolute mode is on, then
the value store is the sprite number.
 
APPENDIX B - ERROR AND WARNING MESSAGES
---------------------------------------

The following is a list of error messages you may come across whilst using
the program :

1)  Delete value is not in the range 0 - 255
Make sure delete value is in the required range

2)  The X/Y value is not i the range 1 - 255
Make sure that the X and/or value is in the required range

3)  There is a problem loading this sprite file.  There is either no system sprite memory or the file is protected
This error appears if there is no system sprite area or the input file is
protected.  De-protect the file and/or increase the system sprite area

4)  At least one sprite is NOT numeric or sprite number exceeds 255
This only appears in ABSOLUTE mode.  The sprite number is either greater
than 255, or there is a non-numeric character in at least one sprite, in
which case the sprite would have to be renamed.  If you exceed 255 sprites,
then please contact the author about a program update.
NOTE : If you modify a sprite, you must remember to re-load the sprites
into the system sprite area.

5)  You must have a valid filename/The filename is currently being used by a directory/The filename is currently being used by an image file
The filename is not valid.  Please change it.

6)  The file is locked.  To save data, please unlock file and try again/The 
file does not have write acess.  Please change file protection and try again
The file is not open for writing.  Please de-protect the file and try again

7)  Unable to save data
General save error.  Disk is protected, not disk present etc etc.

8)  Couldn't open the file
General load error.  Disk doesn't have read access etc etc

9)  The X or Y size values are incorrect
This generally appears if you have saved data without the HEADER, in which
case, you won't be able to re-load the map.  The file could, of course, be
corrupted.

10) Your version of !Mapper is too old to load this map
You are trying to load map data into an earlier version of !Mapper

11) The mode creation is invalid
The program has discover a mode creation value that wasn't 12, 13 or 15.
Generally appears if you have saved data without the HEADER, in which case
you won't be able to re-load the map.  The file could also be corrupted.
          
12) There are some sprites already in the system sprite area.  Do you wish to use these ?
The program has found some sprites already in the system sprite area.
If you select the OK option, you can uses these sprites (if they are
valid of course).  Selecting the CANCEL button will ignore these sprites,
forcing you to load your own.

13) The map has been modified.  Are you sure you want to quit?
If you've modified a map, and you then try to quit the program, this warning
will appear.  Press OK to quit program, or CANCEL to continue with it.

14) The map has been modified.  Are you sure you want to clear the map ?
If you've modified a map, and you then try to clear the map area, this 
warning will appear.  Press OK to quit program, or CANCEL to 
continue with it.

15) You are about to overwrite an existing file.  Do you wish to continue ?
You are about to replace a file with new map data.  Press OK to continue
the save operation or CANCEL to quit saving
   
APPENDIX C - THE DEMO SPRITES AND MAPS
--------------------------------------

The NUMSHAPES sprites consists of sprites which can only be used in
certain modes :

MODE 12 - NORMAL MODE   : acorn, apple, apricot, 99
        - ABSOLUTE MODE : 99 

MODE 13 - NORMAL MODE   : 0, 1_0, 1_1, 2, hello, 1_2
        - ABSOLUTE MODE : 0, 1_0, 2

MODE 15 - NORMAL MODE   : a1, 2_x1, 3
        - ABSOLUTE MODE : 3

(To get the ABSOLUTE MODE sprites, you would have to delete all non-numeric
sprites.  Any sprites that don't appear in any list can't be used because
there width and sizes are too big.)

APPENDIX C - MODULES USED
-------------------------

The MenuUtils module by Alex Petrov was used for the WIMP part.

APPENDIX D - PROBLEMS
---------------------

There are no know problems with the program, but as they say, "there is
no such thing as a working program"... 

As much of the original code from V1.00 was kept, the program is not
terribly well structured or fast.  However, you will only notice a lack of
speed when scrolling large maps.

APPENDIX E - CONTACT
--------------------

For further suggestions and/or the next version, contact :

    Nicholas Kingsley
    100 Orchard Way
    Barnham 
    Bognor Regis

E-Mail (up to June '96) : nicholk@dcs.rhbnc.ac.uk
                             





