
                          Turaco - Arcade Games Editor  
                          ----------------------------

                                  Version 1.0
                                  9 Dec. 1998


Freeware by:
    Scott "Jerry" Lawrence   jerry@mail.csh.rit.edu
    Ivan Mackintosh          ivan@rcp.co.uk
    Chris "Zwaxy" Moore      chris.moore@writeme.com

World Wide Web homepage:
    http://www.csh.rit.edu/~jerry/turaco/

Related Pages:
    The Turaco Message Board     http://www.csh.rit.edu/~jerry/turaco/wwwboard/
    The AGE homepage             http://dales.rmplc.co.uk/ivan/age/

Copyright Message:
    This program and source code may be freely copied, and used in other 
    programs as long as proper credit is given for the writers (us) for the
    modules or code blocks that you use.  You may distribute TURACO only
    in either the source or executable distribution packages as received by 
    you (you) from the web address above (above).  If you want to include 
    this program on a cd-rom or other media to be sold, or given away for 
    free, you must contact us... We want copies of it to show our families
    and friends to brag about being published!  ;)



0.0 Table of Contents
---------------------

0.0 Table of Contents
1.0 Introduction
    1.1 History
    1.2 What's in a name?
2.0 System Requirements
3.0 Currently Supported Games
4.0 How to Use 
    4.1 Screen Layout
5.0 Command Line Options
6.0 Menu Options
7.0 Keyboard Summary
    7.1 General 
    7.2 Sprite Editor
8.0 How to Create a New Game Driver
9.0 How to Contribute Updates
A.0 Known Issues



1.0 Introduction
----------------
    TURACO allows the graphics inside the ROMs for certain arcade games to 
    be edited allowing you to modify or add completely new graphics to the 
    game.  There will be support for editing text strings, maps, and 
    attributes of some games in future versions.

1.1 History

    TURACO is the next generation of "AGE", the Arcade Games Editor.  AGE 
    has been under development since November of 1998.  It started as Ivan's 
    little baby, until it was added to by Jerry, and Chris.  Ivan created 
    the original structure, many drivers, and most of the origial 
    functionality.  Jerry then came by and added bitmap manipulations, 
    oodles more drivers, map editing, text editing, and miscellaneuous 
    functionalty.  Chris added the MAME loader, and eventually, the initial 
    version of the INI loaders, and hacked MAME to create the INI driver 
    files.

    But there was a problem.  Being that it was being added to, and added 
    to, and, well, added to, some problems were creeping up.  We were getting 
    random, but reproducable crashes, the user interface was never great, 
    and the user could not modify drivers themselves without recompiling the 
    program.  We (Ivan and Jerry) decided a re-write was in order.  The 
    re-write started about the same time as AGE 0.7 (the final AGE version) 
    was released.  Jerry decided to use ALLEGRO's GUI functions, and created 
    the necessary GUI objects (palette display, palette chooser, bitmap 
    editor, sprite palette.)

    Jerry did about half of TURACO, with Ivan adding in pretty much all 
    of the internal driver handling, palette internals, and patch internals, 
    borrowing code from AGE where applicable.  Chris has only had a ghostly 
    influence, in that it was his effort in the INI drivers for AGE that was 
    being re-used, along with the drivers created from his MAME hack.

1.2 What's in a name?

    This new version has also had a slight identity crisis in that we 
    weren't sure what to call it.  Jerry decided (as he was the one naming
    files, and writing the makefile) to call it "AGE 2", then "New Age" 
    (the source distribution is still named "NAGE_*" based on this name), 
    and then briefly changed to "Helen Shapiro".  Her lawyers contacted 
    us, and made us change it.  Jerry then finally settled upon "TURACO", 
    based on a very pretty bird in the Rochester Zoo. 


2.0 System Requirements 
-----------------------
    486 running MSDOS or Windows 95/98/NT
    A properly configured mouse
    ROMs for the game that you want to edit

    I've tried it on at least 3 systems with no problems:
	Gateway Handbook 486sx-33, 4mb and 20mb ram, MS-DOS 6.22
	Homebuilt 486dx4-100, 16mb ram, Windows 95
	Homebuilt P166, 64mb ram, Windows 95

    Some of the larger games, like Bubble Bobble, may require a few more
    megabytes of free memory over smaller games, like Pac-Man.


3.0 Currently supported games
-----------------------------
    TURACO currently supports many different games and their variants.
    Be sure to get the latest driver .zip file from the above distribution
    address.  For a full list of games supported including the subdirectory
    names for the ROMs and the ROM names themselves type:

	turaco -listroms

    from the command line. Note that this displays many screens of 
    information typing:

	turaco -listroms | more

    That allows you to view a single screen of information at a time.

    If you wish to just see which romsets are supported, without listing
    each individual rom file required, try:

	turaco -list

    If you want to see a list of all supported romsets and the name 
    of the set, try typing:

	turaco -listfull
     or 
	turaco -listfull | more

    Keep in mind that it is doing a fair share of work to display this 
    information; loading in each driver file (more than 200 of them),
    then searching in them for the information, sorting it, then
    displaying it.  This is why the file selector inside the program 
    needs a few seconds to display the list of supported games.


4.0 How to Use
--------------
    The easiest way to use TURACO is to just run TURACO from the directory
    in which you uncompressed it into.  Make sure that the path to 
    uncompressed roms is included in the turaco.ini.  Some example paths 
    are included in that file.  Generally, you can point it to the path
    of MAME's rom directory, and you should be fine, as long as your 
    roms are not compressed.

    If you don't have MAME then you can use the -listroms command line to 
    view what subdirectories you need to create and what files to copy there.

    If you have the correct game, but have merged roms, renamed roms, or 
    some other such nonsense, then if you are crafty enough, you can 
    change the driver files you need to reflect this.

    Run TURACO and you will be presented with the graphics editor screen.
    To load a game, Select "Change Game" from the file menu.  From here 
    you should see it scanning the drivers to get filenames and other 
    information.  It should take no longer than a few seconds.  You will 
    then be presented with a file selector from which you can choose the 
    game to load.  In the upper right, you will see the driver's filename, 
    and other miscellaneous information about the driver.  To select a 
    game, scroll through the (huge) list of games, and select the game 
    you'd like to load.  You can also press the first letter of the game 
    to skip to that group.  For example, if you press "p", it will scroll 
    to "Pac & Pal".  If you press it again, it will go to "Pac Man".  Try 
    it out... you'll get the idea.

    From there, select OK to load the game.

    If all was successful, you should now be presented with the first 
    graphics bank of that game.  Generally, the first bank includes the 
    alphabet, and numbers.  Pac-Man, for example, also includes the 
    graphics for the mazes.


4.1 Screen Layout

    The layout of this screen is as follows:

    At the top of the screen is the menu bar.

    Below that to the left is the sprite editor, and immediately to 
    it's upper right is the 1x zoom of the sprite being edited.

    To the right of the sprite editor is the color displayer, with the 
    current foreground color (left mouse button) in the center, and the 
    background color (right mouse button) surrrounding it.

    To the right of that is the color palette.  Click on this with the left
    button to select the new foreground color, and with the right button to 
    select the new background color.  

    To the right of that, you should see a listing of the current palette 
    number and the total palettes available.  as well as the buttons to 
    change the current palette.  ie 1/15 means that palette 2 is being 
    displayed, out of 15.  

    Just below that is the "BACK" button.  we'll get to that below...
    Below all of this is the name of the game loaded in, ie: "Mega Bunny 
    Blaster".

    To the right of that is the bank number display and selector.  If a 
    game has multiple graphics banks, you can use these gadgets to change 
    which bank you are looking at as with the palette above.

    Below that is the sprite palette.  By clicking on a sprite in this gadget,
    a menu is displayed showing: "Edit", "Cancel" and "Back". 
    "Edit" will copy the selected sprite to the sprite editor above.
    "Cancel" will do nothing"
    "Back" will take the sprite in the editor, and copy it into the position
    selected.  The "Back" button on the screen will copy the sprite being 
    edited back into the position it was taken from.

    When in the sprite editor, you can do some simple manipulations of the
    image using the arrow keys to move it around, and a few alt-keys to rotate
    and flip the image.  These are also available from the "Sprite" menu.

    Reference section 7.0 below to find out what keyboard shortcuts exist.



5.0 Command Line Options
------------------------

    Syntax:

    TURACO.EXE [short game name] [options ...]

    [short game name] 

	This option parameter allows you to specify the game you wish to 
	edit bypassing the need to use the game load selector. The short 
	game name is the up to 8 character directory where the roms for 
	the game are stored.  ie:  turaco pacman

    [options ... ]

    -help
	Display all supported command line options

    -list / -listroms / -listfull / -listhtml

	These options allow you to list the roms currently supported by 
	TURACO.  They are described in more detail in section 3.0 above.

    -v
	Display version and build information.  Useful when reporting a bug.



6.0 Menu Options
----------------

The menus are arranged by functional group.  We tried arranging them 
alphabetically, but it did not work out too well.  ;)

FILE               ALT + F     File Operations
----
  Change Game      C    Load in a new game.  This will destroy any
                        changes you have not saved.

  -----------

  Save Graphics    S    Save out any changes you have made.

  Revert           R    Forget about any changes you made in this session,
                        and re-load the graphics.  Modified palettes remain.

  -----------

  Generate Patch   G    Generates a copyright-free patch to be applied to the
                        romset.

  Apply Patch      A    Apply a previously-defined patch to the romset.


  -----------

  Exit             X    Exit from TURACO.


EDIT               ALT + E     Edit Operations
----
  Copy Sprite      C    Copy the current sprite into the clipboard

  Paste Sprite     P    Copy the clipboard into the current sprite
  
  -----------

  Add Palette      A    Create a new palette, after the previously last one,
                        with the same colors as the current palette.

  Edit Palette     E    Edit the current palette


MODE               ALT + M     Editing Mode
----
  Paint            p    Mouse will draw in the sprite editor when clicked.

  Flood Fill       f    Mouse will flood-fill the sprite when clicked.
  
  Eyedropper       e    Mouse will get the Foreground (left) or Background
                        (right) color when clicked.

SPRITE             ALT + S     Sprite Manipulations Tools
------
  Clear            k    Clears the sprite with the background color.

  -----------
  
  Flip Horiz       x    Flips the sprite on the horizontal axis.
  
  Flip Vert        y    Flips the sprite on the vertical axis.
  
  Rotate 90        z    Rotates the sprite 90 degrees clockwise.
  
  Rotate 45        w    Rotates the sprite 45 degrees clockwise.
  
  -----------
  
  Slide Left       h    Slides the sprite to the left by one pixel.
  
  Slide Down       j    Slides the sprite down by one pixel.
  
  Slide Up         k    Slides the sprite up by one pixel.
  
  Slide Right      l    Slides the sprite to the right by one pixel.
  
  -----------
  
  Wrap Left        u    Wrap-slides the sprite to the left by one pixel.
  
  Wrap Down        i    Wrap-slides the sprite down by one pixel.
  
  Wrap Up          o    Wrap-slides the sprite up by one pixel.
  
  Wrap Right       p    Wrap-slides the sprite to the right by one pixel.
  

HELP               ALT + H     Miscellaneous Help Option(s)
----  
  About...         a    Displays version information.



7.0 Key Summary
---------------

7.1 General 

    ALT + f      - File menu (see section 6.0 above)
    ALT + e      - Edit menu (see section 6.0 above)
    ALT + m      - Mode menu (see section 6.0 above)
    ALT + s      - Sprite menu (see section 6.0 above)
    ALT + h      - Help menu (see section 6.0 above)
    ALT + p      - Save a snapshot of the screen 
    [            - Previous graphics bank
    ]            - Next graphics bank
    <            - Previous palette
    >            - Next palette
    ,            - Eyedropper tool mode (Get fg/bg color)
    .            - Paint tool mode
    f            - Flood-fill tool mode

7.2 Sprite Editor

    Cursor Keys  - Slide the image around
    ALT + k      - Clear the image (with the background color)
    ALT + x      - Flip horizontal
    ALT + y      - Flip vertical
    ALT + z      - Rotate clockwise, 90 degrees
    ALT + w      - Rotate clockwise, 45 degrees
    ALT + g      - Toggle the gridlines



8.0 How to create a new driver
------------------------------

    The easiest way to create a new driver for TURACO is to copy an 
    existing driver from the "DRIVERS\" directory.

    The driver's name (ie: BUNNY.INI) will become the directory that 
    the roms are looked for in(*).  ie:  roms\bunny\

    The definitions of the structures as seen in the driver file can 
    be gleaned from the source to MAME.  

    If you change or create a driver, please send it to us!

    Perhaps this section will be improved later on...

         (*) A preposition is a bad word to end a sentence on(**).
        (**) This is also a sentence ending on a preposition(***).
       (***) Not this one(****).
      (****) Nor this one(*****).
     (*****) This is the last footnote.  I was thinking of adding as many
             footnotes as the cheat book for Infocom's "Hitchhiker's Guide
             to the Galaxy", but I decided against it(******).
    (******) Damn.



9.0 Updates
-----------

    Please send any modifications to functionality of this program or 
    addition graphics drivers to me so that they can be included in
    subsequent releases.

    All releases, along with experimental releases are available at:

	http://www.csh.rit.edu/~jerry/turaco/

    All comments, and problems should be addressed at the message board 
    which is often checked by Jerry & Ivan at:

	http://www.csh.rit.edu/~jerry/turaco/wwwboard/

    We can be contacted by email through the web addresses at the top 
    of this file.



A.0 Known Issues
----------------

    A.1 Single bitplane drivers do not work properly yet. 
	This will be fixed for the next version.

    A.2 There is no map or text editing support yet.  
	These will be in the next version.

    A.3 Not all drivers have been checked to be sure that they all work.
        The list of unchecked drivers is in the drivers directory in
        the fine "readme.txt".  If you have any problems with any specific
        drivers, bugfixes, or cool modifications or palettes for any 
        drivers, please let us know!

    A.4 After 254.86 hours of straight usage, the computer may emit a 
        strange green fog of pure methane.  Do not breathe this in.  Mix 
        it with your favorite carbonated beverage for a fun drink!
	This will NOT be fixed in the next version.  We need the eggs.

    A.5 The often silly nature of this file.
	This file was written at 3am.  I'm a little loopy now...
	(To keep the style proper, this file was proofread at 2am. :)

