Thanks for downloading the third alpha release of FreeSCI!

FreeSCI is a portable interpreter for SCI games, such as the Space Quest
series (starting with SQ3) or Leisure Suit Larry (2 and sequels); see
below for a complete (?) listing.

FreeSCI is still incomplete. You should be able to finish some SCI games with
it, though- the list of games below contains information about games that
were completed.
This release has the following limitations (plus some bugs):
- Only SCI0 games are supported
- The SCI debug functions aren't fully supported (and probably never will be,
  since we're using our own debug functions)
- Sound is only supported on systems that support sequencer or raw MIDI output

It has the following improvements over Sierra SCI:
- Support for various filters and extended drawing operations for graphics
- saving and restoring the game state is possible from more places than the
  Sierra SCI engine allowed (using the debugger functions)
- Better debugger (we believe :-)
- More portable
- It's Free software :-)


This is ALPHA sofware. That means that there still are lot of bugs. Also, sound
support is still missing from this release.


Please refer to 'NEWS' and the 'ChangeLog' for information about changes
in this and previous versions. Please also refer to the following files for
platform specific instructions:

README.Unix
README.Win32


0 Building FreeSCI
==================

To build the package, type the following:

0. ./configure

1. make


This will try to build several tools:
src/tools/sciconsole - A command console for inspection of SCI data
src/tools/scidisasm - Disassembles all script resources into .script files
src/tools/sciunpack - A tool for unpacking and converting SCI resource data
		      (now also contains the functionality of the old
		       'classes', 'listwords', 'scriptdump' and 'vocabdump'
		       tools)
src/sciv - The main executable; this loads, links and runs SCI bytecode.

For graphics, you will need at least one of the following:
* An Xlib implementation for the X11 Windowing System,  as shipped with most
  UNIX systems and VMS
* libggi (http://www.ggi-project.org)
* libsdl (http://www.libsdl.org)

To install it on your system (globally), run 'make install'. You will need
to have superuser privileges to do this, unless you specified a different
installation prefix while running 'configure'.


0.1 Bulding from CVS
--------------------
If you are using a CVS snapshot instead of an official release, you will
require the following utilities:

* A C compiler (such as gcc)
* lex or flex
* GNU automake and autoconf
* perl 5.x
* make

Instructions:

0. Get the source tarball and unpack it.

1. Go into the freesci directory and run the reconf script. (./reconf) 

2. Run the configure script. (./configure)

3. Run make. Be sure that /usr/ccs/bin is in your path AFTER /usr/local/bin 
and everything else.


1 Running it on UNIX-like OSses
===============================

After FreeSCI has been built, you should have all of the tools listed in
section 0, and the main program (src/sciv). Usually, you will want to
run the main program; there are three ways to run a game with FreeSCI
now:

a) You can enter the directory your game is contained in, and just start
'sciv'. If no parameters are given, it will look for data files in the
current working directory.

b) Run 'sciv' with the -d parameter to specify the path to your resource
file directory

c) First build a configuration file, then run 'sciv' followed by one of
the game names described in the config file. The process of creating a
config file is outlined in section 2.


Please note that the default options are rather spartanic; if your machine
is sufficiently powerful, you might want to spice up your graphics. How
this can be done is described in section 2; we also provide a reference
configuration file (called 'config') for high-quality graphics.



1.1 The built-in debugger
-------------------------

If a script error is encountered or you explicitly activate it, the built-
in debugger will activate and execution of the game scripts will cease
until resumed.

Here are two of the most simple commands:
- 'quit'- Terminates execution of the interpretet
- 'go'- resumes execution of the game scripts

For a list of all commands supported by the debugger, type "list cmds" at
the debugger command line. Use "man <command>" to learn about the specified
command.



2 Configuration
===============

FreeSCI will create a directory called .freesci in your home directory (unless
this directory already exists). If you run an SCI game, this game will
create another directory inside the .freesci directory, to store
its save games in (later on).
(On UNIX systems, the home directory is whatever is contained in your HOME
environment variable; on Win32 systems, it is the directory pointed to by
the WINDIR environment variable.
Also, if a file called "config" exists in this directory, it will be read
and parsed by the interpreter after the game has been loaded; this file may be
used to specify a variety of configuration options.

Currently, the configuration file may contain:

- Comments preceeded by a hash '#' sign

- [GAME_ID]: Commands following this line will only have an effect for
  the game with the specified game ID. (The game ID is printed during
  sciv startup, and is also used to create the save game directory).
  You can use this to provide game-specific configuration options.

- console_log: Specifies a console log file which keeps track of all output
  print with the function sciprintf().

- version = x.yyy.zzz: emulate SCI version x.yyy.zzz. The version number
  is sometimes printed on game discs, or can be found out by
  grepping your main executable for "0.000." (for SCI0 games). It is
  also displayed if the built-in debugger is activated in the Sierra SCI
  engine.

- pic0_dither_mode = dither | flat | dither256: (only one of those three modes).
  dither: Draw in 16 colors, same as Sierra SCI.
  flat: Interpolate colors (256 colors). Improves some graphics.
  dither256: Dither in 256 colors. A compromise between dither and flat.

- pic0_dither_pattern = scaled | unscaled
  scaled: Dither in axb sized blocks, if x scale is a and y scale is b
  unscaled: Dither in 1x1 blocks (single pixels)

- pic0_brush_mode = scaled | ellipses | random-ellipses | more-random
  Affects how semi-random brushes (used mostly for dirt and foilage) are drawn:
  scaled: Scale every semi-random pixel to a rectangular block
  ellipses: Scale every semi-random pixel to a filled ellipse
  random-ellipses: As ellipses, but slightly shift ellipse offset and size
  more-random: Add more random pixels to the whole area

- pic0_line_mode = correct | fine | half
  correct: Draw lines appropriately scaled
  fine: Don't scale lines (thin lines, may cause problems) 
  half: Draw them at approximately half their correct width (only noticeable
        with scaling factors from 3 upwards)

- dirty_strategy = 1 | clusters
  The "dirty strategy" is the strategy used to collect modifications to the
  screen content. Modifying this may affect performance on slow or networked
  systems.
  1: Collect everything in one dirty region
  clusters: Cluster non-overlapping modified regions into a set of regions 

- pic0_scaled = yes | no
  Whether SCI0 background pics should be scaled (may look better) or not
  (faster, looks more like the original games). By default, they are not scaled.

- pic_buffer_size = #
  Number of background pics to store in an LRU buffer. Increasing this value
  will increase the amount of memory used, but may considerably speed up
  changing back to rooms you visited not too long ago.

- mouse = yes | no
  Whether the interpreter should report to the game that it has a mouse.

- resource_dir: Read the game's resource data from the specified location.
  Must not be used in the generic part of the config file.

-- NEW OPTIONS since the 0.3.1 release --

- view_filter = none | linear | trilinear
  Magnification filter for 'views', i.e. moving foreground (and, in some cases,
  non-moving background) images. 'none' means that they are translated into
  what may look like a huge chunk of colored rectangles; 'linear' smoothes
  those rectangles somewhat. 'trilinear' does more sensible filtering by
  applying an almost-standard trilinear filtering algorithm.
  This has no effect if graphics are not scaled.

- pic_filter = none | linear | trilinear
  Selects the filter to use when scaling background pictures. This only applies
  if pic0_scale is set to 'no'.
  Please refer to the documentation of "view_filter" for details on the various
  settings.

- cursor_filter = none | linear | trilinear
  Filter for the mouse cursor. Note that this only applies for graphics drivers
  which don't implement their own mouse cursor.
  Please refer to the documentation of "view_filter" for details on the various
  settings.

- text_filter = none | linear | trilinear
  Filter for text.
  Please refer to the documentation of "view_filter" for details on the various
  settings.

- pic_antialiasing = none | simple
  Performs antialiasing on background pictures. Default is 'none'.
  + 'simple' is a trivial anti-aliasing algorithm which calculates intensity
    according to the following matrix:
    (1/16 1/8 1/16)
    (1/8  1/4  1/8)
    (1/16 1/8 1/16)

- animation_delay: A speed factor for transition animations. Default is 5.
  Set to 0 to disable transition animations.

- animation_granularity: If transition animations are too slow on your system,
  this option can be used to draw several steps of a transition animation
  before updating the screen, resulting in a faster animation. The default is 4,
  which causes transition behaviour identical to FreeSCI 0.3.1.

- alpha_threshold: A value between 0 and 255 (defaults to 129) used by the
  built-in crossblitter to distinguish between "opaque" and "transparent"
  pixels. This only has any effect if pixmap filtering is enabled for any
  resource type.
  Smaller values will cause fewer parts of the picture to be displayed,
  which may result e.g. in text being unreadable, while larger values may
  cause too many pixels to be drawn, resulting in bulky images.
  This does not have any effect when running unscaled.

- midi_device:  The equivalent of what sound driver you select in a SCI
  game.  For example, MT-32, Adlib, etc.  Currently, 'mt32' and 'mt32gm'
  are the only options.  (the latter is a GM mapping of the MT32 driver)
  If you have none of the above, leave it set to 'mt32gm' (default)

- midiout_driver:  If you elected to use a "real" midi device (eg the
  MT32 or a General MIDI synth), set this to 'unixraw' or 'alsaraw' if
  you have it connected to your PC's MIDI port.  If you have no MIDI
  devices, 'null' is also valid, and it sends all data to /dev/null.
  Finally, you can use 'ossseq', which uses the OSS /dev/sequencer.
  Which is the default.  :)

- sound_server:  FreeSCI has different ways to handle the concurrent processing
  of sound output. They are:
  * sdl: A threaded SDL sound server
  * unix: A forked-off sound server
  Generally, the sdl sound server (default) should provide better performance,
  if available.


2.1 Driver-specific options
---------------------------
Graphics and sound drivers may have additional options specific to them.
Driver-specific options are set by writing

	<subsystem>.<driver>.<option> = <value>

For example, you would use

	gfx.ggi.swap_caps_ctrl = true

to activate the GGI driver's feature for swapping CapsLock and the left Ctrl
key.

All driver-specific options are listed here:

2.1.1 Graphics subsystem
------------------------
This subsystem uses the prefix 'gfx'.

2.1.1.1 GGI driver:
-------------------
At this time, the GGI driver does not have any specific configuration options.

2.1.1.2 Xlib driver:
--------------------
- disable_shmem = true | false
disables shmem x11 access (meaningless if XShm support wasn't compiled in).

2.1.1.3 SDL driver:
-------------------
- swap_caps_ctrl = true | false
Determines whether to swap the meanings of the CapsLock and the left Ctrl
key (relative to a PC-style keyboard layout). The resulting layout resembles
a Sun keyboard. Default is 'false'.
- fullscreen = true | false
kinda self-explanatory, eh?  :)

2.1.2 Midiout subsystem
-----------------------
This subsystem is responsible for addressing the sound hardware. Its prefix is
'midiout'.

2.1.2.1 ALSARaw driver:
-----------------------
This driver (driver ID 'alsaraw') passes output through to ALSA's raw MIDI output
devices.

Options:
- card: The sound card number to use. Defaults to 0.
- device: The sound device within the card to use. Default 0.

2.1.2.2 UNIXRaw driver:
-----------------------
This driver (ID 'unixraw') handles output to the traditional /dev/midi* devices,
such as those provided by OSS/Free.

Options:
- device: The device file to use for output (defaults to /dev/midi00)

2.1.2.3 OSSseq driver:
----------------------
The OSS sequencer driver ('ossseq') issues MIDI commands to /dev/sequencer. It
can be used to address a variety of sound hardware, including many synthesizer
chips (such as the EMU8k or EMU10k). If you don't have an external MIDI device,
this is most likely what you want to use.

Options:
- device: Number of the sequencer device to address (defauls to '1'). Try
  altering this value if you can't hear anything.
- recorder: Allows to record the events sent to /dev/sequencer, plus a
  preceeding 0-byte. Useful for debugging.

2.1.2.4 Win32 MCI driver:
-----------------------
This driver (ID 'win32mci') handles output to MCI MIDI Output devices in
Windows 95/98/NT4/2000. 

Options:
- device: MCI Device number (as output my FreeSCI during initialization).
  This defaults to the last MCI MIDIout device found in the system, but
  can be set in the config file using "midiout.win32mci.device = x". 
 

2.2 Config file example:
------------------------
# FreeSCI config file

version = 0.000.685
pic0_dither_mode = flat
pic_antialiasing = simple
text_filter = trilinear
midiout.alsaraw.card = 1
midiout.alsaraw.device = 2

# default to interpolated color mode and interpreter version 0.000.685

[Glory]

pic0_dither_mode = dither256
# Quest for Glory looks better in that mode
pic0_brush_mode = morerandom

resource_dir = /usr/local/share/freesci/qg1

[SQ3]

version = 0.000.453
# This SQ3 version is ancient
resource_dir = /home/bob/stuff/misc/other/games/more/sierra/old/sq/3
-----------------------


3 Potentially supported games
=============================

The following games have been tested with FreeSCI and are known to work to some
extent:
+ Hero's Quest / Quest for Glory 1
  (Completed by Emmanuel Jeandel with a post- 0.3.1 development snapshot)
+ Space Quest 3
  (completed by Jason Cragg with a post- 0.3.0 development snapshot)
- King's Quest 4
- Leisure Suit Larry 2
+ Leisure Suit Larry 3
  (Completed by Christina Mengert and Micheal Solberg with a post- 0.3.1
   development snapshot)
- Police Quest 2
- Codename: Iceman
- The Colonel's Bequest
- Conquest of Camelot
- The Fun Seeker's Guide (from the SQ Collector's Series)
- Hoyle's Book of Games (volume 1) (*)
- Hoyle's Book of Games (volume 2)

In theory, FreeSCI should be able to let you complete all of these.

(*) Due to differences between the way Sierra SCI and FreeSCI handle graphical
widgets, Hoyle's Book of Games may consume a lot of memory rather quickly. We
are hoping to resolve these issues at least partially before the next release.


4 Platform support
==================

Successful builds for the 0.3.2 release were reported for the following
platforms (in order of appearance):
- Alpha EV67/Debian GNU/Linux/gcc		tested extensively
- Alpha EV67/Debian GNU/Linux/ccc		tested
- IA32/SuSE 6.3 Linux/gcc			tested
- IA32/Windows 9x/NT/2k/Visual C++              tested
- Sparc/Sun/Solaris/gcc				tested
- Alpha EV6/Compaq/Tru64/cc			built
- Alpha EV6//FreeBSD/gcc			built
- IA64/GNU/Linux64/gcc				built
- IA32//FreeBSD/gcc				built
- IA32//NetBSD/gcc				built

The following platform used to be supported, but no longer is:

- ia32/DOS (no maintainer)
	This port is orphaned.


5 Notes
=======

Please note that most of the documentation found in the doc/misc subdirectory
is random information copied from the SCI Decoding Project homepage and
from homepages of various of its members.
Some of the source code contained in the doc/ directory, namely sd.c, sde.c,
sdv.c, script.java and decrypt.c, was created by Carl Muckenhoupt who has
given permission for it or parts of it to be ported and/or included in this
distribution.
Other source code, such as scr000.txt and scr_code.cpp, was copied from public
sources without the knowledge of its authors.

In order to do something useful, you need all of the resource files of any
SCI0 game in your current working directory before running one of the programs
from this package. These resource files and everything they contain are
property and copyrighted by Sierra On-Line (which in turn is a registerd
trademark of Sierra On-Line, Inc.).
Space Quest, Quest for Glory, King's Quest, Leisure Suit Larry, Police Quest,
Codename: Iceman, Conquest of Camelot, and The Colonel's Bequest are registered
trademarks of Sierra On-Line, Inc.



