Turaco CL 0.8

2003 May 30

                         Jerry Carpenter
                turacoCL@umlautllama.com

Table of Contents

Content: 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 5.0 TileMaps Explained 6.0 Environment Variables 7.0 Command Line Options

Appendices

A.0 Creating a New Game Driver
B.0 Building Turaco CL
C.0 Support
D.0 Copyright, Credit, License

========================================

Introduction [1.0]

TuracoCL allows the graphics stored in the ROMs for certain arcade games to be extracted, and rebuilt allowing you to modify or add completely new graphics to the game using external paint tools.

History [1.1]

Turaco CL is the latest incarnation of Turaco, which was an arcade graphics editor for MS-DOS. Jerry tried to port Turaco over to linux, and more modern operating systems, but was unable to due to bugs and oddnesses found in the code. (My bad. -J) So, to counteract this, and to eliminate the dependancy on using a graphics editor that Jerry wrote, Turaco CL imports and exports the graphics into common image file formats to be edited in your favorite paint program.

Turaco was the next generation of "AGE", the Arcade Games Editor. AGE was under development from November of 1998 until early 1999. It started out its life as a font editor that Ivan Mackintosh was working on. Then it was added to by Jerry, and Chris Moore. Ivan created the original structure, many drivers, and most of the origial functionality. Jerry, who had started to write a pacman editor, "Stylist", earlier that spring then came by and added bitmap manipulations, oodles more drivers, map editing, text editing, and miscellaneous 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. Ivan and Jerry decided a re-write was in order. The re-write started about a month prior to the release of the final version (v0.7) of AGE. 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, since upgraded by Ivan.

Turaco CL is a complete re-write, with a distinct lack of depencancy on any sort of graphics library, while still using the original INI driver files we had created for Turaco. This time, Jerry is the only developer. Chris and Ivan have had no involvement on this incarnation at all.

What's in a name? [1.2]

Turaco initially 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" and then briefly changed to "Helen Shapiro". Her lawyers contacted the development team, and made them change it. Jerry then finally settled upon "TURACO", based on a very pretty bird in the zoo in Rochester, NY.

Turaco CL is short for "Turaco Command Line", since this version is a non-graphical, command line version of the Turaco functionality. In order to increase the possibility of confusion, the older MS-DOS program, previously known as simply "Turaco" is now known as "Turaco Classic".

System Requirements [2.0]

Turaco CL requires any machine with a command line shell and a POSIX compatible layer. Most development work on Turaco CL has been done under OS X as well as Solaris with the occasional builds on Linux and MS-DOS.

Currently supported games [3.0]

Turaco CL currently supports 3036 games, whose drivers can be found in the drivers directory. Well, not really. The new drivers have been removed from the distribution channels due to the fact that they suck ass.

Tools will be provided later on to list out the supported romsets, but that functionality is not provided within Turaco CL itself.

Oh, not all 3036 of those work properly...

...but some of them do.

How to Use [4.0]

There are basically two different things that you can do with Turaco CL. You can encode ROMs with it, and you can decode ROMs with it.

The way that you specify this is with the "-inf" (INput File) parameter. The only other required command line option is either the -drv or the -ini option, which selects the name of the driver that we're using. This is explained in detail in section [7.0].

For example, here is a simple command line to extract the bank 1 graphics from Bunny Blaster:

turacocl -drv bunnyb -inf ROM

You can also specify an absolute path to the driver file like so: (this will prevent it from searching for the driver)

turacocl -ini drivers/bunny/bunnyb.ini -inf ROM

This should create three files:

bun_1.pcx "bunnyb" bank number 1 as a PCX image.

bun_1c.pcx A "checkerboard" file. (explained below)

bun_p1.pcx The palette key for palette 1.

These files will be created with similar filenames unless you have changed them with the -dbf, -chk and -key options.

The palette key image is only useful for 24 bit image file formats like PPM files. It is not generated, nor is it necessary for paletted image formats like PCX files. It doesn't matter if the palette key contains colors that are not really in the game or in the driver... as long as it is consistant with the bank image, it will work fine. This file is just so that Turaco CL knows how to re-encode this 24bit RGB image back into the paletted image for the ROM set. Any colors in your bank that do not EXACTLY MATCH a color in the palette key will be set to color 0.

When you edit the bank image file, you should also load in and save out the palette key file as well. This consistency is necessary for Turaco CL to encode the graphics properly back into a ROM. Turaco CL can support PPM, PNM and PBM files properly, so don't fret when Photo$hop saves it out with this new extension with a completely different file size. It's okay.

Again, if you're using a paletted image format like PCX files, just ignore all of this Palette Key image file stuff.

The checkerboard file is for reference only. I've found it useful to have this at 50% transparency over the bank image in Photo$hop so that I know where the sprite bounds are. Future versions of Turaco CL will have more information in this file as well so that you can make a font or sprite bank from scratch.

To take these image files and shove them back into a ROM, you can Turaco CL like this: (Assuming you haven't changed any of the filenames.)

turacocl -drv bunnyb -inf IMG

If you have changed the filenames, use the appropriate command line option to specify them properly.

Drivers will by default be searched for in the $(TDRIVERS) directory, which is explained in section [6.0].

ROMs will initially be searched for in the local directory, unless specified with the -rom option or the -trom option.

Output roms will be put in the current directory, unless you have changed this with the -rod option.

TileMaps Explained [5.0]

One common thing that many games do is to use multiple smaller sprites to draw a single larger image. For reference, this is done with the title scene and attract sequences for Ms. Pac-Man (Midway Logo), Pengo (mountain scene, Pengo logo), Dig-Dug (Dig Dug logo and graphics), and in Tapper (Budweiser/Root-Beer logo).

The problem is that these are not always arranged in an order such that they are easily editable via the default exported bank image file. The sprites might be out of order, repeated or just in an odd order in the graphics bank, making editing these images difficult.

The solution for this is the TileMaps. For this example, I will be referencing a jigsaw puzzle. If you have never heard of a jigsaw puzzle, go to your local toy store and buy one. ;) Arrange all of the pieces of the jigsaw puzzle right-side-up on the table in front of you, in a grid fashion. Now number these 0, 1, 2, and so on, starting from the upper leftmost one, across to the right, then the next row closest to you and so on.

It might look something like this:

        0       1       2       3
        4       5       6       7
        8

This is analogous to the bank file. You have a grid of startiing pieces/sprites arranged in a known order.

Now, complete the puzzle. The resulting puzzle will most likely not be in the same order. In fact, it might look something like so:

        3       8       4
        2       5       1
        0       9       6

This resulting arrangement is analogous to the data contained in the "Row"s of the TileMap. These Rows are stored in a known configuration in the driver, so that they can be broken out to the proper bank-ordering when importing and exporting.

In order to keep this working properly, I have devised a system where there are "Sets" of "Tilemaps". Each set has a name, and you specify it on the command line with the "-tms" command line option.

-tms setname

When extracting the graphics out, the bank image file will be produced (as above), as well as an image file for each exported bank in the set.

So, for example, if there were a set in the driver called "frogs", and it listed the tilemaps named "burrito" and "taco", then the following imaged files should be produced:

bun_1.pcx "bunnyb" bank number 1 as a PCX image.

bun_1c.pcx A "checkerboard" file. (explained below)

burrito.pcx The "burrito" tilemap.

taco.pcx The "taco" tilemap.

A couple of important things to note however:

        When encoding these images back into ROM files, if there
        are any instances where a sprite is used more than once,
        the bottom rightmost one will be stored back into the ROM.
        For example, if the tilemap looked like this:
                0       2       4
                1       4       3
                5       6       4

            and you have edited it such that the three instances
        of "4" are distinct from eachother, then only the bottom
        right "4" will actually be stored back into the ROM.  That
        sprite will be copied back over the other two "4"s

        Any sprite used in a tilemap will be 'grayed out' in the
        bank file.  Since it will be overwritten by the sprite in
        the tilemap image anyway, it is pointless to have it in
        there as well.

Okay, so you have a game that you want to figure out the tilemaps for, so that you can change the graphics in a game. There are a few problems facing you at this point, which I will try to explain.

What is necessary in the driver to implement a tilemap set for my game?

Check out the "inidriv.txt" file for an example.

            You need to have entries in the "Tilemap" section of
            the driver.  The "Tilemaps" item needs to contain the
            correct number of tilemaps in the driver.  The "Sets"
            item needs to contain the correct number of sets in
            the driver.  Also, for each set, you need a line that
            has the form:

                SetN= name X Y Z

            where "N" is the set number (1, 2, 3... ), "name" is
            the name of the set (used to select it on the command
            line) and "X", "Y", ... are used to define which tilemaps
            are contained in that set.

            For each Tilemap section, you need the "FName" (used
            for the filename for the files, the Bank number that
            the sprite is culled from, as well as the correct Width
            and Height.  (Height is the number of rows, Width is the
            number of elements on each row.)

            Then for each of the Rows, it simply is a list of which
            sprites get used in that position on the grid.  For
            the above example, the entry might look like this:

                [Tilemap1]
                    FName = sample
                     Name = The above sample in the document
                     Bank = 1
                    Width = 3
                   Height = 3
                     Row1 = 3 8 4
                     Row2 = 2 5 1
                     Row3 = 0 9 6

            The Name, Description and Credit are all optional.

        2) How can I figure out which sprites are which in the game?

            The easiest way to do this is to break out the checkerboard
            file.  Export the bank that is used out to image files.
            Now import the checkerboard file as the graphic file
            using the "-dbf" option.  Next, load up the graphics
            roms in your favorite emulator for the game (or burn
            graphics roms and drop them into real arcade hardware)
            and wait for the screen with the tilemap in it to come
            up.  Then just make a note of which sprite numbers are
            where, and put those values into the driver file.

            Be aware that each position in the checkerboard file
            is unique up until sprite number 2000.  After that,
            you're on your own. ;)

Environment Variables [6.0]

In order to use Turaco CL, you need to have two environment variables set. These determine where Turaco CL will look for the game driver files, as well as where the graphics roms.

These are the two environment variables that MUST be set:

        TDRIVERS        The path to the root of the ini drivers tree.
                        ie:  /var/share/turacoCL/drivers/

        TROMS           The path to the root of the rom tree.  
                        ie:  /usr/games/mame/roms/

You'd set them like so: (MS-DOS)

        SET TDRIVERS=C:\turacoCL\drivers
        SET TROMS=C:\games\mame\roms

Bourne Shell:

        TDRIVERS=${HOME}/turacoCL/ini/drivers
        export TDRIVERS
        TROMS=/usr/games/mame/roms
        export TROMS

C-Shell:

        setenv TDRIVERS ${HOME}/turacoCL/ini/drivers
        setenv TROMS    /usr/games/mame/roms

etc.

Command Line Options [6.0]

Syntax

turacocl [options ...]

Help Options:

        -h
            Display all supported command line options

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

Common Options: (Encode and Decode)

        -drv Drivername
                        Select the driver to be searched for.

        -ini Driver.ini
                        Select the absolute path to a driver to use.

            = one of the above two is REQUIRED =

        -inf IMG
                        Convert from Image to ROM (Encode)

        -inf ROM
                        Convert from ROM to Image (Decode / Extract / etc.)

            = one of the above two is REQUIRED =

        -bnk Number
                        Select the bank number to use

        -pal Number
                        Select the palette number to use

        -key KeyFile.pnm
                        Select a color key filename to use

        -rom Directory
                        Select the absolute path to the input directory
                        for the ROMs

        -ff PCX
                        Select paletted PCX image file format (default)
        -ff PNM
                        Select 24 bit PNM image file format
                (use only one of these two.)

        -dmp
                        Dump out the driver, as it was loaded in.

Image to ROM Options: (Encode)

        -rod Directory
                        Select the absolute path to the output directory
                        for the generated ROMs

ROM to Image Options: (Decode)

        -dbf BankImageFile.pcx
                        Override the name for the generated file

        -chk CheckerboardFile.pcx
                        Override the name for the checkerboard file

        -wid Number
                        Select the number of sprites wide that
                        generated images will contain

TileMap Options: (Encode/Decode)

        -tms SetName
                        Work with the selected tilemap set.  If it
                        was not found, a list of known tilemaps for 
                        this driver will be displayed.

Appendices

Creating a New Game Driver [A.0]

The easiest way to create a new driver for Turaco CL is to copy an existing driver from the $(DRIVERS) directory.

The driver's name (ie: "bunny.ini") will become the directory in which the roms are found. ie: $(DRIVERS)/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!

Read "inidriv.txt" for an explanation of each field in a driver file.

Building Turaco CL [B.0]

You should be able to build Turaco CL by simply running the gnu make program. On most systems, this is "gmake", but on OS X, it is "make". On OS X you need to have the Apple-provided developers tools installed in order to build Turaco CL.

No external libraries are needed other than the base install of whatever compilers are on your system.

Current platforms tested against:

        Sun Blade 1000 running SunOS 5.8
        Macintosh PowerBook G4 running Darwin 6.4  (OS X 10.2.4)
        x86 Intel Box running Linux 2.4.20
        x86 Intel Box running PC-DOS 7.0 (MS-DOS compatible)

The development environment bounces back and forth between the Blade and the G4 depending on the time of day. ;)

Building this under MS-DOS (or PC-DOS) requires that you have the DJGPP compiler installed. It might work well with other compilers, but they are untested. You will need the makefile/file tools to build it properly. There are also two slight modifications that need to be made to the Makefile. They are documented in the Makefile.

DJGPP can be acquired from http://www.delorie.com

Support [D.0]

The primary support line for Turaco is over at the Turaco Yahoo Group. Discussions about bugs, feature requests, romset hacks, driver development, all should take place at the group.

You can join (and please do!) from here:

http://groups.yahoo.com/group/Turaco

Turaco CL is written by Jerry Carpenter, and is based partially on Turaco v1.1.3, 1999-OCT-04:

Turaco 1.1.3 was written by:

        Scott "Jerry" Lawrence          jerry@csh.rit.edu
        Ivan Mackintosh                 ivan@absynth.com

With contributions by:

        Chris "Zwaxy" Moore             chris.moore@writeme.com
        Marcel "The Sil" Silvius

Legal Mumbo-Jumbo:

No warranty is neither expressed nor implied for any damages which may occur during the proper or improper use of this program and its associated files. Use it at your own risk!

We make no moral or legal statement about the use of un-licensed rom images which are not in your ownrship. In most cases, testing was performed with rom-images for games that we own. Many of the "supported" games have not been tested.

Product and game names are trademarks of their respective companies.

$Id: README.txt,v 1.23 2003/05/31 03:25:31 jerry Exp $