INSTRUCTIONS
Introduction
The Z64 Resource Extractor is a small utility
capable of scanning a ROM for levels, objects, audio, and data, and
save them into individual files. If you use a debugging ROM, then
it can also extract suitable filenames to use. These files can
then be analyzed with any compatible utility you desire. The
program is capable of extracting files from commercial ROMs (that use
pointer tables) and decompressing files that use the YAZ0 algorithm,
and will also generate a files database in a separate file that will be
used in future projects.
Note: These instructions are for version 1.1 of the Resource Extractor. Previous versions may lack features or capabilities described in this document.
Note: These instructions are for version 1.1 of the Resource Extractor. Previous versions may lack features or capabilities described in this document.
Working at the Command Line
The "command line" is a program that harkens back
to the days when computers were just becoming affordable to the average
person and featured 100KB of RAM with a compact 5¼" disk drive and no
hard drive. Apple's ][ series featured a hidden command line that
was technically a variant of the BASIC programming language.
Later on, Microsoft created/bought out DOS (formerly CP/M) and released
it for IBM-compatible computers. DOS had no graphical interface,
no mouse support, no voice control, nothing except for a little prompt
where you typed in commands that told the computer what to do.
DOS was used until Microsoft switched over to 32-bit processor technology. Once Windows NT 3.51 was released, MS-DOS was no longer the primary means for users to interface with their computers. People could start up their computers and start working with a graphical interface right away. By the time Windows 2000 and Windows Me were released, users could no longer boot their computers into a pure command-line environment. But the command line has advantages when it comes to scripting (although GUIs are starting to work around these limitations) and automation, so Microsoft has made sure that every version of Windows includes a command line interface.
Fortunately, it is very, very easy to access the command-line interface:
Once open, you should see something along the lines of path> with a blinking cursor next to it (i.e., C:\Documents and Settings\username>).
The first important step is to navigate to the folder that contains Z64
Resource Extractor. There is a fairly easy way to do this.
First, make sure your command line is inside a window and not set to
fullscreen (hit Alt+Enter if it's in fullscreen to switch to windowed
mode). Then use Windows Explorer and browse to the folder with
Z64 Resource Extractor in it. Set the address box to visible (use
the View menu) and copy the path into the clipboard. Switch back
to the command line and type in "cd " (note the space), then
right-click on the title bar, go to the Edit submenu, and click on
Paste. Hit Enter and it'll go to the proper folder.
Note: The DOS-based OSes may require you to put quotation marks around the path for it to work properly. NT-based OSes shouldn't have this issue, but will work if you use quotes.
Now copy or move the ROM image (with Windows Explorer, preferably) you want to extract from to the folder containing Z64 Resource Extractor. Rename it so that there are no spaces in the filename (or enter in its 8.3 name if you know it). For the final step, type in ResourceExtractor romname.rom in the command-line and hit Enter.
DOS was used until Microsoft switched over to 32-bit processor technology. Once Windows NT 3.51 was released, MS-DOS was no longer the primary means for users to interface with their computers. People could start up their computers and start working with a graphical interface right away. By the time Windows 2000 and Windows Me were released, users could no longer boot their computers into a pure command-line environment. But the command line has advantages when it comes to scripting (although GUIs are starting to work around these limitations) and automation, so Microsoft has made sure that every version of Windows includes a command line interface.
Fortunately, it is very, very easy to access the command-line interface:
DOS-Based OS's (Windows 95/95a/98/98SE/Me)
|
NT-Based OS's (Windows NT/2000/XP/2003)
|
Note: The DOS-based OSes may require you to put quotation marks around the path for it to work properly. NT-based OSes shouldn't have this issue, but will work if you use quotes.
Now copy or move the ROM image (with Windows Explorer, preferably) you want to extract from to the folder containing Z64 Resource Extractor. Rename it so that there are no spaces in the filename (or enter in its 8.3 name if you know it). For the final step, type in ResourceExtractor romname.rom in the command-line and hit Enter.
Watching It Work
Once you start up the program, it will display
first a brief message with some legal jargon. Press any key
(except for Alt, Shift, Ctrl, Caps Lock, Num Lock, Scroll Lock,
PrtScrn, or Pause) to continue.
Z64 Resource Extractor 1.1
WARNING: This program may violate copyright laws when applied to certain
commercial ROMs. Use at your own risk.
WARNING: This program supports uncompressed ROMs and ROMs utilizing the
YAZ0 algorithm. ZLIB and other compression algorithms are not supported.
Press any key to continue . . .
Next it will check to see if a filename was given. If no filename was entered in, it will ask for a filename. Note that spaces in filenames will work when entered in this manner.
Please enter in ROM filename to extract data from:
romfile.rom
Once it has a filename, it will open it and check to see if it's a byteswapped ROM, typical ROM, or not a ROM at all.
If it cannot detect the bit encoding, it will ask you to provide the
endian mode. If you don't know the mode, it is best to quit at
this point and check to see if you're using the right file.
At this point it will begin to scan the ROM for the name and address databases typically included in debugging ROMs (in regards to the name database, it looks for the phrase "makerom", a generic term for the program itself). If detected, it will store the data in RAM and report to you how many entries were found for both. Because ROMs tend to be very large, the scanner will only check the first 900KB (approx.) and stop if it doesn't find anything. It will ask if you wish to continue the scan, but be warned that this can take a long time (it will show a progress meter to help you keep track of where it's at).
Object name database located in ROM image. Scanning...
Scan complete. Resulting size of database: 1531
Address database located in ROM image. Scanning....
Scan complete. Resulting size of database: 1531
At this point, it will compare the database sizes and make sure they match up. If they do, then all is well. If the sizes don't match, it will ask you if you want to continue using the databases. In this situation, files in the address database that don't match in the name database will receive generic filenames and no extension. Files in the name database but not in the address database are discarded. The program will list all orphaned names and addresses if this does occur for your reference.
Currently, the program will close if the databases are not used. This will be changed in the future.
The program now will begin the smart scan process, which uses the databases to find files, extract them, and give them a name based on how the resources were named in the database. While extracting a file, the program will display a progress bar since many files take awhile to extract (and it may appear to the user that the program was hanging if the progress bar wasn't there). It will then report if the file was successfully extracted. If it doesn't have any idea what the file was originally named, it will use the offset it found the file at in the ROM. If it has no idea what kind of file it is, it will give it a generic ".ZDATA" extension.
Files that already exist and have the proper size will be skipped. Files that already exist but do not have the right size will be overwritten.
Initiating smart scan...
Phase 1: Extracting data identified in database.
File dmadata.zdata already exists and has matching filesize. File skipped.
File Audiobank.zdata already exists but has different filesize. Old version will be deleted.
File successfully exported: Audiobank.zdata (179648 bytes)
██████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
Once all files are extracted, the program will save the databases to a file (romfile.db) and then close. In future versions, the program will scan regions not defined in the database for data that may be undefined but used.
Phase 1 complete.
Phase 3: Exporting file tables for reference purposes.
Phase 3 complete.
Smart extraction complete.
Extraction process complete.
Z64 Resource Extractor 1.1
WARNING: This program may violate copyright laws when applied to certain
commercial ROMs. Use at your own risk.
WARNING: This program supports uncompressed ROMs and ROMs utilizing the
YAZ0 algorithm. ZLIB and other compression algorithms are not supported.
Press any key to continue . . .
Next it will check to see if a filename was given. If no filename was entered in, it will ask for a filename. Note that spaces in filenames will work when entered in this manner.
Please enter in ROM filename to extract data from:
romfile.rom
Once it has a filename, it will open it and check to see if it's a byteswapped ROM, typical ROM, or not a ROM at all.
| Byteswapped (PC-friendly) Byte order is little endian.
|
Typical (Not PC-friendly) Byte order is big endian. Byteswapping enabled.
|
Not a ROM Bit encoding not detected. ROM image may be invalid.
|
At this point it will begin to scan the ROM for the name and address databases typically included in debugging ROMs (in regards to the name database, it looks for the phrase "makerom", a generic term for the program itself). If detected, it will store the data in RAM and report to you how many entries were found for both. Because ROMs tend to be very large, the scanner will only check the first 900KB (approx.) and stop if it doesn't find anything. It will ask if you wish to continue the scan, but be warned that this can take a long time (it will show a progress meter to help you keep track of where it's at).
Object name database located in ROM image. Scanning...
Scan complete. Resulting size of database: 1531
Address database located in ROM image. Scanning....
Scan complete. Resulting size of database: 1531
At this point, it will compare the database sizes and make sure they match up. If they do, then all is well. If the sizes don't match, it will ask you if you want to continue using the databases. In this situation, files in the address database that don't match in the name database will receive generic filenames and no extension. Files in the name database but not in the address database are discarded. The program will list all orphaned names and addresses if this does occur for your reference.
| Sizes Match Database sizes match! All resources named in the database will be saved with the internal filename.
|
Sizes Don't Match WARNING: Database sizes do not
match. They may not correlate to each other, which may result in
misleading filenames for extracted resources.
|
The program now will begin the smart scan process, which uses the databases to find files, extract them, and give them a name based on how the resources were named in the database. While extracting a file, the program will display a progress bar since many files take awhile to extract (and it may appear to the user that the program was hanging if the progress bar wasn't there). It will then report if the file was successfully extracted. If it doesn't have any idea what the file was originally named, it will use the offset it found the file at in the ROM. If it has no idea what kind of file it is, it will give it a generic ".ZDATA" extension.
Files that already exist and have the proper size will be skipped. Files that already exist but do not have the right size will be overwritten.
Initiating smart scan...
Phase 1: Extracting data identified in database.
File dmadata.zdata already exists and has matching filesize. File skipped.
File Audiobank.zdata already exists but has different filesize. Old version will be deleted.
File successfully exported: Audiobank.zdata (179648 bytes)
██████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
Once all files are extracted, the program will save the databases to a file (romfile.db) and then close. In future versions, the program will scan regions not defined in the database for data that may be undefined but used.
Phase 1 complete.
Phase 3: Exporting file tables for reference purposes.
Phase 3 complete.
Smart extraction complete.
Extraction process complete.
Resource Filetypes
There are five different filetypes used by the Z64 Resource Extractor, each storing different kinds of data.
.ZACTOR - Object data. Content is uncertain, but might be a compiled scripting language.
.ZOBJ - Object data. Contains meshes, textures, and animation sequencing.
.ZSCENE - Scene data. Contains collision mesh, textures, lighting definitions, camera instructions, and references to map data.
.ZMAP - Map data. Contains mesh, textures, texture definitions, coloring, and object definitions.
.ZDATA - Generic data. May contain textures, scripts, text, audio, resource descriptors, or executable code.
If no extension is given, then the Resource Extractor had no name entry on it within the database. Eventually it will automatically assign extensions to these files.
Some ROMs may use a different naming scheme, preventing the Resource Extractor from working properly. In the future, the Resource Extractor will contextually identify all data files, which will bypass this issue.
.ZACTOR - Object data. Content is uncertain, but might be a compiled scripting language.
.ZOBJ - Object data. Contains meshes, textures, and animation sequencing.
.ZSCENE - Scene data. Contains collision mesh, textures, lighting definitions, camera instructions, and references to map data.
.ZMAP - Map data. Contains mesh, textures, texture definitions, coloring, and object definitions.
.ZDATA - Generic data. May contain textures, scripts, text, audio, resource descriptors, or executable code.
If no extension is given, then the Resource Extractor had no name entry on it within the database. Eventually it will automatically assign extensions to these files.
Some ROMs may use a different naming scheme, preventing the Resource Extractor from working properly. In the future, the Resource Extractor will contextually identify all data files, which will bypass this issue.
Warning!
The Z64 Resource Extractor is designed to avoid most circumstances that generate crashes. It is not designed, however, to use the CPU judiciously. While this program is extracting data, it will very likely bring CPU usage to 100%. While this means you probably shouldn't run an intense game while this program is at work, it will not cause your machine to hang as it does not attempt to use Windows. If you are using Windows 2000/XP/2003/Vista, then you can use the Task Manager's Processes tab to change the priority of the Resource Extractor to "Below Normal". This will give other programs preference to CPU usage and prevent you from experiencing any system lagging.
Windows 95/98/Me users can download freeware that alters the priority of applications, but the kernel for these operating systems is not as powerful as the one in NT-based systems and thus may still experience system lag. FreeDOS and DOS 7.0 users won't have any problems, as they can only use one program at a time anyway (not counting DOS Shell or other utilities that enable multi-tasking in DOS environments).
The Z64 Resource Extractor is designed to avoid most circumstances that generate crashes. It is not designed, however, to use the CPU judiciously. While this program is extracting data, it will very likely bring CPU usage to 100%. While this means you probably shouldn't run an intense game while this program is at work, it will not cause your machine to hang as it does not attempt to use Windows. If you are using Windows 2000/XP/2003/Vista, then you can use the Task Manager's Processes tab to change the priority of the Resource Extractor to "Below Normal". This will give other programs preference to CPU usage and prevent you from experiencing any system lagging.
Windows 95/98/Me users can download freeware that alters the priority of applications, but the kernel for these operating systems is not as powerful as the one in NT-based systems and thus may still experience system lag. FreeDOS and DOS 7.0 users won't have any problems, as they can only use one program at a time anyway (not counting DOS Shell or other utilities that enable multi-tasking in DOS environments).