			 MapEd - A Map Editor for Age
			   Scott "Jerry" Lawrence
			   jerry@mail.csh.rit.edu
			       1 January 1998
			
This file contains hints and tips for editing maps using the "MapEd"
map editor within AGE.  Note that this documentation is based on the 
pacman map editor.  Other map editors may be supported, and may be
supported differently, although the concepts and interface should 
be extremely similar.

Basic Editing:
1.  Load the pacman variant (pacman, namcopac, pacmanjp, hangly, puckman,
    piranha, pacplus, pacmod) which has the map you want to edit.  The
    maps of some of these differ (hangly has a different map than namcopac.)
    In age, press 'l' to bring up the rom load menu, then select the
    rom you want to load by using the up/down arrows, then select one using
    the mouse button or the space bar.
2.  Start up the map editor.  Press [F5] to do this.  The screen should 
    change to the map editing screen.  If you instead get a message saying
    that there is no map, then you probably did not select one of the
    above pacman variants. (Did you select MsPacman?  MsPacman and her
    variants are not yet supported.)  The map editing screen shows you 
    a few things:
      Left half - the map being edited.  It has a green border around 
      it so you can see where the map ends.  Press the 'u' key to move
      it upwards, the 'd' key to move it downwards, and the 'r' key
      to reset it back to its starting position.  
      
      In the map you will see a green cursor.  You can move this around 
      using the mouse or the cursor keys.  
      
      As in the main AGE editor, the ',' and '.' keys ('<' and '>') 
      change color palettes.  The last palette (the 10th one) is 
      roughly what is used for the map in PacMan.
      
      You can change the tile underneath the cursor using either the 
      '+' and '-' keys to increase or decrease the tile.  To select the
      tile you can also press the 'g' key to Get a tile from the tile
      palette (which is in the lower right of the screen).  The tile 
      palette shows you which tiles are available for use in the map.
      Generally, you can use characters 0xB0 through 0xFF in the map.
      You can also use an empty tile, shown in the very bottom of the
      palette.  When you change into tile selection mode, you will 
      notice that above the tile palette, the mode indicator changes.  
      The number (hexadecimal) immediately above the tile palette is the
      tile that the user is selecting either in the map or in the tile
      palette. When in Tile Selection mode, the arrow keys, or the
      mouse change the position of the yellow cursor in the tile
      palette.  Changes are shown in the main map view.  The HOME key
      resets the cursor position to the tile that was selected when the
      Tile Selector was started, and ESCAPE or the spacebar selects and
      leaves Tile Selection mode.  The mode indicator will change to be
      the color of the cursor in the active mode. (Yellow for the
      map, green for the tiles.)  
      
      The Green cursor in the tile palette shows the current paste-tile.
      This is the last tile you selected when you were in tile selection
      mode ('g').  You can quickly paste this into your map by hitting
      the space bar, or left mouse button, instead of using the '+'/'-' 
      keys or the tile selector.  
      
      One neat trick to do, is that if you see a tile piece you want to
      use elsewhere in a map, move the map cursor over to it.  Then 
      switch to tile selection mode (hit 'g'), then hit the space bar
      or left mouse button.  This selects the tile that the map cursor
      is on.  Now, move the map cursor to the location where you want
      to place this tile piece down, and hit the space bar or left mouse
      button.  Voila.  :)
      
      In the upper right of the screen, you will see some important 
      indicators.  The topmost is which map is being displayed. This
      is useless now, but when MsPacman is supported, it will show 
      which of her 4 maps are being edited.
      Next down is the starting position in the roms. I'm not really
      sure why i left that in there, other than the fact that it looks
      kinda cool.
      
      Next down are four indicators 'B', 'O', 'H', and 'S'.  These show 
      which aspects of the map are being displayed.  These are 'B'ase 
      map, 'O'verlay map, and 'H'ardcoded map.  By default, all three are
      enabled.  They can be toggled with their respective indicator keys.
      The Base map is the blue wall tiles, the Overlay is the regular 
      pellets, and the Hardcoded bits are the Power Pellets.
      The 'S' indicator shows if the map is in stretch mode.  It stretches
      the map to fit in the screen.  It may lose pixels, so it might not
      be very useful, but it's there all the same.
      
      Next below that is the size of the Map.  If you add too many tile
      pieces, and the number is greater than 0x17d (hexadecimanl) the 
      display turns red.  If it's green it will probably work. Try it
      out in MAME or some other PacMan emulator to be sure, prior to 
      buring roms for your PacMan arcade machine.  If the map is too 
      small, you may have problems as well.
      
      If the map size is in red, the entire map will not be saved out to
      the rom images.  only the first 0x17d bytes of it will.  This will
      result in an unplayable map.  If your map shows a size in red, you
      need to reduce the size of the map, and you will be fine.  Read the
      5th paragraph in the "Some other things to note when editing a map"
      section below for more information on this.
      
      The 'P' key toggles a pellet underneath the cursor.  The pellets
      have a few restrictions on them as well.  Pellots cannot be in the 
      range above and below the ghosts' starting box, where the "Player 1"
      and "Ready!" text usually appears. There also must be 240 pellets 
      in the board.  This is shown in the next indicator down.  If there 
      are too few or too many pellets, the count indicator will be red 
      instead of green.
      
Some other things to note when editing a map:
      If you have a wall with pellots running through the wall, you will
      be able to go through the wall without problem, but if you die on the 
      level, and the level restarts, the wall will be restored where 
      the pellets used to be.  (try it out, and you'll see what i mean.)
      
      If you box in the ghosts, odd things can happen.  Ghosts will 
      go through walls, and will basically follow odd paths.
      
      Secret passages can be made by not having wall tiles on the left
      and right edges.  top-bottom passages don't seem to work very 
      well.  They work for piranha, although i'm not sure how they 
      do it.
      
      Map base tiles must be symmetrical, as only 1/2 of the map
      is actually stored in the rom.  Pellets can be non-symmetrical.
      Look at the Piranha map for an example.  
      
      You might want to use some of the "blank" characters in the set
      (characters 0xfc, 0xfd, 0xfe, and 0xff) to increase the size of 
      the map.  Change the bitmap image of these four characters to 
      be some unique graphic, like a "c","d","e", and "f". Then display
      the map from the romset "pacman"  to see how this is used.  Maps
      are Run-Length encoded vertically for spaces, so if you need to reduce 
      the size of the map, eliminate some vertical rows of 2 or more 
      characters, and replace them with spaces.  If you need to increase 
      the size of the map, replace some spaces with invisible characters 
      (like one of the last four listed above). Be aware that the only 
      place where the ghosts and PacMan can travel is an empty space (the 
      bottom piece in the tile palette.) 
      
Bugs:
      None.  ;)
      
Thanks:
      David_Caldwell@indigita.com, for the initial data about the maps.
      M.C.Silvius (msilvius@caiw.nl) for pacman name info & motivation. ;)
      Ivan Mackintosh, for starting AGE.
      Yuri Software for making HEdit32 (Hex editor for WinNT/Win95)
      Scott "Jerry" Lawrence, a swell guy who helped me a whole bunch
      
Adding a map driver:
    Okay, this might get confusing...  If you're reading this section, 
    I'm assuming that you have all of the necessary tools and knowledge
    to build, and edit the source code.  (you need DJGPP and Allegro.)
    For this example, Let's use the fictional game, Bunny Blaster. :)
    1) Add the file BUNNY.C in the maped directory. 
    2) In the makefle, add "maped\bunny.o" in the MAPED listing, in
       a similar fashion to that of the DRIVERS list.
    3) Add functions in BUNNY.C: (you can use any function name style
       you want, but for this example, I'm using the same filename 
       style as was used in the PacMan map driver.)
       
    void Maped_Decode_Bunny(void)
        The function that loads from the data roms, which are loaded
	into dataroms[], and store the decoded data into editbuf[] and
	overbuf[].  These structures are 2-dimensional arrays, stored as
	linear data.  ie, the information for the map element at (x,y) can
	be found at:   editbuf[x * (y*map_width)]
	The editbuf stores the index into the specified rom bank of 
	which character/sprite belongs at that location in the grid.
	The overlay (currently) is an array of bytes in which, for
	pacman as an example, if the byte is zero, there is no pellet.
	If the byte is non-zero (1) then there is a pellet.  Currently
	in maped, the 'p' key only toggles that one bit.  if you need 
	more resolution (more overlay characters) than that, you may need
	to hack the maped source a bit.
	
    void Maped_Encode_Bunny(void)
	Same as above, but it goes the other way.

    void Maped_Playfield_Base_Bunny(BITMAP * playfield)
    void Maped_Playfield_Over_Bunny(BITMAP * playfield)
	Converts the data loaded above into the bitmap "playfield".
	_Base_ does the base information (Map walls in PacMan)
	_Over_ does the overlay information (Pellets in PacMan)
	This function converts the editbuf into a displayable bitmap.
	Reference pacman's for more info.  Perhaps this should be 
	done internally... hmmm
	
    void Maped_Playfield_HC_Bunny(BITMAP * playfield)
	Draws any hardcoded information, not stored in the rom, or if
	any bits are in unknown locations in the rom and are un-editable.
	The Super-Power pellets in Pacman are this way. (The giraffe
	and leemurs in Bunny Blaster is stored in a hardcoded location 
	as well.)
	
    int Maped_Overlay_Pos_Valid_Bunny(int cxp, int cyp)
	returns 0 if (cxp, cyp) is an invalid position, otherwise, 
	returns 1. This is useful if the overlay data cannot be 
	stored in certain locations.  In PacMan, the locations 
	where "PLAYER 1" and "READY!" appear, power pellets cannot 
	be stored.
	
    void Maped_Info_Bunny(int mode)
	displays textual data out to the "screen" bitmap.  The "mode" 
	variable is either MODE_EDIT, or MODE_TILE.  This data is 
	useful if you want it displayed on the screen.
	
    4) Now that you have all those written create the MAPED_FUNCTIONS
       structure, and fill it with the appropriate function pointers.
	struct MAPED_FUNCTIONS Bunny_Functions =
	{
	    &Maped_Decode_Bunny,
	    &Maped_Encode_Bunny,
	    &Maped_Playfield_Base_Bunny,
	    &Maped_Playfield_Over_Bunny,
	    &Maped_Playfield_HC_Bunny,
	    &Maped_Overlay_Pos_Valid_Bunny,
	    &Maped_Info_Bunny,
	};
       And if you are not using one of these, you can replace it with
       a NULL.  The calling functions check for NULL function pointers
       before it calls the functions.
    
    5) And add the extern to that struct in the bottom of drivers.h
       extern struct MAPED_FUNCTIONS Bunny_Functions;
	
    6) Make sure that the MAPINFO structure is defined in drivers\bunny.c
       The data stored in that structure is available to both the internal
       functions and the functions you will add above.  The elements of
       this structure are especially useful if there is more than one map
       in a romset, especially if they are different sizes.  The MAPINFO
       structure stores map & overlay location, map width & height, bank
       number for which bank of graphics is associated with the map data,
       and the pointer to the function structure above.
       
	struct MAPINFO Bunny_MapInfo[] =
	{
	    { 0x3436, 0x35b5, 28, 32, 0, &Bunny_Functions },
	    // map is stored at 0x3436
	    // overlay is at 0x35b5
	    // map is (28x32), of characters from bank 0
	    // and it uses the functions defined in "Bunny_Functions"
	}
