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.

Compression Tools

compress_scumm_sou

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

compress_agos

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

compress_queen

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

compress_saga

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

Example of usage:

 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_sword1

Used to compress Broken Sword 1's music and speech files to MP3 or Vorbis or FLAC.

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_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.

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:

 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_bun

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

Example of usage:

 compress_scumm.bun digmusic.bun uncomp comp --flac

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

compress_kyra

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

Example of usage:

 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.

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.

extract_kyra

Unpacks .PAK files from Kyrandia games.

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_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]/[GUI]

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

Use dumpcd [dumpcd]

Alternatively 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_zak_c64

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

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.

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

dekyra

Basic script disassembler for Legend of Kyrandia games

---

Prev: Appendix: Config file description

Back to Table of Contents

Next: