======================================== Turaco CL 0.6 2003 March 30 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 Environment Variables 6.0 Command Line Options Appendices A.0 Creating a New Game Driver B.0 Building Turaco CL C.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. I 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. oops.) So, to counteract this, and to eliminate the dependancy on using a graphics editor that I have written, 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. We (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, Chris and Ivan have had no involvement on this version 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 us, and made us change it. Jerry then finally settled upon "TURACO", based on a very pretty bird in the Rochester, NY Zoo. Turaco CL is short for "Turaco Command Line", since this version is a non-graphical, command line version of the Turaco functionality. ---------------------------------------- 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. Tools will be provided later on to list out the supported romsets, but that functionality is not provided within Turaco CL itself. ---------------------------------------- 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 [6.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: bunnyb_bank1.pnm "bunnyb" bank number 1 as a PPM image. bunnyb_bank1_chk.pnm A "checkerboard" file. (explained below) bunnyb_pal1_key.pnm 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. 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 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. The checkerboard file is for reference only. I've found it useful to have this at 50% 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 PNM 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 [5.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. ---------------------------------------- Environment Variables [5.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 PNM Convert from PNM to ROM (Encode) -inf ROM Convert from ROM to PNM (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 PNM to ROM Options: (Encode) -rod Directory Select the absolute path to the output directory for the generated ROMs ROM to PNM Options: (Decode) -dbf BankImageFile.pnm Override the name for the generated file -chk CheckerboardFile.pnm Override the name for the checkerboard file -wid Number Select the number of sprites wide that generated images will contain ======================================== 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 ---------------------------------------- Copyright, Credit, License [C.0] Turaco CL is written by Scott "Jerry" Lawrence, and is based partially on Turaco v1.1.3, 1999-OCT-04: Turaco 1.1.3 was written by: Scott "Jerry" Lawrence turacoCL@umlautllama.com 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.15 2003/03/30 21:51:54 jerry Exp $