Difference between revisions of "ScummVM Tools/new"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Improved manual with details on how to use the new tools, still missing screenshots and details about some tools.)
 
m (Cadi moved page User Manual/Appendix: Tools/new to ScummVM Tools/new: Remove page from the user manual appendix to standalone page)
 
(17 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{HelpWithManual}}
#REDIRECT [[User_Manual/Appendix:_Tools]]
{| border="0" cellpadding="2" cellspacing="1"  style="margin:1em; background:#FF0000;"
|- style="background:#ffffff"
|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.
 
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.
 
After this, you will be asked for 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:
 
./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:
 
./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 ====
*'''-b ''rate''''' &mdash; ''rate'' is the target bitrate(ABR)/minimal bitrate(VBR).
*'''-B ''rate''''' &mdash; ''rate'' is the maximum VBR/ABR 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.
 
==== 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 (0 - 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_agos ===
Used to compress the Feeble Files or Simon 1/2 voc/wav files
to MP3, Vorbis or FLAC.
 
=== compress_gob ===
Pending content...
 
=== 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.
 
=== 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_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_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_sou ===
Used to compress .sou files to .so3 (MP3), .sog (Vorbis),
or .sof (FLAC).
 
=== 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_tinsel ===
Pending content...
 
=== 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_tucker ===
Pending content...
 
== 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_cine ===
...
 
=== extract_gob_stk ===
...
 
=== extract_kyra ===
Unpacks .PAK files from Kyrandia games.
 
=== 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 [[http://www.zeograd.com/misc_download.php dumpcd]]/[[http://gracesdisposal.bpweb.net/LOOM/ISO%20TOOLS/DUMPCD%20WIN/ GUI]]
Alternatively use TurboRip from [[http://pcedev.net/utils/ here]].
 
'''Linux'''
 
Use dumpcd [[http://gracesdisposal.bpweb.net/LOOM/ISO%20TOOLS/DUMPCD%20LINUX/dumpcd-bin-0.1.tar.bz2 dumpcd]]
 
Alternatively you may compile dumpcd using the source code available [[http://gracesdisposal.bpweb.net/LOOM/ISO%20TOOLS/DUMPCD%20SOURCE%20LINUX/ 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_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 [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 ===
Basic script disassembler for Legend of Kyrandia games
 
{{ManualFooterLinksNoNext|prev=Appendix: Config file description}}

Latest revision as of 21:13, 3 March 2021

Redirect to:

Retrieved from "https://wiki.scummvm.org/index.php?title=ScummVM_Tools/new&oldid=32096"