ScummVM Tools

WORK IN PROGRESS, HELP NEEDED

If you want to contribute, send us a sample of text you'd write for the new manual, and we will consider adding you an account. You can work on the manual in the Wiki, but if you prefer, supplying us with HTML or TeX sources is fine, too (we will then translate them for the Wiki). You can have a look at our TODO page for a list of tasks that need to be done.

TODO: describe each ScummVM command line tool in detail. Explain the allowed options, give typical usage examples and so on. Game pages might link to this.

This is a collection of various tools that may be useful to use in conjunction with ScummVM. Please note that although a tool may support a feature, certain ScummVM versions may not. ScummVM 0.6.x does not support FLAC audio, for example.

Using the GUI

The recommended way to use the tools are using the tool GUI, run the program tool program.

Most common usage is to compress files, to do that, simply click Next as compression is the default activity. If you are compressing Touche data files, you need to select advanced mode and then compress_touche, as the tools do not support selecting the touche directory automatically.

Next select the input file, depending on the tool you are using, this file to be selected differs greatly. You can look in the list below for the expected extension or filename, if you don't know it already. For some games this is obvious as there only is a single data file. For games that ship on multiple disks, select the first disk on this page, you will be asked for the second disk on the next page.

Sometime a tool is applied on a single file, but the game may contain many such file. By selecting Run on all files with the same extension you can automatically run the tool on all the files with the same extension and present in the same directory as the selected input file. For example you can run compress_scumm_san on all the SAN file of a game.

In most cases, the tool to be used will be automatically detected, if there are multiple options, you must manually select the correct tool to be used, this is usually obvious from the name of the tool, if you are unsure, check the list of tools below.

In this case, the correct tool (compress_queen) was automatically detected. Now select the output directory, note that the directory must exist. Extraction tools usually generate a large amount of output files, while compression tools generate a single archive. Since ScummVM usually expects a specific filename for compressed archives, you should not change the default after extraction completes.

Next, you will be asked for target platform. This is the platform that you are running ScummVM on, not the platform you are running the tools on. Note that this does not make the output files incompatible with other platforms. Instead it affects the default audio settings to be optimized for the platform selected, as support for some are very poor on certain platform (and will make ScummVM run very slow).

Next page asks audio for audio format to use, in most cases you can leave this at the default setting. If you want to configure bitrate and quality settings manually, check the advanced options checkbox, and you can change this at the next page.

After this, the tool will run. This can take a while and if all went well, you can continue on to the next page. If an error occured, you can go back to adjust settings. Take special care to note that some input files can cause the entire application to crash as many tools don't check too well for mal-formatted input files.

If all is well, advance to the next page to finish the guide! Enjoy your newly compressed/extracted data files!

Using the CLI

You can access all tools through the command line interface using the following syntax:

./scummvm-tools-cli [audio mode params] [params] [-o output] [extract|compress] <inputfile N ...>

Normally, all arguments except the input file(s) can be skipped. You can specify extract or compress before the filename to hint the tool what activity you want to perform. In many cases, the tools will output to the directory "out/" relative to the input file, if no directory is specified.

Some tools take additional parameters, use --help <tool name> to display extra arguments for that tool.

Use --list to display a list of all supported tools.

Use the -o or --output flag to specify the output file, if it's a directory, it's strongly recommended to append / to the filename for clarity. Normally the tools will output to the directory "out/" relative to the input file, if no directory is specified, some tools output to a file instead of a directory.

You can also specify the tool explicitly to ignore automatic detection:

./scummvm-tools-cli --tool <tool name> [audio mode params] [params] [-o output] <inputfile N ...>

Audio mode params

You can specify what compression method to use. Use --mp3, --flac or --vorbis first to select a special format, default is MP3.

MP3 mode params (version 1.1.1)

• -b rate — rate is the target bitrate(ABR)/minimal bitrate(VBR).
• -B rate — rate is the maximum ABR/VBR bitrate.
• --vbr — LAME Uses the VBR mode (default).
• --abr — LAME Uses the ABR mode.
• -V value — Specifies the value (0 - 9) of VBR quality (0 being the best quality).
• -q value — Specifies the MPEG algorithm quality (0 - 9) (0 being the best quality).
• --silent — The output of LAME is hidden.
• --lame-path — Specifies the path to lame (default: lame).

MP3 mode params (version 1.2.0svn)

• --vbr — LAME Uses the VBR mode (default).
• --abr rate — LAME Uses the ABR mode with the given target bit rate.
• --cbr rate — LAME Uses the CBR mode with the given bit rate.
• -b rate — rate is the minimum ABR/VBR bitrate (undefined by default).
• -B rate — rate is the maximum ABR/VBR bitrate (undefined by default).
• -V value — Specifies the value (0 - 9) of VBR quality (0 being the best quality).
• -q value — Specifies the MPEG algorithm quality (0 - 9) (0 being the best quality).
• --silent — The output of LAME is hidden.
• --lame-path — Specifies the path to lame (default: lame).

Vorbis mode params

• -b rate — rate is the nominal bitrate.
• -m rate — rate is the minimum bitrate.
• -M rate — rate is the maximum bitrate.
• -q value — Specifies the value (-1 - 10) of VBR quality 10 is best quality.
• --silent — The output of oggenc is hidden.

Flac mode params

• --fast — FLAC uses compression level 0.
• --best — FLAC uses compression level 8.
• -value — Specifies the value (0 - 8) of compression, with 8 being the best quality.
• -b value — Specifies a blocksize of value samples, must be a multiple of 8 between 8 and 160.
• --verify' — Files are encoded and then decoded to check accuracy.
• --silent — The output of FLAC is hidden.

Compression Tools

compress_agos

Used to compress the Feeble Files or Simon 1/2 voc/wav files to MP3, Vorbis or FLAC.

Example of usage:

 ./scummvm-tools-cli --tool compress_agos --vorbis -q 7 SIMON2.WAV

compress_gob

Compresses Gobliiins! data files.

compress_kyra

Used to compress The Legend of Kyrandia's speech files with MP3, Vorbis or FLAC.

Example of usage:

 ./scummvm-tools-cli --tool compress_kyra <flags here> input/GEMCUT.VRM output/GEMCUT.VRM

Note: You have to keep the VRM extension, else it will NOT work. Use it like shown above, copy all *.VRM files to a directory and let the tool put the output file in another directory.

compress_queen

Used to rebuild the datafile of Flight of the Amazon Queen, and allow optional MP3, Vorbis or FLAC compression.

Example of usage:

 ./scummvm-tools-cli --tool compress_queen <flags here> [-o outputfile] queen.1

The default output file is "queen.1c"

compress_saga

Used to compress SAGA engine digital sound files to MP3, Vorbis or FLAC.

Example of usage:

 ./scummvm-tools-cli --tool compress_saga <flags here> <file>

Where <file> is the sound file you with to compress, without the extension.

For Inherit the Earth, the digital music (music.rsc), speech (voices.rsc or "inherit the earth voices") and sound effects (sounds.rsc) files can be compressed. For I have no mouth, the speech (voices*.res) files can be compressed.

The compressed files have the ".cmp" extension. Once compressed, you only need the respective .cmp files.

There is no compression support yet for the following versions:

• The Mac CD Guild version of Inherit the Earth (uses MacBinary *.bin files)
• The unsupported early DOS demo of Inherit the Earth

compress_scumm_bun

Used to the compress '.bun' music/voice files with MP3, Vorbis or FLAC.

Example of usage:

 ./scummvm-tools-cli --tool compress_scumm_bun --flac digmusic.bun uncomp comp

Please note that FLAC compression will produce larger files than the original, for The Curse of Monkey Island!

compress_scumm_san

Compresses '.san' smush animation files. It uses lossless zlib for compressing FOBJ gfx chunks inside a san file. It also can create a separate Ogg file with the audio track.

Example of usage:

 ./scummvm-tools-cli --tool compress_scumm_san opening.san uncomp/ comp/

In order to use such compressed files, your ScummVM binary must have been built with zlib support enabled (you can find out whether that's the case by looking at the About dialog). For the Ogg or MP3 compression feature, your ScummVM binary naturally must have been built with Ogg or MP3 support enabled.

NOTE: For some '.san' files there is a corresponding '.flu' file, which contains offsets into the '.san' file. Hence, the compress_scumm_san has to modify the '.flu' file. This happens automatically, if the '.san' and '.flu' files are in the same directory (which is normally the case). If you want to move the '.san' files before compressing them, make sure to move the '.flu' files, too!

compress_scumm_sou

Used to compress .sou files to .so3 (MP3), .sog (Vorbis), or .sof (FLAC).

Example of usage:

 ./scummvm-tools-cli --tool compress_scumm_sou --mp3 MONSTER.SOU

or simply:

 ./scummvm-tools-cli --mp3 MONSTER.SOU

compress_sword1

Used to compress Broken Sword 1's music and speech files to MP3 or Vorbis or FLAC. Only the PC and the Mac version are currently supported. The PSX version is not supported by this tool.

Example of usage:

./scummvm-tools-cli --tool compress_sword1 --vorbis -q 7 BS1/swordres.rif

The input file (in that case BS1/swordres.rif) can be any file at the root of the directory that contains the Broken Sword data files. When the tool is auto-detected (i.e. when not using the --tool flag), the input file should be either the swordres.rif file or one of the cluster file (*.clu for the PC version or *.clm for the mac version).

The tool will look for the speech and the music files in the SPEECH/ and MUSIC/ sub-directories respectively (e.g. BS1/SPEECH/speech1.clu). If they are not found there, it then looks for them directly at the root of the input directory (e.g. BS1/speech1.clu). The compressed files will also be created in the MUSIC/ and SPEECH/ sub-directories of the output directory if these sub-directories exist. Otherwise the compressed files will be created at the root of the output directory.

It is possible to compress only the speech files or the music files using the --speech-only or --music-only flags:

 ./scummvm-tools-cli --tool compress_sword1 --vorbis --speech-only BS1/swordres.rif

compress_sword2

Used to compress Broken Sword 2's music and speech .clu files to .cl3 (MP3), .clg (Vorbis) or .clf (FLAC).

Please note that FLAC compression will produce a larger file than the original! This is because the original files already use lossy compression.

compress_tinsel

Used to compress tinsel .smp files.

compress_touche

Used to compress and pack Touche speech files ('Vxxx' and 'OBJ') to MP3, Vorbis or FLAC to a single file named TOUCHE.SO3/.SOG/.SOF depending on the sound compression. Once compressed, only TOUCHE.DAT and TOUCHE.SOx files are required to play the game under ScummVM.

Example of usage:

 ./scummvm-tools-cli --tool compress_touche <flags here> [-o outputfile] <inputdir>

If no outputfile is provided, or if it is a directory, the file will be named TOUCHE.XXX, where XXX depends on the compression method, and will be created in the output directory if one is given, or the current directory otherwise.

The inputdir should be the directory that contains all the touche data files (TOUCHE.DAT, OBJ and the Vxxx files).

compress_tucker

Used to compress .wav files from FX/MUSIC/SPEECH directories to a single file named TUCKER.SOx Once compressed, the 3 directories aren't required to play the game under ScummVM.

Encoder Tools

encode_dxa <filename>

Creates DXA file out of extracted Smacker video.

To extract a video use RAD Game Tools and perform 2 passes on it. For example, if your video is called 'intro.smk'.

1. Extract the video to PNG, 256 colors (choose PNG format and tick the checkbox). It will create bunch of files named 'introXXX.png', where XXX is frame number. Make sure you have extracted 256 colors PNGs, otherwise encode_dxa will complain.

2. Extract the audio to WAV format, you will get an 'intro.wav' file.

3. Put files 'intro.smk', 'intro.wav' and 'intro*.png' into a single directory.

4. Run `encode_dxa intro.smk` in that directory

5. You will get an intro.dxa file and intro.flac/mp3/ogg file in result.

Additionally you may use batch processing mode of SMK files in RAD Game Tools. Just select more than one file and push the 'Convert' button. It will ask you either you want them processed in batch mode and will do this for you. All buttons and conversion options work the same.

convert_dxa.bat, convert_dxa_one.bat

To ease your life we also provide batch files to autoconvert all files. It should work with any game version.

1. Copy *.smk files from all CDs to some directory

2. Edit paths in convert_dxa.bat file.

3. Run the batch. If you set everything correct, it will be almost unattended conversion, just for several files there are no audio, and RAD Game Tools converter will ask you to press OK

convert_dxa.sh

Same as above convert_dxa.bat, just for *nix-based systems. It uses Wine to run RAD Game Tools.

Extraction Tools

Many games package together all their game data in a few big archive files. The following tools can be used to extract these archives, and in some cases are needed to make certain game versions usable with ScummVM. In general, though, they are mostly intended for ScummVM developers and not useful to end users.

extract_agos

Extracts the packed files used in the Amiga and AtariST versions of Elvira 1/2, Waxworks and Simon the Sorcerer 1.

Example of usage:

./scummvm-tools-cli --tool extract_agos <infile 1> ... <infile n>

extract_cge

Unpack Soltys and Sfinx game data files.

Example of usage:

./scummvm-tools-cli --tool extract_cge [-o outputdir] <inputfile>

The <inputfile> has to be either the vol.cat or the vol.dat file. See also the re-packaging tool for the Soltys game files.

extract_cine

Unpacks Delphine's Cinematique engine's archive files. Should work at least with Future Wars and Operation Stealth. It seems to also work with Cruise for a Corpse. It accepts only one input file. This may be either one of the archive file, in which case only this file is unpacked, or the 'vol.cnf' file, in which case all archive files listed in the 'vol.cnf' file are unpacked.

Example of usage:

./scummvm-tools-cli --tool extract_cine [-o outputdir] <infile>

extract_cruise_pc

Unpack the E1, E4 and E5 files found in some versions of Cruise for a Corpse. To extract the D1 to D5 files, use the extract_cine tool instead.

Example of usage:

./scummvm-tools-cli --tool extract_cruise_pc [-o outputdir] <infile>

extract_fascination_cd

Extract the hidden STK from Fascination CD. It's designed to work on ISO files of the first data track only i.e. ~11M, not 652M. If your CD reading tool does not support single track ISO creation, this can be created using a tool such as "dd" to truncate the ISO dump.

extract_gob_stk

Extract the files from a Stick file used by 'gob' engine (.STK/.ITK/.LTK).

extract_kyra

Unpacks .PAK files from Kyrandia games.

It is also able to extract the installer package files from Hand of Fate DOS floppy version. You should be sure you got all WESTWOOD.### files for that, since they are one big package file splitted into several, so with -x you will extract *all* files from the installer files.

This tool takes some additional arguments, run ./scummvm-tools-cli --help extract_kyra for details.

Example of usage:

./scummvm-tools-cli --tool extract_kyra -x [-o outputdir] <infile>

extract_loom_tg16

Extracts data files from the PC-Engine version of Loom.

You will need to extract the code track from the CD with one of the following utilities

Windows

Use dumpcd [dumpcd Link]/[Alternative Link]

There is also a version with a GUI available [here.]

Alternatively use TurboRip from [here].

Another alternative is to use the PC-Engine emulator Ootake (You will need to own an original console because Ootake requires that you dump the system card)

Linux

You may compile dumpcd using the source code available [here].

extract_mm_apple

Extracts data files from the Apple II version of Maniac Mansion.

extract_mm_c64

Extracts data files from the Commodore 64 version of Maniac Mansion.

extract_mm_nes

Extracts data files from the NES version of Maniac Mansion.

extract_parallaction

Extracts the contents of archives used by Nippon Safes

extract_scumm_mac

Extracts Macintosh "single file" SCUMM games into their component parts, for use with ScummVM. This is required for ScummVM up to version 0.6.x; all later versions directly support reading this file format.

extract_t7g_mac

Extract data files from the The 7th Guest Macintosh data file.

extract_zak_c64

Extracts data files from the Commodore 64 version of Zak McKracken.

pack_cge

Pack Soltys and Sfinx game data files (as such this is not really an extraction tool, see extract_cge for the extraction tool).

Example of usage:

./scummvm-tools-cli --tool pack_cge [-o outputdir] <inputdir>

Script Tools

The following tools can be used to analyze the game scripts (controlling the behavior of certain scenes and actors in a game). They are intended for use by developers, and as such in general not helpful to normal users.

decine

Decompiles Delphine's Cinematique engine's scripts. Should work at least with Future Wars and Operation Stealth.

Example of usage:

decine [type] [version] [filename]

type: -prc or -rel (Use -prc for *.prc-files, -rel for *.rel-files)
version: -v1 or -v2 (Use -v1 for Future Wars, -v2 for Operation Stealth)
filename: The name of the script file to decode

degob

Decompiles TOT scripts used in Coktel Vision games

Example of usage:

 degob <version> <file.tot> [<file.ext>] [<commun.ext>]

<version> describes from which game the script file was taken and is one of "Gob1", "Gob2", "Gob3", "Ween", "Bargon", "Fascination, "Lost", "Woodruff", "Dynasty" and "Urban".

If the script file calls loadMult(), the script file's EXT file must be supplied on the command line as well; some script files also require a commun.ext. degob throws an error to let you know if any of the two should be the case.

dekyra

Basic script disassembler for Legend of Kyrandia games

descumm

Decompiles SCUMM scripts.

Syntax:
 descumm [-o] filename
Flags:
 -0	Input Script is C64
 -1	Input Script is v1
 -2	Input Script is v2
 -3	Input Script is v3
 -4	Input Script is v4
 -5	Input Script is v5
 -6	Input Script is v6
 -7	Input Script is v7
 -8	Input Script is v8
 -p	Input Script is from Humongous Entertainment game
 -n	Use Indy3-256 specific hacks
 -z	Use Zak256 specific hacks
 -u	Script is Unblocked/has no header
 -o	Always Show offsets
 -i	Don't output ifs
 -e	Don't output else
 -f	Don't output else-if
 -w	Don't output while
 -b	Don't output breaks
 -c	Don't show opcode
 -x	Don't show offsets
 -h	Halt on error

descumm sends the results to standard output, so you should redirect the output using the ">" character, like so:

descumm -5 inscript.tmp > outscript.txt

Each version of the SCUMM engine has a different instruction set, so you must specify which set to use when interpreting the input. If you're not sure which version number to use, consult the table at SCUMM/Versions. Note that Indy3-256 and Zak256 have a few instructions that differ from the standard SCUMM V3 instruction set, so you should also specify the "-n" or "-z" option.

By default, descumm attempts to interpret most instructions that jump to another address as "if/else" or "while" blocks. If you like, you can retain just the basic instruction, which will appear in the form of:

unless ([boolean-expression]) goto [address];

You can also disable outputting the opcode hex values and address offsets, although you may have trouble understanding where jumps go to.

If the script has been "unblocked", it is missing the header information as described in SCUMM/Technical_Reference/Script_resources. This information is not necessary to interperet the code, but you must tell descumm if is not present via the "-u" option.

desword2

Disassembles Broken Sword II scripts

Other Tools

create_sjisfnt

Allows the creation of a Shift JIS Japanese font from a compatible truetype font (sazanami-mincho.ttf / kochi-mincho.ttf)

Syntax:
 create_sjisfnt [compatible font] SJIS.FNT

Can be used for all FM-Towns/PC-98/PC-Engine games which require the original font ROMs.

---

Prev: Appendix: Config file description

Back to Table of Contents

Next: