Initial revision

svn-id: r4785

1 files changed, 560 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000000..dd2a4e1527
--- /dev/null
+++ b/README
@@ -0,0 +1,560 @@
+ScummVM README
+Last updated:    2002-07-08
+Release version: 0.2.2 [CVS]
+------------------------------------------------------------------------
+
+For more information, compatibility lists, details on donating, the latest
+release, progress reports and more, please visit the ScummVM home page
+at: http://scummvm.sourceforge.net/
+
+
+About:
+------
+
+ScummVM is an implementation of the SCUMM (Script Creation Utility for
+Maniac Mansion) engine used in various Lucas Arts games such as Monkey
+Island and Day of the Tentacle. At this time ScummVM should be considered
+ALPHA software, as it's still under heavy development. Be aware that while
+many games will work with few major bugs, crashes can happen. Also note
+that saved games can, and probably will, be incompatible between releases.
+
+Also ScummVM is capable of playing several non-SCUMM games, at the moment
+this includes Simon The Sorcerer.
+
+If you enjoy ScummVM feel free to donate using the PayPal button on the
+ScummVM homepage. This will help us buy utilities needed to develop ScummVM
+easier and quicker. If you cannot donate, help and contribute a patch!
+
+Contacting:
+-----------
+The easiest way to contact the ScummVM team is by subitting bug reports or
+commenting in our forums. You can also join and e-mail the scummvm-devel
+mailing list, or chat with us on irc (#scummvm, irc.openprojects.net)
+
+Supported Games:
+----------------
+
+At the moment the following games have been reported to work, and should
+be playable to the end:
+
+        Loom (256 color CD version)               [Game: loomcd]
+        Zak McKraken (256 color FM Towns version) [Game: zak256]
+        Monkey Island 1 (CD version)              [Game: monkey1]
+        Monkey Island 2                           [Game: monkey2]
+        Indiana Jones And The Fate Of Atlantis    [Game: atlantis]
+        Day Of The Tentacle                       [Game: tentacle]
+        Sam & Max                                 [Game: samnmax]
+        Simon The Sorcerer                        [Game: simon1dos/simon1win]
+
+
+The following games should load, but are not yet fully playable. Play these at
+your own risk, and please do not file bug reports about them. If you want
+the latest updates on game compatibility, visit our web site and view the
+compatibility chart.
+
+        Monkey Island 1 (VGA floppy)                   [Game: monkeyvga]
+        Indiana Jones and the Last Crusade (256 color) [Game: indy3]
+        Full Throttle                                  [Game: ft]
+        The Dig                                        [Game: dig]
+
+The following games are SCUMM engine, but NOT supported by ScummVM (yet).
+
+        Maniac Mansion
+        Zak McKraken (16 color floppy version)
+        Monkey Island 1 (EGA, 16 color floppy version)
+        Loom (16 color floppy version)
+        Curse of Monkey Island
+
+Please be aware that the engine may contains bugs and non-implemented-
+features that sometimes make it impossible to finish the game. Save often,
+and please file a bug report (details on submitted bug reports are below)
+if you discover such a bug.
+
+
+Supported Platforms:
+-------------------
+
+ScummVM has been ported to run on many platforms and operating systems.
+Links to these ports can be found either on the ScummVM web page or by a
+Google search. Many thanks to the effort of porters. If you have a port of
+ScummVM and wish to commit it into the main CVS, feel free to contact us!
+
+        Windows         - SDL
+        Windows CE      - SDL           (iPaq and other handheld devices)
+        Linux           - SDL/X11       (includes iPaq devices running Linux)
+        Macintosh       - SDL/CUSTOM    (Including Classic and Mac OS X)
+        AmigaOS         - SDL/AGA
+        MorphOS         - SDL
+        BeOS            - SDL
+        Acorn (RiscOS)  - ???
+        Dreamcast       - ???
+        UNIX            - SDL           (SDL may work on Solaris, IRIX, *BSD)
+
+Known Bugs:
+-----------
+
+This release has the following known bugs. There is no need to report them,
+although patches to fix them are welcome. If you discover a bug that is not
+listed here, nor in the compatibility table on the web site, please see
+the section on Reporting Bugs.
+
+       Indy 4 (Fate Of Atlantis):
+                - Keyboard fighting does not work. ScummVM now defaults to
+                  using mouse fighting.
+
+
+       Sam and Max:
+                - Subgames are not all fully functional.
+
+                - Conroy singing in Bumpusville may work incorrectly. Eg,
+                  music will overlap and Conroy will get stuck singing. Just
+                  hit escape to skip the cutscene. This is due to SNM using
+                  a different iMUSE implementation to previous games.
+
+
+       Zak McKracken Fm Towns:
+                - The Fm Towns 256 color version of Zak McKracken is rare,
+                  And as the ScummVM team does not encourage piracy in any
+                  way, we do not know where to buy or download a copy of this
+                  game. Petition LucasArts to re-release it :)
+
+                - No music or sound effects yet.
+
+
+       Loom (256 Talkie):
+                - If you are having random crashes, this is a Windows bug.
+                  Try copying the data files from CD to your hard disk.
+
+                - Bobbin may sometimes appear to walk backwards.
+
+
+       Monkey 1 (CD Version):
+                - If you are having random crashes, this is a Windows bug.
+                  Try copying the data files from CD to your hard disk.
+
+
+Reporting Bugs:
+---------------
+To report a bug, please create a SourceForge account and follow the bugs
+link from our homepage. Please make sure the bug is reproducible, and 
+still exists in the latest daily build/current CVS version. Also check the
+compatibility listing for that game to ensure the issue is not already known.
+
+Do NOT report bugs listed as being completable above.
+
+Please include the following information:
+        - Game version (PLEASE test the latest CVS/Daily build)
+        - Bug details, including instructions on reproducing
+        - Language of game (English, German, etc)
+        - Version of game (Talkie, Floppy...)
+        - Platform and Compiler (Win32, Linux, etc)
+        - 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.
+
+
+Compiling:
+----------
+
+You need SDL-1.2.2 or newer (older versions may work, but are unsupported), and
+a supported compiler. Several compilers, including GCC, mingw and Microsoft
+Visual C++ are supported. If you wish to use MP3-compressed CD tracks or
+.SOU files, you will need to install the MAD library and define
+COMPRESSED_SOUND_FILE. Tools for compressing .SOU files to .SO3 files can be
+found in the 'tools' CVS module, or in the 'scummvm-tools' package.
+
+You can also comment/uncomment appropriate lines in the Makefile to use
+sdl_gl.cpp instead of sdl.cpp. This allows hardware accelerated bilinear
+filtering by using OpenGL textures.
+
+On Win9x/NT/XP you can define USE_WINDBG and attach WinDbg to browse debug 
+messages (see http://www.sysinternals.com/ntw2k/freeware/debugview.shtml).
+
+        GCC:
+        * Type make (or gmake if that's what GNU make is called on your
+          system) and hopefully ScummVM will compile for you.
+
+        Microsoft Visual C++:
+        * Open the workspace, scummwm.dsw
+        * Enter the path to the SDL include files in Tools|Options|Directories
+        * Now it should compile successfully.
+
+        BeOS:
+        * Open the 'scummvm.proj' file in BeIDE. Compile as normal.
+
+        PocketPC - Windows CE:
+        * Download the SDLAudio library:
+          http://arisme.free.fr/PocketScumm/sources/SDLAudio-1.2.3-src.zip
+        * Open and compile the SDLAudio WCEBuild/WCEBuild workspace in EVC++
+        * Open the ScummVM wince/PocketScumm workspace
+        * Enter the SDLAudio directory to your includes path
+        * Enter the compiled SDLAudio.lib to your link libraries list
+        * Now it should compile successfully
+
+
+Running:
+--------
+
+Before you run the engine, you need to put the game's datafiles in a
+directory. The filenames must be in lowercase on *nix systems
+(monkey2.000 and monkey2.001). If you use a game with speech, the file
+monster.sou must reside in the same directory as the datafiles.
+
+For example, to run a copy of Monkey Island installed in C:\Games\LucasArts
+under Windows, you would make a shortcut calling this command:
+
+  C:\Games\LucasArts\scummvm.exe -f -pC:\Games\LucasArts\monkey\ monkey
+
+Under BSD, Linux, or similar, the commandline would be:
+  /path/to/scummvm -f -p/games/LucasArts/monkey/ monkey
+
+Or, if you have, for example, Full Throttle on CD, and your CD drive is D:,
+and you wish to disable subtitles and run in fullscreen:
+
+  C:\Games\LucasArts\scummvm.exe -f -n -pD:\resource\ ft
+  /path/to/scummvm -f -n -p/mnt/cdrom/resource/ ft
+
+Note that if you run the game once this way, and specify the -w commandline
+parameter (or edit the config file manually), ScummVM will remember the
+path, and other settings for this game. Documentation on the configuration
+file can be found near the end of this readme.
+
+The short game name you see at the end of the command line is very
+important. A short list is contained at the top of this file. You can also
+get the current list of games and game names at:
+        http://scummvm.sourceforge.net/compatibility.php
+
+For the adventurous, who like to live on the edge... you can download daily
+builds of Win32, Redhat, Debian and other packages here:
+        Daily builds - http://scummvm.sourceforge.net/daily/
+
+
+Command Line Options:
+---------------------
+
+        scummvm [OPTIONS] [GAME]
+
+        [GAME]     - Short name of game to load. E.g. monkey for Monkey Island.
+        
+        -p<path>   - Path to where the game is installed. Default is Cwd.
+        -b<num>    - Start in room <num>.
+        -c<num>    - Drive to play cd audio from.  E.g., 0 is first drive.
+        -s<num>    - Set the sfx volume, 0-255.    Default is '100'
+        -m<num>    - Set the music volume, 0-100.  Default is '60'
+        -t<num>    - Set music tempo. Adlib default: 0x1F0000, Midi: 0x460000
+        -e<mode>   - Select sound engine. See below.
+        -g<mode>   - Select graphics scaler. See below.
+        -f         - Full-screen mode.
+        -n         - Disable subtitles. Use with games that have voice.
+        -y         - Set talk speed ('yak option'). Default is '60'
+        -a         - Enable amiga pal conversion, for playing Amiga versions
+        -d[<num>]  - Set debug verbosity to <num>
+        -w[<file>] - Write configuration file
+        -l<file>   - Load alternate configration file
+
+In game Hot Keys:
+-----------------
+        Ctrl 0-9 and Shift 0-9   - load and save games
+        Ctrl-Alt 1-7             - cycles between graphics filters
+        Ctrl-z OR Alt-x          - quits
+        Ctrl-f                   - runs in fast mode.
+        Ctrl-g                   - runs in really REALLY fast mode.
+        Ctrl-d                   - starts the debugger.
+        Ctrl-s                   - shows memory consumption.
+        [ and ]                  - master volume, down/up
+        - and +                  - text speed, slower / faster
+        F5                       - displays a save/load box.
+        Space                    - pauses
+        Period (.)               - skips current line of text in some games
+        Alt-Enter                - toggles full screen/windowed
+        Enter                    - Left Mouse Button Press
+        Tab                      - Right Mouse Button Press
+        Keyboard Arrow Keys      - Mouse Movement
+
+Note that using ctrl-f and ctrl-g are not recommended: Games can crash when
+being ran faster than their normal speed, as scripts will loose syncronisation
+
+Graphics filters:
+-----------------
+ScummVM offers several anti-aliasing filters to attempt to improve visual
+quality. These are the same filters used in many other emulators, such as
+MAME.
+
+They are:
+        -gnormal     - No filtering, original 320x200 resolution. Fastest.
+        -g2x         - No filtering, double screen/window size to 640x400 (default)
+        -g3x         - No filtering, triple screen/window size to 800x600
+        -g2xsai      - 2xsai filtering, double screen/window size to 640x400
+        -gsuper2xsai - Enhanced 2xsai filtering. 640x400 screen/window size
+        -gsupereagle - Less blurry than 2xsai, but slower. Also 640x400
+        -gadvmame2x  - 640x400 scaling. Doesn't rely on blurring like 2xSAI.
+
+Note that filters are very slow when ScummVM is compiled in a debug
+configuration without optimizations. And there is always a speed impact when
+using any form of anti-aliasing/linear filtering. Also note that the FmTowns
+Zak (zak256 target) uses an original resolution of 320x480 - hence for this
+game scalers will be 640x480 and 960x720.
+
+The alternative to these scalers is to try using the SDL_gl.cpp target. This
+will allow you to use hardware accelerated functions, like bilinear filtering
+and FSAA, on suitable OpenGL capable cards.
+
+Autosaves:
+----------
+
+Because ScummVM is still a beta product, it -can- crash and/or hang
+occasionally. As such, every five minutes it will save a game in Slot 0. This
+game can be loaded via Ctrl-0, or the F5 menu. This autosaving only applies to
+Scumm games, not other games (such as Simon the Sorcerer)
+
+
+Savegames:
+----------
+
+Savegames are by default put in the current directory. You can specify the save
+in the config file by setting the savepath parameter. See the example config
+file later in this readme.
+
+You can also use the environment variable SCUMMVM_SAVEPATH to specify where to
+put save games. Don't forget the trailing directory separator. Also be aware
+that saved games can, and probably WILL, break between ScummVM releases.
+
+Bash (Linux) Example:
+        export SCUMMVM_SAVEPATH=/tmp/scummvm_savegames/
+
+Windows example:
+        set SCUMMVM_SAVEPATH=C:\saved_games\
+
+
+Music and Sound: 
+----------------
+By default, on most operating systems, ScummVM will automatically use ADLIB
+emulation. However, some games do not include Adlib music - such as Sam and
+Max. Note: MIDI may not be available on all operating systems or may need
+manual configuration.
+
+If you ARE using MIDI, you have several different choices of output, 
+depending on your operating system and configuration.
+        
+        -eadlib     - Uses internal Adlib Emulation (default) 
+        -ewindows   - Windows MIDI. Uses built-in sequencer, for Windows users
+        -emidiemu   - Emulated midi music, for Sam and Max (BETA - BUGGY)
+        -eseq       - Uses /dev/sequencer for MIDI, *nix users. See below.
+        -eqt        - Quicktime sound, for Macintosh users.
+        -ecore      - CoreAudio sound, for MacOS X users.
+        -eamidi     - Uses the MorphOS MIDI system, for MorphOS users
+        -ealsa      - Output using ALSA sequencer device. See below.
+        -enull      - Null output. Don't play any music.
+        
+
+Playing sound with Adlib emulation:
+-----------------------------------
+By default an Adlib card will be emulated and ScummVM will output the music
+as sampled waves. This is the default mode for most games, and offers the
+best compatability between machines and games. However, Sam and Max does not
+include Adlib emulation.
+
+
+Playing sound with MIDI emulation:
+----------------------------------
+Until recently, some games (particually Sam and Max) were only able to run
+in MIDI mode. This prevented music for these games from working on platforms
+that do not support MIDI, or soundcards that do not provide MIDI drivers (eg,
+many soundcards will not play MIDI under Linux). We have recently added an
+'emulated MIDI' technology. It can be accessed using the 'midiemu' option,
+and is the default for Sam and Max on UNIX platforms. -HOWEVER-, it is still
+very buggy and the emulation is not perfect. If you are capable of using
+native midi, we recommend using one of the MIDI modes below, or Adlib if
+your game includes music in the appropriate format.
+
+
+Playing sound with Native MIDI:
+-------------------------------
+Use the appropriate -e<mode> command line option from the list above to
+select your preferred MIDI device. For example, if you wish to use the
+Windows MIDI driver, use the -ewindows option.
+
+
+Playing sound with Sequencer MIDI:              [UNIX ONLY]
+----------------------------------
+If your soundcard driver supports a sequencer, you may set the environment
+variable "SCUMMVM_MIDI" to your sequencer device - eg, /dev/sequencer
+
+If you have problems with not hearing audio in this configuration, it is
+possible you will need to set the "SCUMMVM_MIDIPORT" variable to 1 or 2. This
+selects the port on the selected sequencer to use. Then start scummvm with the
+-eseq parameter. This should work on several cards, and may offer better
+performance and quality than Adlib or MIDI emulation. However, for those
+systems where sequencer support does not work, you can always fall back on
+either of those methods.
+
+
+Playing sound with ALSA sequencer:              [UNIX ONLY]
+----------------------------------
+If you have installed the ALSA driver with the sequencer support, then
+set the environment variable "SCUMMVM_PORT" to your sequencer port - eg 65:0
+
+Here is a little howto on how to use the ALSA sequencer with your soundcard.
+In all cases, to have a list of all the sequencer ports you have, try the
+command "aconnect -o -l". On my system it gives me the output:
+client 64: 'External MIDI 0' [type=kernel]
+    0 'MIDI 0-0        '
+client 65: 'Emu10k1 WaveTable' [type=kernel]
+    0 'Emu10k1 Port 0  '
+    1 'Emu10k1 Port 1  '
+    2 'Emu10k1 Port 2  '
+    3 'Emu10k1 Port 3  '
+client 128: 'Client-128' [type=user]
+    0 'TiMidity port 0 '
+    1 'TiMidity port 1 '
+
+It means the external MIDI output of my sound card is located on the
+port 64:0, that I've got four WaveTable MIDI outputs in 65:0, 65:1, 65:2
+and 65:3, and that I've got two TiMidity ports, located at 128:0 and 128:1.
+
+If you have a FM-chip on your card, like the SB16, then you have to load
+the soundfonts using the sbiload software. Example:
+  sbiload -p 65:0 /etc/std.o3 /etc/drums.o3
+
+If you have a WaveTable capable sound card, you have to load a sbk or sf2
+soundfont using the sfxload software. If you manage to do so, please mail
+me since I managed to get it working only once, and never again.
+
+If you don't have a MIDI capable soundcard, or if you want to take
+advantage of your TiMidity samples, then you can ask TiMidity to become an
+alsa sequencer output. Here is a quick way to do so:
+  timidity -iAqqq -B2,8 -Os1S -s 44100 &
+
+Then the TiMidity port will be visible from the 'aconnect -o -l' list. You
+should launch it beeing as root, since it will try to set up some real time
+priority.
+
+
+Using MP3 files for CD audio:
+-----------------------------
+Use LAME or some other mp3 encoder to rip the cd audio tracks to files. Name
+the files track1.mp3 track2.mp3 etc. ScummVM must be compiled with MAD support
+to use this option. You'll need to rip the file from the CD as a WAV file,
+then encode the MP3 files in Constant Bit Rate sampled at 22 kHz. This can
+be done with the following LAME command line:
+
+lame -t -q 0 -b 96 --resample 22.05 track1.wav track1.mp3
+
+
+Compressing MONSTER.SOU with MP3:.
+---------------------------------
+You need LAME, and our extract util from the tools dir to perform this task,
+and ScummVM must be compiled with MAD support.
+
+Make a backup file of your MONSTER.SOU before attempting this. Copy your
+MONSTER.SOU file to a temporary folder. Then run:
+  extract monster.sou
+
+In about 30 minutes or so, you will have a much smaller monster.so3 file,
+copy this file to your game dir. You can safely remove the monter.sou file.
+
+
+Coding style:
+------------
+For ScummVM coding, we use hugging braces, and two-space tab indents.
+We occasionally run the following 'indent' parameters to ensure everything
+is kept standard:
+
+-br -bap -nbc -lp -ce -cdw -brs -nbad -nbc -npsl -nip -ts2 -ncs -nbs
+-npcs -nbap -Tbyte -Tvoid -Tuint32 -Tuint8 -Tuint16 -Tint -Tint8
+-Tint16 -Tint32 -TArrayHeader -TMemBlkHeader -TVerbSlot -TObjectData
+-TImageHeader -TRoomHeader -TCodeHeader -TResHdr -TBompHeader
+-TMidiChannelAdl -TGui -TScumm -TSoundEngine -TPart -TPlayer
+
+
+Configuration file:
+-------------------
+By default, the configuration file is saved in, and loaded from:
+
+        Windows: <windir>\scummvm.ini,
+        Linux:   ~/.scummvmrc
+        Others:  scummvm.ini in the current directory
+
+An example config file is as follows:
+
+        [scummvm]
+        gfx_mode=supereagle
+        fullscreen=true
+        savepath=C:\saves\
+
+        [tentacle]
+        path=C:\tentacle\
+        nosubtitles=true
+        master_volume=98
+        music_volume=40
+        sfx_volume=255
+
+        [loomcd]
+        cdrom=1
+        path=C:\loom\
+        talkspeed=55
+        
+        [monkey2]
+        path=C:\amiga_mi2\
+        music_driver=windows
+        amiga=true
+
+
+
+Credits:
+--------
+ The core ScummVM team:
+        James Brown        - Current lead developer, ScummVM
+        Vincent Hamm       - Developer, ScummVM (inactive)
+        Max Horn           - Developer, ScummVM, MacOS X port, new GUI
+        Jeremy Newman      - Webmaster
+        Ludvig Strigeus    - Original developer, Scumm and SimonVM. (Retired)
+
+ Porters:
+        Lionel Ulmer       - X11/Linux port
+        Nicolas Bacca      - PocketPC/WinCE port
+        Mutwin Kraus       - MacOS Carbon port (Retired)
+        Marcus Comstedt    - Dreamcast port
+        Ruediger Hanke     - MorphOS port
+
+ Contributors:
+        Claudio Matsuoka   - Daily Linux/BeOS builds (http://scummvm.sf.net/daily/)
+        Travis Howell      - Daily Win32 builds
+        Janne Huttunen     - V3 actor mask support, Dig/FT SMUSH audio
+        Jeroen Janssen     - Numerous readability and bugfix patches
+        Gregory Montoir    - AdvanceMAME Scale-2X implementation
+        Mikesch Nepomuk    - MI1 VGA Floppy patches.
+        Edward Rudd        - Fixes for playing MP3 versions of MI1/Loom Audio
+        Daniel Schepler    - Final MI1 CD music support
+        Tim 'realmz'       - Initial MI1 CD music support
+        Jonathan 'khalek'  - Expert weaver in the Loom
+        Nicolas Noble      - Config file and ALSA support
+        Pawel Kolodziejski - Added missing Dig SMUSH codecs
+        Felix Jakschitsc   - His hard work on Zak256
+        Andre Souza        - SDL-based OpenGL renderer
+        Kovacs Endre Janos - Several fixes for Simon1
+        Ralph Brorsen      - Helped write the new GUI
+
+        And to all the contributors, users, and beta testers we've missed.
+        Thanks!
+
+ Special thanks to:
+        Sander Buskens  - For his work on the initial reversing of Monkey2
+        Jimmi Thogersen - For ScummRev, and much obscure code/documentation
+        Kevin Carnes    - For Scumm16, the basis of ScummVM older gfx codecs
+
+        Aric Wilmunder, Ron Gilbert, David Fox, Vince Lee, and all those at
+        LucasFilm/LucasArts who made SCUMM the insane mess to reimplement
+        that it is today. Feel free to drop us a line and tell us what you
+        think, guys!
+
+
+
+
+------------------------------------------------------------------------
+Good Luck and Happy Adventuring!
+The ScummVM team.
+http://scummvm.sourceforge.net/
+------------------------------------------------------------------------