Difference between revisions of "User Manual"

From ScummVM :: Wiki
Jump to navigation Jump to search
m (Change "CVS" to "SVN")
(Remove link to deleted page)
 
(50 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Edit-first-section}}  
{{DISPLAYTITLE:[Deprecated] User Manual }}
 
{| border="0" cellpadding="1" cellspacing="2" style="margin-left:5em; background:#FF9999; width:80%"
{| border="0" cellpadding="2" cellspacing="1" align="left" style="margin:1em; background:#FF0000; width:40%"
|- align="center"
|- align="center"
| '''WORK IN PROGRESS, HELP NEEDED'''
|'''Check out our new user documentation!'''
|- style="margin-left:1em; background:#ffffff;"
|- style="margin-left:1em; background:#ffffff;"
|- style="background:#ffffff"
|- style="background:#ffffff"
|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, working on the [http://scummvm.svn.sourceforge.net/viewvc/scummvm/docs/trunk/docbook/ DocBook version] or supplying us with HTML or TeX sources is fine, too (we will then translate them for the Wiki and into DocBook).
|We have a user documentation portal at [https://docs.scummvm.org docs.scummvm.org]. It covers all aspects of using ScummVM, including how to install ScummVM on a variety of platforms, how to add and play games, and how to tweak settings for optimal game play.
|}
|}__NOEDITSECTION__ __NOTOC__
{{-}}
 
{| align="right"
  | __TOC__
  |}
 
 
= Introduction =
== What is ScummVM? ==
ScummVM is a program which allows you to run certain classic graphical
point-and-click adventure games, provided you already have their data
files. The clever part about this: ScummVM just replaces the
executables shipped with the game, allowing you to play them on
systems for which they were never designed!
 
Some of the adventures ScummVM supports include Adventure Soft's Simon
the Sorcerer 1 and 2; Revolution's Beneath A Steel Sky, Broken Sword 1
and Broken Sword 2; Flight of the Amazon Queen; Wyrmkeep's Inherit the
Earth; Coktel Vision's Gobliiins; Westwood Studios' The Legend of
Kyrandia and games based on LucasArts' SCUMM (Script Creation Utility
for Maniac Mansion) system such as Monkey Island, Day of the Tentacle,
Sam and Max and more. You can find a thorough list with details on
which games are supported and how well on the compatibility
page. ScummVM is continually improving, so check back often.
 
Among the systems on which you can play those games are Windows,
Linux, Mac OS X, Dreamcast, PocketPC, PalmOS, AmigaOS, BeOS, OS/2,
PSP, PS2, SymbianOS/EPOC and many more.
 
At this time ScummVM should be considered beta software, and is still
under heavy development. Be aware that whilst we attempt to make sure
that many games can be completed with few major bugs, crashes can happen.
 
If you enjoy ScummVM feel free to
[http://sourceforge.net/donate/index.php?group_id=37116 donate some money]
to help us. This will help us buy utilities needed to develop ScummVM
easier and quicker. If you cannot donate, help and contribute a patch!
 
== Reporting bugs ==
To report a bug, please create a [http://sourceforge.net SourceForge account],
then use our [http://sourceforge.net/tracker/?group_id=37116&atid=418820 bug tracker]
to file a report (you can also reach it via the "Bug Tracking" link from
[http://www.scummvm.org our homepage].
Please make sure the bug is reproducible, and still occurs in the latest
daily build/current SVN version. Also check the bug doesn't already exist on the bug tracker, and have a look at the [http://www.scummvm.org/compatibility.php compatibility list on our website]
for that game, to ensure the issue is not already known.
 
Also, please do not report bugs on games that are not listed as being completable in [[#Appendix: Supported games | Appendix: Supported games]], or in the online [http://www.scummvm.org/compatibility.php compatibility list].
We already '''''know''''' those games have bugs.
 
Please include the following information:
 
*ScummVM version (PLEASE test the latest SVN/Daily build)
*Bug details, including instructions on reproducing
*Language of game (English, German, ...)
*Version of game (talkie, floppy, ...)
*Platform and Compiler (Win32, Linux, FreeBSD, ...)
*Attach a save game if possible
*If this bug only occurred recently, please note the last version without the bug, and the first version including
the bug. That way we can fix it quicker by looking at the changes made.
 
This should only take you a little time but will make it much easier for us to process your bug report in a way that satisfies both you and us.
 
== Contacting the developers ==
The easiest way to contact the ScummVM team is by submitting bug reports (see reporting-bugs) or by using our
[http://forums.scummvm.org forums]. You can also join and email the scummvm-devel mailing list (see
[http://lists.sourceforge.net/lists/listinfo/scummvm-devel]). Or chat with us on IRC (channel #scummvm on irc.freenode.net).
 
Please do not ask us to support an unsupported game -- read
[http://www.scummvm.org/faq.php our FAQ] for an explanation.
 
= Getting started =
 
== Requirements ==
TODO: List Requirements (in terms of required/optional libraries, CPU power, memory, ... In particular it would be nice if we could e.g. say what PalmOS devices support ScummVM; not necessarily a list of all supported Palm models, but more a list of what OS you need how much memory, colors, etc.)
 
ScummVM is known to run on the following systems:
*Unix-like (Linux, *BSD, Solaris, etc.)
*Windows
*Mac OS X
*Windows Mobile (WinCE / PocketPC / Smartphone)
*PalmOS
*Dreamcast
*MorphOS
*GP32
*GP2X
*Symbian based smartphones
*PlayStation 2
*PlayStation Portable
*Nintendo DS
*BeOS
*AmigaOS 4
*Atari/FreeMiNT
*Solaris
*OS/2
*Opie
 
Besides these, there have been many more unofficial ports in the past. Since they were not done by us, we can not say anything about their reliability, legality, or availability, nor can we provide support for them. Use them at your own risk!
 
Among those officially unsupported systems are:
 
*XBox
*RISC OS
 
If you plan to compile ScummVM yourself, you will need certain additional libraries. More on that in [[#Compiling from sources | Compiling from sources]].
 
== How to obtain ScummVM ==
Basically you have two choices on how to get ScummVM: either you download one of the binaries we built for you (probably the most convenient way); or you can compile it yourself from source. For beginners, we strongly recommend using our prebuilt binaries.
 
=== Binaries ===
You can download official binaries of ScummVM from our [http://www.scummvm.org/downloads.php downloads page]. Go there with your favorite web browser and download the binary for your platform. If none is available, you may have to build ScummVM yourself, refer to the next section for instructions on how to do that. Alternatively, some third parties are providing unofficial ScummVM binaries for further platforms, but naturally, we can not make any statements about the quality of such unofficial builds - use them at your own risk!
 
We always ship pre-built binaries of ScummVM for the following platforms (note that it can take some time after a release for all binaries to be available):
*Linux (Fedora Core)
*Linux (Debian)
*Windows
*Mac OS X
*Windows Mobile (WinCE / PocketPC / Smartphone)
*Symbian
*Dreamcast
*PlayStation 2
*PlayStation Portable
*Nintendo DS
*GP2X
 
In addition to these, we try to provide more binaries, but which depends mostly on how many volunteers we can find to help us out. In the past we have shipped binaries for these systems:
*Linux (Mandrake)
*Linux (Slackware)
*Solaris
*BeOS
*AmigaOS 4
*MorphOS
*OS/2
 
=== Compiling from sources ===
TODO:
* Point to the [[Compiling ScummVM]] page, resp. integrate that here.
* List all required libs; where to get them; how to install them
* List all optional libs etc.
* We could separate this by OS, or by compiler/dev system. I think the current split in the README (section 9.0) isn't too bad.
 
 
== Installation ==
After you have obtained ScummVM as described in the previous section, you will probably want to install it on your system. The steps required for that differ between the various operating systems. In the following we try to cover all the systems we officially support.
 
=== Debian ===
From the downloads page, download the Debian .deb package. To install it, you need to be root and type ''dpkg -i packagename.deb'' into a virtual terminal near you.
 
=== Fedora Core / Redhat ===
TODO
 
=== Slackware ===
TODO
 
=== Amiga OS4 ===
From the downloads page, get the AmigaOS4 package. You will download a packed archive (.lha). To open it, double click on it and UnArc will unpack right away or ask for the installation path. Once it is unpacked, you can move the whole drawer where ever you wish to store it.
 
=== Windows ===
From the downloads page, download either the Win32 .zip file or the Win32 .exe file. If you download the .zip file, you will need a program such as WinZip to open it. After opening the archive, copy it to the folder where you want to put it. If you download the .exe installer, you will get options where you want to install it. Choose the location to where you want to install it. Also, the installer places a shortcut in the Start Menu.
 
=== Mac OS X ===
From the downloads page, download the "Mac OS X Universal Binary" file. You will download a disk image (.dmg). To open it, double click on it and Disk Copy will mount the image. Once it is mounted, copy the files inside to a folder where you wish to store it.
 
=== Windows Mobile (WinCE / PocketPC / Smartphone) ===
Create a folder on your device to put ScummVM into, e.g. "\My Device\SD-MMcard\ScummVM". From the downloads page, download the "Windows CE ARM package" zip file. Extract everything from this file, and place it all in the folder that you created on your device (using ActiveSync or similar: note that if your chosen location is short of space, the only absolutely ''required'' file is "scummvm.exe"). To run ScummVM just tap on "scummvm.exe" in File Explorer: you may wish to copy a shortcut of "scummvm.exe" to your Start Menu to allow for easier access.
 
=== PalmOS ===
From the downloads page, download the "PalmOS 5 binary" or the "PalmOS Tapwave Zodiac binary" and unzip the files to your computer. Using your hotsync tool, install the scummvm-frontend.prc and skin.pdb files to your device. Launch ScummVM to create the /PALM/Programs/ScummVM/ folders and subfolders on your memory card. Using a card reader, copy the engines you require to play your games to the /ScummVM/Mods/ folder on your card (scumm.engine for scumm games, queen.engine for FOTAQ, etc.)
 
=== Symbian / EPOC ===
TODO
 
=== Nintendo DS ===
TODO
 
=== Dreamcast ===
From the downloads page, download either the Dreamcast .zip file or the Nero image file. If you download the .zip file, you will need a program such as WinZip to open it. After opening the archive, copy it to the folder where you want to put it. The Nero image can be burned automatically to a CD using Nero Burning ROM or any other program that accepts NRG formatted disc images.
 
=== GP2X ===
TODO
 
=== GP32 ===
TODO
 
=== PlayStation 2 ===
TODO
 
=== PlayStation Portable ===
TODO
 
== First steps ==
 
= Running and using ScummVM =
== The Launcher ==
=== Managing your games ===
==== Adding a game ====
Before you can play a game using ScummVM, you first need to ''add'' it to the Launcher.
# Your game will run more smoothly if you copy all the files from the original disk(s) (whether floppy or CD) into a folder on your hard-drive.
# {{ManualScreenshot|name=Emptylauncher.png|desc=The ScummVM Launcher}} Click on the "Add Game..." button on the right-hand side of the Launcher.{{-}}
# {{ManualScreenshot|name=Adddialog.png|desc=Add Game Dialog Box}} You will now be presented with a file browser. You should use this browser to locate the directory in which the files from your game's disks are located. Double click on the name of a directory to go into it, and use the "Go up" button to go back up one level. Once you are in the correct folder, click the "Choose" button.{{-}}
# {{ManualScreenshot|name=Addgamesettings.png|desc=Game Settings Dialog Box}} If ScummVM detected the game correctly, it will now display a dialog box which lets you change various settings about the game, including the name that appears in the main window of the Launcher. There are six tabs full of settings to change, and these are discussed later on in the [[#Configuration|configuration]] section, but you don't need to change any of them. To finish adding your game, just click the "OK" button.{{-}}
# {{ManualScreenshot|name=Launcherwithgame.png|desc=The ScummVM Launcher with one game added}} Tada! You've added your first game to ScummVM. To play it now, just select the game you want to play and click on the Start button.{{-}}
 
==== Adding multiple games at once ====
 
# {{ManualScreenshot|name=Massadd.png | desc=Confirmation dialog for mass add}} If all of your games are in separate subdirectories of one "games" directory, you can add all of your games at once. Simply hold down the "shift" key, and the "Add Game..." button will switch to being a "Mass Add..." button. If you click on it, the ScummVM Launcher will ask you to confirm that you really do want to do this.{{-}}
# {{ManualScreenshot|name=Massaddbrowse.png | desc=File browser for mass add}} You will then be presented with the same file browser that we used previously to select just one game. This time, however, click "Choose" when you are in the top-level directory which all your game directories are inside.{{-}}
# {{ManualScreenshot|name=Launcherwithgames.png | desc=Mass add complete}} The mass add will then search for all the games it can find within that directory, and come back and let you know how many it found. You should then see all the games it found inside the Launcher window.{{-}}
 
==== Removing a game ====
{{ManualScreenshot|name=Deletegame.png|desc=Dialog to confirm deletion}} To remove a game from the ScummVM Launcher, just select the game you want to remove and click the "Remove Game" button on the right-hand side. ScummVM will ask you whether you are sure you want to remove it, so click yes to remove it. Note that this will not delete the game files from your hard drive: you can easily re-add it again later.{{-}}
 
=== Configuring the Launcher and configuring individual games ===
There are many options to change the way that ScummVM runs games: for discussion of these options see the [[#Configuration|configuration]] section.
 
== Running ScummVM from the command line ==
As well as starting your ScummVM games using the graphical Launcher, you can also start them from the command line. The simplest way to run a game from the command line is to type, for example:
<pre>scummvm samnmax</pre>
 
Note this command is dependent on your system. You may have to specify exactly where ScummVM is installed to, for example in Windows:
<pre>c:\games\scummvm\scummvm.exe samnmax</pre>
Or in Unix:
<pre>/home/username/scummvm/scummvm samnmax</pre>
 
The short game name you see at the end of the command line ("samnmax" in this case) specifies which game is started. It either corresponds to a user-defined target (i.e. one that has been added using the Launcher: this is the case in the example above), or to a built-in gameid. A brief list of the latter can be found in the supported games section.
 
There are many different ''options'' that can be specified to make ScummVM run the game just the way you want, and these are listed in the table below. The meaning of most long options (that is, those options starting with a
double-dash) can be inverted by prefixing them with "no-". For example,
"--no-aspect-ratio" will turn aspect ratio correction off. This is useful
if you want to override a setting in the configuration file.
 
=== Command line options ===
{|class="wikitable"
|+ <pre>scummvm [OPTIONS] GAME</pre>
|-
! Short
! Long
! Description
|-
| -v
| --version
| Display ScummVM version information and exit
|-
| -h
| --help
| Display a brief help text and exit
|-
| -z
| --list-games
| Display list of supported games and exit
|-
| -t
| --list-targets
| Display list of configured targets and exit
|-
| -c
| --config=''CONFIG''
| Use alternate configuration file
|-
| -p
| --path=''PATH''
| Path to where the game is installed
|-
| -x
| --save-slot[=''NUM'']
| Save game slot to load (default: autosave)
|-
| -f
| --fullscreen
| Force full-screen mode
|-
| -F
| --no-fullscreen
| Force windowed mode
|-
| -g
| --gfx-mode=''MODE''
| Select graphics scaler (see also [[#Graphic_filters|Graphic filters]])
|-
|
| --gui-theme=''THEME''
| Select GUI theme (default, modern, classic)
|-
|
| --themepath=''PATH''
| Path to where GUI themes are stored
|-
| -e
| --music-driver=''MODE''
| Select music driver (see also [[#Music_drivers|Music drivers]])
|-
| -q
| --language=''LANG''
| Select language (see also section TODO)
|-
| -m
| --music-volume=''NUM''
| Set the music volume, 0-255 (default: 192)
|-
| -s
| --sfx-volume=''NUM''
| Set the sfx volume, 0-255 (default: 192)
|-
| -r
| --speech-volume=''NUM''
| Set the voice volume, 0-255 (default: 192)
|-
|
| --midi-gain=''NUM''
| Set the gain for MIDI playback, 0-1000 (default:100) (only supported by some MIDI drivers: see [[#Music_drivers|Music drivers]])
|-
| -n
| --subtitles
| Enable subtitles (use with games that have voice)
|-
| -b
| --boot-param=''NUM''
| Pass number to the boot script (boot param)
|-
| -d
| --debuglevel=''NUM''
| Set debug verbosity level
|-
|
| --debugflags=''FLAGS''
| Enables engine specific debug flags (separated by commas)
|-
| -u
| --dump-scripts
| Enable script dumping if a directory called 'dumps' exists in the current directory
|-
|
| --cdrom=''NUM''
| CD drive to play CD audio from (default: 0 = first drive)
|-
|
| --joystick[=''NUM'']
| Enable joystick input (default: 0 = first joystick)
|-
|
| --platform=''WORD''
| Specify version of game (allowed values: 3do, acorn, amiga, atari, c64, fmtowns, mac, nes, pc, segacd, windows)
|-
|
| --savepath=''PATH''
| Path to where savegames are stored
|-
|
| --extrapath=''PATH''
| Extra path to additional game data
|-
|
| --soundfont=''FILE''
| Select the SoundFont for MIDI playback (only supported by some MIDI drivers: see [[#Music_drivers|Music drivers]])
|-
|
| --multi-midi
| Enable combination of Adlib and native MIDI (see [[#Music_drivers|Music drivers]])
|-
|
| --native-mt32
| True Roland MT-32 (disable GM emulation) (see [[#Music_drivers|Music drivers]])
|-
|
| --enable-gs
| Enable Roland GS mode for MIDI playback (see [[#Music_drivers|Music drivers]])
|-
|
| --output-rate=''RATE''
| Select output sample rate in Hz (e.g. 22050) (see [[#Output_sample_rate|Output sample rate]])
|-
|
| --aspect-ratio
| Enable aspect ratio correction (see [[#Graphics_tab|Graphics settings]])
|-
|
| --render-mode=''MODE''
| Enable additional render modes (see [[#Graphics_tab|Graphics settings]])
|-
|
| --alt-intro
| Use alternative intro for CD versions of Beneath a Steel Sky and Flight of the Amazon Queen
|-
|
| --copy-protection
| Enable copy protection in SCUMM games, when ScummVM disables it by default. '''''***TODO Add link to the copy protection section***'''''
|-
|
| --talkspeed=''NUM''
| Set talk speed for SCUMM games
|-
|
| --demo-mode
| Start demo mode of Maniac Mansion
|-
|
| --tempo=''NUM''
| Set music tempo (in percent, 50-200) for SCUMM games (default: 100)
|}
 
=== Examples of Command Line Usage ===
;Running Monkey Island, fullscreen, from a hard disk (Win32):<code>C:\Games\LucasArts\scummvm.exe -f -pC:\Games\LucasArts\monkey\ monkey</code>
;Running Full Throttle from CD, fullscreen and with subtitles enabled (Win32):<code>C:\Games\LucasArts\scummvm.exe -f -n -pD:\resource\ ft</code>
;Running Monkey Island, fullscreen, from a hard disk (Unix):<code>/path/to/scummvm -f -p/games/LucasArts/monkey/ monkey</code>
;Running Full Throttle from CD, fullscreen and with subtitles enabled (Unix):<code>/path/to/scummvm -f -n -p/cdrom/resource/ ft</code>
 
== Hotkeys ==
TODO
 
== Saving and loading ==
TODO
 
== Macintosh games: Accesing HFS filesystems ==
You will need the "Windows Installer" from the download page. To copy the game data file from the CD to your hard disc, you will need [http://home.earthlink.net/~gamba2/pc2mac.html HFVExplorer]. Make sure you get the "HFV Explorer installer" rather than the zip file. When you choose to download the zip file, make sure you read the readme included with HFVExplorer, to set it up properly. Run the HFVExplorer installer and allow it to use its defaults.
 
Start up HFVExplorer; if you don't have a shortcut for it, find it in "C:\Program Files\HFVExplorer". It should open the HFS (Macintosh filesystem) CD-ROM automatically when you insert the disc. Make sure HFVExplorer is displaying hidden files: Select View->Options and enable "Show invisible Mac files" on the "File attributes" tab.
 
Now, look for the data file in the right pane. It will probably end with the word "Data" and will be the largest file on the volume. For instance (using Sam &amp; Max Hit the Road as an example), it is called "Sam &amp; Max Data" on the "Sam &amp; Max" CD-ROM. Select the data file and copy it (use Ctrl+C or Edit->Copy). In the left HFVExplorer pane, navigate to the directory where you want the game to reside on your hard disc. We recommend selecting drive C: and creating a new folder called "SamNMax" or a name that better reflects your particular game.
 
Paste the data file (with Ctrl+V or Edit->Paste) and allow HFVExplorer to choose the copy mode. Now, wait while the program copies several hundred megabytes from the CD. When the file is copied, close HFVExplorer.
 
More details (including how to use extract_scumm_mac) can be found at [[HOWTO-Mac_Games]], a wiki page dedicated specifically to Macintosh games.
 
== Multi-CD games ==
In general, ScummVM does not deal very well with multi-CD games. This is because ScummVM assumes everything about a game can be found in one directory. Even if ScummVM does make some provisions for asking the user to change CD, the original games usually install a small number of files to hard disk. Unless these files can be found on all the CDs, ScummVM will be in trouble.
 
Fortunately, ScummVM has no problems running the games entirely from hard disk, if you create a directory with the correct combination of files. Usually, when a file appears on more than one CD you can pick either of them.
 
These instructions are written for the PC versions (which in some case is the only version) of the games. Windows and DOS use case-insensitive file systems, so if one CD has a file called MONKEY.DAT and another has a file called monkey.dat, they are the same files. These instructions give file names in all lower-case names, even if that’s not always how they appear on the CDs. In fact, on case-sensitive file systems you will have to make sure that all filenames use either all upper- or all lower-case letters for ScummVM to be able to find the files.
 
The instructions for the Broken Sword games are for the Sold-Out Software versions, which are the ones you are probably most likely to find in stores now.
 
=== The Curse of Monkey Island ===
For this game, you will need the comi.la0, comi.la1 and comi.la2 files. The comi.la0 file can be found on either CD, but since they are identical it doesn't matter which one of them you use.
 
In addition, you will need a resource subdirectory with all of the files from the resource subdirectories on both CDs. Some of the files appear on both CDs, but again they're identical.
 
=== Broken Sword 1 ===
For this game, you will need all of the files from the clusters directories on both CDs. You will also need the speech.clu files from the speech directories, but since they are not identical you will need to rename them speech1.clu and speech2.clu for CD 1 and 2 respectively.
 
In addition, you will need a music subdirectory with all of the files from the music subdirectories on both CDs. Some of these files appear on both CDs, but in these cases they are either identical or, in one case, so nearly identical that it makes little difference.
 
ScummVM does not support the original cutscene files (with file extension .smk) for legal reasons, so there is no need to copy them.
 
=== Broken Sword 2 ===
For this game, you will need all of the files from the clusters directories on both CDs. (Actually, a few of them may not be strictly necessary, but the ones that I’m uncertain about are all fairly small.) You will need to rename the speech.clu and music.clu files speech1.clu, speech2.clu, music1.clu and music2.clu so that ScummVM can tell which ones are from CD 1 and which ones are from CD 2. Any other files that appear in both cluster directories are identical. Use whichever you like.
 
In addition, you will need the cd.bin, cd.inf and startup.inf files from the sword2 directory on CD 1.
 
ScummVM does not support the original cutscene files (with file extension .smk) for legal reasons, so there is no need to copy them.
 
=== The Feeble Files ===
 
TODO
 
= Configuration =
== Using the Launcher to configure ScummVM ==
The ScummVM Launcher gives us a graphical method for changing the settings that it uses to run games. There are two ways to do this: firstly by changing the default settings (which games will follow unless told otherwise), secondly by overriding an individual game to use settings that are different from the defaults. To begin with we will look at changing the default settings. To do this, click on the "Options" button on the right-hand side of the Launcher window. There are many options, and they are separated into tabs: we shall look at each tab in turn.
 
=== Graphics tab ===
{{ManualScreenshot|name=Graphicstab.png|desc=The Graphics tab of the ScummVM options}}
The graphics tab allows us to change various things about the way the games are displayed on screen when played.
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Graphics mode
| This allows us to change the graphic filter that ScummVM uses. See the [[#Graphic_filters|Graphic filters]] section of the manual for more detail
|-valign="top"
| Render mode
| For games that could be played on various different systems / graphics cards, this control allows us to decide which system we want ScummVM to reproduce. The options are <default> (which tries to choose the most sensible option), Hercules Green, Hercules Amber (monochrome), CGA (4 colors), EGA (16 colors), and Amiga (32 colors))
|-valign="top"
| Fullscreen mode
| Switches between playing games in a window, or playing them in fullscreen mode. Switch between the two using Alt-F5 while in a game.
|-valign="top"
| Aspect ratio correction
| Most games supported by ScummVM were designed to be played at a screen resolution of 320x200. Most modern systems, when displaying this size image, will display it in a window that is not 1.33:1 (as the designers intended), but 1.6:1 or even 1.7:1. This results in the game appearing stretched and the characters looking wider than they should. If this option is checked, ScummVM corrects for this by stretching the game window down by a similar amount, and the game can be played without distortion. Like [[#Graphic_filters|Graphic filters]], this takes a little processing power to achieve.
|}
{{-}}
 
=== Audio tab ===
{{ManualScreenshot|name=Audiotab.png|desc=The Audio tab}}The audio tab in the options allows us to change various things about the way that sound is outputted in ScummVM games.
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Music driver
| This is the method that ScummVM uses to output MIDI music. For more details, see the [[#Music_drivers | section on music drivers]].
|-valign="top"
| Output rate
| This is the sample rate at which ScummVM plays back sounds (including music if using the Adlib <*** TODO or others? ***> music driver). For more information, see the [[#Output_sample_rate| Output sample rate section]]
|-valign="top"
| Text and Speech
| For games with digitized speech, this control allows the user to decide whether to play the game with speech and without any subtitles, with subtitles displaying the words spoken in the digitized speech but not the speech, or with both.
|-valign="top"
| Subtitle speed
| This allows the user to adjust the length of time that the subtitles are displayed on screen: the lower the speed is set, the longer the subtitles appear for.
|}
{{-}}
 
=== Volume tab ===
{{ManualScreenshot|name=Volumetab.png|desc=The Volume tab}}The volume tab allows us to set the relative volumes for the various different types of sound that ScummVM plays.
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Music volume
| The volume of the music played back in games. This is usually MIDI music played back with one of the [[#Music_drivers|music drivers]], but some games use digitized music.
|-valign="top"
| SFX volume
| The volume of the sound effects within the games. '''''*** TODO: are MIDI sound effects included in this, or are they controlled by the Music volume? ***'''''
|-valign="top"
| Speech volume
| The volume of the digitized speech in the game, if it has any.
|}
{{-}}
 
=== MIDI tab ===
{{ManualScreenshot|name=Miditab.png|desc=The MIDI tab}} The MIDI tab lets us change various settings about the MIDI music played back in games.
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Soundfont
| *** TODO ***
|-valign="top"
| Mixed Adlib/MIDI mode
| *** TODO ***
|-valign="top"
| True Roland MT-32 (disable GM emulation)
| *** TODO ***
|-valign="top"
| Enable Roland GS Mode
| *** TODO ***
|-valign="top"
| MIDI gain
| *** TODO ***
|}
{{-}}
 
=== Paths tab ===
{{ManualScreenshot|name=Pathstab.png|desc=The Paths tab}}This part of the options lets the user tell ScummVM where to look for particular files
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Save Path
| This is the default folder in which ScummVM will store saved games. If this is not set, saved games will generally be stored in the current directory. Exceptions to this include Mac OS X (''$HOME/Documents/ScummVM Savegames/'') and other UNIX variants (''$HOME/.scummvm/'').
|-valign="top"
| Extra Path
| This is the folder that ScummVM will look in for various "extra" files. These could include one or more of:
* Additional datafiles required for certain games (e.g. kyra.dat)
* Soundfonts (see [[#MIDI_tab|MIDI tab]])
* MT-32 ROMs (see [[#Music_drivers|Music drivers]])
|-valign="top"
| Theme Path
| The folder that additional themes for the ScummVM Launcher are stored in.
|}
{{-}}
 
=== Misc tab ===
{{ManualScreenshot|name=Misctab.png|desc=The Misc tab}}The Misc tab contains options that don't belong on any of the other tabs.
{|class="wikitable"
|-valign="top"
! width="120"|Control
! Description
|-valign="top"
| Theme
| Click on this button to change the visual appearance of the ScummVM Launcher
|-valign="top"
| Autosave
| In some games (namely ''Beneath a Steel Sky'', ''Flight of the Amazon Queen'' and all SCUMM games), ScummVM will automatically save the game every few minutes. For the SCUMM engine, it will save in Slot 0. This saved game can be loaded again using Ctrl-0 or the F5 menu. Use this control to adjust the time period that ScummVM waits between saves; the default setting is 5 minutes.
|}
 
{{-}}
 
== Using the configuration file to configure ScummVM ==
When you change a setting in the ScummVM Launcher (see [[#Using_the_Launcher_to_configure_ScummVM |Using the Launcher to configure ScummVM]]), all it does is add a line to the ''configuration file''. This is a plain text file which stores all the settings for ScummVM. It is possible to edit this file directly, and some settings can only be changed this way.
 
The name of the config file and the location in which it is stored depend on the system you are running ScummVM on:
 
{|class="wikitable"
|-
! Operating System
! Location of config file
|-
| Windows Vista
| \Users\username\AppData\Roaming\ScummVM\scummvm.ini
|-
| Windows 2000/XP
| \Documents and Settings\username\Application Data\ScummVM\scummvm.ini
|-
| Windows NT4
| <windir>\Profiles\username\Application Data\ScummVM\scummvm.ini
|-
| Windows 95/98/ME
| <windir>\scummvm.ini
|-
| Unix
| $HOME/.scummvmrc
|-
| Mac OS X
| $HOME/Library/Preferences/ScummVM Preferences
|-
| Others
| scummvm.ini in the current directory
|}
Note: all Windows versions will use <windir>\scummvm.ini if it already exists.
 
=== All config file switches in detail ===
 
== Graphic filters ==
 
ScummVM offers several anti-aliasing filters to attempt to improve visual
quality. These filters take the original game graphics, and scale it by a
certain fixed factor (usually 2x or 3x) before displaying them to you.
So for example, if the game originally ran at a resolution of 320x200
(typical for most of the SCUMM games), then using a filter with a scale
factor of 2x will effectively yield 640x400 graphics. Likewise a
3x filter will give 960x600.
 
ScummVM uses the following graphic filters:
{|class="wikitable"
|-
! Name
! Factor
! Description
|-
| 1x
| 1x
| No filtering, no scaling, fastest
|-
| 2x
| 2x
| No filtering, simple pixel duplication (default for non 640x480 games)
|-
| 3x
| 3x
| No filtering, simple pixel duplication
|-
| 2xsai
| 2x
| SAI filter
|-
| super2xsai
| 2x
| Enhanced 2xSAI filtering
|-
| supereagle
| 2x
| Less blurry than 2xSAI, but slower
|-
| advmame2x
| 2x
| Doesn't rely on blurring like 2xSAI, fast
|-
| advmame3x
| 3x
| Doesn't rely on blurring like 2xSAI, fast
|-
| hq2x
| 2x
| Very nice high quality filter but slow
|-
| hq3x
| 3x
| Very nice high quality filter but slow
|-
| tv2x
| 2x
| Interlace filter, tries to emulate a TV
|-
| dotmatrix
| 2x
| Dot matrix effect
|}
 
To select a graphics filter from the command line, use the '-g' [[#Command_line_options|command line option]], e.g.:
 
<pre>scummvm -gadvmame2x monkey2</pre>
 
There is always a speed impact when using any form of anti-aliasing/linear filtering. Filters can be especially slow when ScummVM is compiled in a debug
configuration without optimizations. For these reasons, not all backends support all (or even any) of the filters listed above;
some may support additional ones. The filters listed above are those supported by the default SDL backend.
 
NB: The final resolution depends on the original resolution of the game you are playing. For example, the FM-TOWNS version of Zak McKracken uses an original resolution of 320x240, hence for this game the final resolution with a scaler will be 640x480 (2x) or 960x720 (3x).
Likewise, games that were originally 640x480 (such as Curse of Monkey Island or the Broken Sword games) will be scaled to 1280x960 (2x) and 1920x1440 (3x).
 
== Music and Sound ==
=== Music drivers ===
=== Using compressed audio files ===
=== Output sample rate ===
The output sample rate tells ScummVM how many sound samples to play per channel per second. There is much that could be said on this subject, but most of it is beyond the scope of this document. The short version is that for most games 22050 Hz is fine, but in some cases 44100 Hz is preferable. On extremely low-end systems you may want to use 11025 Hz, but it’s unlikely that you will have to worry about that.
 
To elaborate, most of the sounds that ScummVM has to play were sampled at either 22050 Hz or 11025 Hz. Using a higher sample rate will not magically improve the quality of these sounds, thus 22050 Hz is fine.
 
Some games use CD audio. If you use compressed files for this, they are probably sampled at 44100 Hz, so for these games that may be a better choice of sample rate.
 
When using the Adlib, FM Towns, PC Speaker or IBM PCjr music drivers, ScummVM is responsible for generating the samples. Usually 22050 Hz will be plenty for these, but there is at least one piece of Adlib music in Beneath a Steel Sky that will sound a lot better at 44100 Hz.
 
Using frequencies in between is not recommended. For one thing, your sound card may not support it. In theory, ScummVM should fall back on a sensible frequency in that case, but don’t count on it. More importantly, ScummVM has to resample all sounds to its output frequency. This is much easier to do well if the output frequency is a multiple of the original frequency.
 
= Appendix: Supported games =
The list of games supported by the most recent stable version of ScummVM can be found on the [http://www.scummvm.org/compatibility_stable.php Compatibility page], or the games supported by the current unstable version can be found on the [http://www.scummvm.org/compatibility.php SVN Compatibility page].
The [[Engines|Engines page]] in the wiki also lists these things, along with the engines that are still work-in-progress.
 
= 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.
 
== 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 <inputfile> <inputdir> <outputdir> [--ogg] ===
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 <inputfile> <inputdir> <outputdir> [params] ===
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.
Use the dumpcd utility at http://www.zeograd.com/misc_download.php
to dump the code tracks on the CD.
 
=== 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 ===
{{ManualSectionNoLink|name=Getting Help|desc=
Decompiles SCUMM scripts
# [https://github.com/scummvm/scummvm/blob/v{{StableVersion}}/README.md ReadMe file for version {{StableVersion}}]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/cz/PrectiMe Czech translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/de/LIESMICH German translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/se/LasMig Swedish translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/da/HurtigStart Danish QuickStart translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/fr/DemarrageRapide French QuickStart translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/it/GuidaRapida Italian QuickStart translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/no-nb/HurtigStart Norwegian (bokmaal) QuickStart translation]
## [https://github.com/scummvm/scummvm/raw/v{{StableVersion}}/doc/es/InicioRapido Spanish QuickStart translation]
}}


=== desword2 ===
{{ManualSectionNoLink|name=Appendix|desc=# [[User Manual/Appendix: Controls|Control Mapping for supported devices]]
Disassembles Broken Sword II scripts
# [[User Manual/Appendix: Graphic filters|Graphic filters]]
# [[User Manual/Appendix: Tools|Tools]], a list of the tools available for use with ScummVM (e.g. for compressing audio), along with a description of their usage
# [[User Manual/Appendix: Integrations|Integrations]]
}}


=== dekyra ===
{{ManualSectionNoLink|name=Links|desc=
Basic script disassembler for Legend of Kyrandia games
You will find help on using ScummVM in other places on the web. Here are a few links to solve frequent issues or that my help you improve your experience with ScummVM.
* HOW-TOs:
** [https://forums.scummvm.org/viewtopic.php?t=8440 How to catch ScummVM errors <nowiki>[forum]</nowiki>]
** [https://forums.scummvm.org/viewtopic.php?t=8012 How to play multi-disc games with ScummVM <nowiki>[forum]</nowiki>]
** [https://forums.scummvm.org/viewtopic.php?t=6303 Enhanced ScummVM MIDI music on Windows <nowiki>[forum]</nowiki>]
** [https://forums.scummvm.org/viewtopic.php?t=4639 Using Timidity with ScummVM on Windows XP <nowiki>[forum]</nowiki>]
** [[HOWTO-LoomTG16|How to extract the Loom PC-Engine/TG16 data track to use with ScummVM <nowiki>[wiki]</nowiki>]]
* Supported games:
** [https://www.scummvm.org/compatibility/{{StableVersion}}/ Compatibility table for the latest ScummVM release <nowiki>[website]</nowiki>]
** [https://www.scummvm.org/compatibility/ Compatibility table for the development version of ScummVM <nowiki>[website]</nowiki>]
** [[Engines|List of games that are supported by ScummVM or for which there is a work in progress <nowiki>[wiki]</nowiki>]]
}}

Latest revision as of 19:03, 18 June 2023

Check out our new user documentation!
We have a user documentation portal at docs.scummvm.org. It covers all aspects of using ScummVM, including how to install ScummVM on a variety of platforms, how to add and play games, and how to tweak settings for optimal game play.

Getting Help

  1. ReadMe file for version 2.8.1
    1. Czech translation
    2. German translation
    3. Swedish translation
    4. Danish QuickStart translation
    5. French QuickStart translation
    6. Italian QuickStart translation
    7. Norwegian (bokmaal) QuickStart translation
    8. Spanish QuickStart translation

Appendix

  1. Control Mapping for supported devices
  2. Graphic filters
  3. Tools, a list of the tools available for use with ScummVM (e.g. for compressing audio), along with a description of their usage
  4. Integrations

Links

You will find help on using ScummVM in other places on the web. Here are a few links to solve frequent issues or that my help you improve your experience with ScummVM.

Retrieved from "https://wiki.scummvm.org/index.php?title=User_Manual&oldid=37687"