@@ Line 6: / Line 6: @@
 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.
+[[Image:Toolguide1.png]]
+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 [[User_Manual/Appendix:_Tools#compress_scumm_san|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.
+[[Image:Toolguide2.png]]
+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.
+[[Image:Toolguide3.png]]
+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).
+[[Image:Toolguide4.png]]
+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.
+[[Image:Toolguide5.png]]
+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.
+[[Image:Toolguide6.png]]
+If all is well, advance to the next page to finish the guide! Enjoy your newly compressed/extracted data files!
+[[Image:Toolguide7.png]]
+== 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''''' &mdash; ''rate'' is the target bitrate(ABR)/minimal bitrate(VBR).
+*'''-B ''rate''''' &mdash; ''rate'' is the maximum ABR/VBR bitrate.
+*'''--vbr''' &mdash; LAME Uses the VBR mode (default).
+*'''--abr''' &mdash; LAME Uses the ABR mode.
+*'''-V ''value''''' &mdash; Specifies the value (0 - 9) of VBR quality (0 being the best quality).
+*'''-q ''value''''' &mdash; Specifies the MPEG algorithm quality (0 - 9) (0 being the best quality).
+*'''--silent''' &mdash; The output of LAME is hidden.
+*'''--lame-path''' &mdash; Specifies the path to lame (default: lame).
+==== MP3 mode params (version 1.2.0svn) ====
+*'''--vbr''' &mdash; LAME Uses the VBR mode (default).
+*'''--abr ''rate''''' &mdash; LAME Uses the ABR mode with the given target bit rate.
+*'''--cbr ''rate''''' &mdash; LAME Uses the CBR mode with the given bit rate.
+*'''-b ''rate''''' &mdash; ''rate'' is the minimum ABR/VBR bitrate (undefined by default).
+*'''-B ''rate''''' &mdash; ''rate'' is the maximum ABR/VBR bitrate (undefined by default).
+*'''-V ''value''''' &mdash; Specifies the value (0 - 9) of VBR quality (0 being the best quality).
+*'''-q ''value''''' &mdash; Specifies the MPEG algorithm quality (0 - 9) (0 being the best quality).
+*'''--silent''' &mdash; The output of LAME is hidden.
+*'''--lame-path''' &mdash; Specifies the path to lame (default: lame).
+==== Vorbis mode params ====
+*'''-b ''rate''''' &mdash; ''rate'' is the nominal bitrate.
+*'''-m ''rate''''' &mdash; ''rate'' is the minimum bitrate.
+*'''-M ''rate''''' &mdash; ''rate'' is the maximum bitrate.
+*'''-q ''value''''' &mdash; Specifies the value (-1 - 10) of VBR quality 10 is best quality.
+*'''--silent''' &mdash; The output of oggenc is hidden.
+==== Flac mode params ====
+*'''--fast''' &mdash; FLAC uses compression level 0.
+*'''--best''' &mdash; FLAC uses compression level 8.
+*'''-''value''''' &mdash; Specifies the ''value'' (0 - 8) of compression, with 8 being the best quality.
+*'''-b ''value''''' &mdash; Specifies a blocksize of ''value'' samples, must be a multiple of 8 between 8 and 160.
+*'''--verify'''' &mdash; Files are encoded and then decoded to check accuracy.
+*'''--silent''' &mdash; The output of FLAC is hidden.
 == 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.
+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 ===
@@ Line 25: / Line 136: @@
 Example of usage:
-   compress_saga <flags here> <file>
+   ./scummvm-tools-cli --tool compress_saga <flags here> <file>
 Where <file> is the sound file you with to compress, without the
@@ Line 39: / Line 150: @@
 There is no compression support yet for the following versions:
-- The Mac CD Guild version of Inherit the Earth (uses MacBinary *.bin files)
+* The Mac CD Guild version of Inherit the Earth (uses MacBinary *.bin files)
-- The unsupported early DOS demo of Inherit the Earth
+* The unsupported early DOS demo of Inherit the Earth
-=== compress_sword1 ===
+=== compress_sci ===
-Used to compress Broken Sword 1's music and speech files to
+Used to compress Sierra resource.aud/.sfx and AUDIO001.002 files. This tool is not compatible with SCI32 games!
-MP3 or Vorbis or FLAC.
+Example of usage:
+  ./scummvm-tools-cli --tool compress_sci --vorbis [-o output] resource.aud
-=== compress_sword2 ===
+=== compress_scumm_bun ===
-Used to compress Broken Sword 2's music and speech .clu
+Used to the compress '.bun' music/voice files with MP3, Vorbis
-files to .cl3 (MP3), .clg (Vorbis) or .clf (FLAC).
+or FLAC.
-Please note that FLAC compression will produce a larger file
+Example of usage:
-than the original! This is because the original files already
+  ./scummvm-tools-cli --tool compress_scumm_bun --flac digmusic.bun uncomp comp
-use lossy compression.
-=== compress_touche ===
+Please note that FLAC compression will produce larger files
-Used to compress and pack Touche speech files ('Vxxx' and
+than the original, for The Curse of Monkey Island!
-'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 ===
@@ Line 67: / Line 175: @@
 Example of usage:
-   compress_scumm_san opening.san uncomp comp
+   ./scummvm-tools-cli --tool compress_scumm_san opening.san uncomp/ comp/
 In order to use such compressed files, your ScummVM binary
@@ Line 83: / Line 191: @@
 move the '.flu' files, too!
-=== compress_scumm_bun ===
+=== compress_scumm_sou ===
-Used to the compress '.bun' music/voice files with MP3, Vorbis
+Used to compress .sou files to .so3 (MP3), .sog (Vorbis),
-or FLAC.
+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:
-  compress_scumm.bun digmusic.bun uncomp comp --flac
+ ./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.
-Please note that FLAC compression will produce larger files
+It is possible to compress only the speech files or the music files using the '''--speech-only''' or '''--music-only''' flags:
-than the original, for The Curse of Monkey Island!
+  ./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_kyra ===
+=== compress_touche ===
-Used to compress The Legend of Kyrandia's speech files with
+Used to compress and pack Touche speech files ('Vxxx' and
-MP3, Vorbis or FLAC.
+'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:
-   compress_kyra <flags here> input/GEMCUT.VRM output/GEMCUT.VRM
+   ./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).
-Note: You have to keep the VRM extension, else it will NOT work.
+=== compress_tucker ===
-Use it like shown above, copy all *.VRM files to a directory
+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.
-and let the tool put the output file in another directory.
 == Encoder Tools ==
@@ Line 157: / Line 295: @@
 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 [[#pack_cge|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.
-=== extract_scumm_mac ===
+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.
-Extracts Macintosh "single file" SCUMM games into their
-component parts, for use with ScummVM.
+This tool takes some additional arguments, run ./scummvm-tools-cli --help extract_kyra for details.
-This is required for ScummVM up to version 0.6.x; all
-later versions directly support reading this file
+Example of usage:
-format.
+ ./scummvm-tools-cli --tool extract_kyra -x [-o outputdir] <infile>
 === extract_loom_tg16 ===
 Extracts data files from the PC-Engine version of Loom.
-Use the dumpcd utility at http://www.zeograd.com/misc_download.php
-to dump the code tracks on the CD.
+You will need to extract the code track from the CD with one of the following utilities
+'''Windows'''
+Use dumpcd [[http://www.zeograd.com/misc_download.php dumpcd Link]]/[[https://adrianastley.com/files/scummvm/dumpcd.exe.gz Alternative Link]]
+There is also a version with a GUI available [[https://adrianastley.com/files/scummvm/windumpcd.rar here.]]
+Alternatively use TurboRip from [[https://adrianastley.com/files/scummvm/TurboRipV100.rar here]].
+Another alternative is to use the PC-Engine emulator [http://www.ouma.jp/ootake/ 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 [[https://adrianastley.com/files/scummvm/dumpcd-0.1.zip here]].
 === extract_mm_apple ===
@@ Line 186: / Line 369: @@
 === 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|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)<br>
+version: -v1 or -v2 (Use -v1 for Future Wars, -v2 for Operation Stealth)<br>
+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
+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 [http://en.wikipedia.org/wiki/Standard_streams 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 ===
+== Other Tools ==
-Basic script disassembler for Legend of Kyrandia games
+=== pack_bladerunner ===
+Can be used to pack the four "CDFRAMES.DAT" files from the four Blade Runner CDs into a single "HDFRAMES.DAT" file (same file as created by the original game installer) that should be copied into the game's directory.
+ Syntax:
+  ./scummvm-tools-cli --tool pack_bladerunner [-o outputfile] <inputdir>/CDFRAMES1.DAT
+The <inputdir> should contain the "CDFRAMES.DAT" files from the game CDs, renamed as ''"CDFRAMES1.DAT", "CDFRAMES2.DAT", "CDFRAMES3.DAT", "CDFRAMES4.DAT"'' copied from the first, second, third and fourth CD respectively.
+Note that '''an alternative method''', also supported by ScummVM, is to simply copy the "CDFRAMES.DAT" files from each CD directly into the game directory; following this approach, the files from the first, second, third and fourth CDs should also be renamed as ''"CDFRAMES1.DAT", "CDFRAMES2.DAT", "CDFRAMES3.DAT", "CDFRAMES4.DAT"'' respectively, in order to be properly detected by ScummVM.
+=== 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.
+{{ManualFooterLinksNoNext|prev=Appendix: Config file description}}

Difference between revisions of "ScummVM Tools"

ScummVM Tools (view source)

Revision as of 21:40, 28 May 2019

Navigation menu

Search