README

  Aleph One/SDL
  An Open Source 3D action game

  Copyright (C) 1995 Bungie Software Corporation
  Portions Copyright (C) 2000-2005 Christian Bauer, Loren Petrich,
    Chris Pruett, Rhys Hill, Ben Thompson, Woody Zenfell, Mihai Pararita,
    Bo Lindbergh et al.
  Expat XML Library Copyright (C) 1998, 1999 James Clark


License
-------

Aleph One is available under the terms of the GNU General Public License.
See the file "COPYING" that is included in the distribution for details.

The BeOS version of Aleph One is statically linked against SDL which is
provided to you under the terms of the GNU Library General Public License.
See the file "COPYING.SDL" that is included in the distribution for details.
The source code for the version of SDL used is available on

  http://alephone.cebix.net


What is Aleph One?
------------------

Aleph One is an Open Source 3D first-person shooter game, based on the game
Marathon 2 by Bungie Software. It is set in a Sci-Fi universe dominated by
deviant computer AIs and features a well thought-out plot.


System Requirements
-------------------

Aleph One/SDL runs on all Unix systems supported by SDL (which includes
Linux, FreeBSD, Solaris and IRIX), on BeOS R4.5 or later versions, and on
Windows 9x/NT/2000. It does not currently run on MacOS.

Successfully tested systems include:
 - Linux/i386
 - Linux/alpha
 - Linux/x86_64
 - FreeBSD/i386
 - Solaris/sparc
 - BeOS/x86 R5
 - BeOS/ppc R4.5
 - Windows 95
 - Windows 98/SE
 - Windows NT 4
 - Windows 2000

To compile Aleph One/SDL, you need an up-to-date C++ compiler. Using GCC 3.x
should give the best results. Users of pre-ISO C++ compilers need not apply.

Aleph One/SDL supports, but doesn't require, OpenGL for rendering.


Installing Aleph One
--------------------

See the files "INSTALL.Unix", "INSTALL.BeOS" and "INSTALL.Windows".

Aleph One/SDL needs Marathon data files which are not included in the
distribution, so you should read the installation instructions even if
you have downloaded an executable version of Aleph One/SDL.


Playing Aleph One
-----------------

Unix:
  To start Aleph One, type

   $ alephone

  If you have installed the Marathon Demo data RPM packages, start Aleph One
  like this

   $ /usr/share/AlephOne_m2_demo/start
  or
   $ /usr/share/AlephOne_minf_demo/start

BeOS:
  To start Aleph One, double click the "AlephOne" application icon. If you want
  to specify arguments or see error messages, you will have to start it from the
  shell, however.

Windows:
  To start Aleph One, double click the "AlephOne" application icon. If you want
  to specify arguments or see error messages, you will have to start it from an
  MS-DOS window, however.

The program can take a number of command line arguments. Here is a complete
list:

  [-h | --help]          Display the help message
  [-v | --version]       Display the game version
  [-d | --debug]         Allow saving of core files (disable SDL parachute)
  [-f | --fullscreen]    Run the game fullscreen
  [-w | --windowed]      Run the game in a window
  [-g | --nogl]          Do not use OpenGL
  [-s | --nosound]       Do not access the sound card
  [-m | --nogamma]       Disable gamma table effects (menu fades)

If Aleph One complains about missing data files, and you are sure that you
have installed them, try setting the ALEPHONE_DATA environment variable to
the path of the data file directory. This variable can also specify a colon-
separated (Windows: semicolon-separated) list of directories which are
searched for data files in the given order.

The background story of the game and the keyboard controls are explained in
the manual or README file on your Marathon CD or in the Demo archive.
Here is a rundown of the default keyboard configuration (assuming a US
keyboard; all keys are mapped by position):

  On the menu screen:
    N - Begin new game
    O - Continue saved game
    P - Preferences
    R - Replay saved film
    C - Show game credits
    Q - Quit

  In-game:
    KP8     - Walk forward
    KP5     - Walk backward
    KP4     - Turn left
    KP6     - Turn right

    Z       - Sidestep left
    X       - Sidestep right

    D       - Look up
    C       - Look down
    V       - Look ahead

    A       - Glance left
    S       - Glance right

    Space   - Fire weapon, primary trigger
    Alt     - Fire weapon, secondary trigger (e.g. grenades)
    KP7     - Select previous weapon
    KP9     - Select next weapon

    Tab     - Action (open doors, flip switches, log in to computer terminals)

    Shift   - Sidestep
    Ctrl    - Walk slowly/swim
    Meta    - Keyboard look

    M       - Overhead map

  Other keys (not configurable):
    -       - Zoom overhead map out
    =       - Zoom overhead map in

    \       - Toggle FPS display

    Esc     - Quit game/leave terminal
    Alt-Q   - Quit game
    Alt-C   - Quit game (use this under BeOS because Alt-Q will quit
              the whole Aleph One application without warning)
    Alt-P   - Pause game (press Alt-P again to resume)

    F1      - Decrease screen size
    F2      - Increase screen size
    F3      - Toggle high/low resolution
    F4      - Reset OpenGL textures
    F5      - Make the chase cam switch sides
    F6      - Toggle chase cam
    F7      - Toggle tunnel vision
    F8      - Toggle crosshairs
    F9      - Screen dump (saved in ~/.alephone/Screenshot_*.bmp files)
    F10     - Toggle position display
    F11     - Decrease gamma level
    F12     - Increase gamma level

    ,       - Decrease sound volume
    .       - Increase sound volume
    [ and ] - Scroll player inventory view

    Backspace - Switch player view in replays
    [ and ] - Adjust film replay speed

If you click on "Defaults" in the keyboard configuration menu when mouse
control has been turned on you will get a different keyboard layout, more
suited to mouse play.


Playing third-party maps with Aleph One
---------------------------------------

(If the following instructions are too technical for you, see the "Map
installation for dummies" section, below)

Aleph One can be extended with custom map, physics, shape and sound files
which can be selected in the "Environment" section of the preferences menu.
Aleph One/SDL looks for these files in two places:

Unix:
  /usr/local/share/AlephOne
 and
  ~/.alephone

BeOS:
  The Aleph One application directory
 and
  /boot/home/config/settings/Aleph One

Windows:
  The Aleph One application directory
 and
  The directory "Prefs\<user name>" in the Aleph One application directory

Aleph One looks in both of these directories (and in all subdirectories) for
map, shape and sound files it recognizes and shows a list of them in the
"Environment" preferences menu when clicking on one of the "Map", "Physics",
"Shapes" or "Sounds" items. So, for example, under Unix you could create a
directory ~/.alephone/maps and place all map files you downloaded in there.

Most 3rd-party maps for Marathon 2 and Marathon Infinity you can find on the
internet, for example in the Marathon HyperArchive

  http://www.marathon.org/hyperarchive/

do in principle work out-of-the box with Aleph One/SDL. I said "in principle",
because these maps are usually stored in BinHex (.hqx) and/or StuffIt (.sit)
format, which is difficult to unpack on non-Mac systems.

Fortunately, for Linux there is a beta version of "StuffIt Expander" which
can handle such files:

  http://www.aladdinsys.com/expander/expander_linux.html

(when unpacking a ".sit.hqx" archive, you will need to run "unstuff" twice,
first for de-BinHexing and a second time for unstuffing).

The other problem with Marathon map files is that terminal pictures,
chapter screens and chapter screen sounds are stored in the resource fork
on the Mac. If a map doesn't have a resource fork with these things (most
Net maps don't), it is sufficient to just copy the entire map file over
to a place where Aleph One can find it (see above).

If the map does have a resource fork (most single-player maps do), you
have three options:
 a) Extract the data and resource forks into separate files, as I did with
    the map file in the installation instructions above. If the file
    containing the data fork has the name "foo", the resource file must be
    called "foo.rsrc" or "foo.resource" and kept in the same directory as
    the data file. Splitting files into data and resource forks is easy
    to do when copying unpacked files from Mac CD-ROMs (see above) or when
    unpacking downloaded map files under MacOS with my Basilisk II Mac
    emulator (copy the unpacked map to the external file system where the
    resource fork will be stored in a ".rsrc" directory).
 b) Convert the dual-forked Mac map file into a single "AppleSingle" encoded
    file. This is the preferred option because it will combine the data and
    resource forks into a single file which is easier to move around than
    two separate files. The "tools" directory of the Aleph One/SDL source
    archive contains two utilities for handling AppleSingle files.
 c) Convert the dual-forked Mac map file into a single "MacBinary II" encoded
    file. This will also leave you with a single map file. The Linux "unstuff"
    program will produce MacBinary files when giving it the "-m=auto" option.

The shape and sound files don't require special treatment to work under
Aleph One/SDL. Some shape files, however, come in the form of a "patcher"
application that only runs under MacOS. Such files cannot be used with
Aleph One/SDL.


Map installation for dummies under Linux
----------------------------------------

First, download and install the "StuffIt Expander" beta for Linux:

  http://www.aladdinsys.com/expander/expander_linux.html

Now, suppose that you downloaded a file "CoolMap.sit.hqx" which contains
a Marathon 2 or Infinity map.

1. De-BinHex the file:

     $ ls
     CoolMap.sit.hqx
     $ unstuff CoolMap.sit.hqx
     Scanning CoolMap.sit.hqx
     Expanding CoolMap.sit.hqx
     /home/cbauer/downloads/CoolMap.sit ............
     done
     $ ls
     CoolMap.sit   CoolMap.sit.hqx

2. Unstuff the file:

     $ unstuff -m=auto CoolMap.sit
     Scanning CoolMap.sit
     Expanding CoolMap.sit
     /home/cbauer/downloads/Cool Map Folder/Cool Map ............
     /home/cbauer/downloads/Cool Map Folder/Read Me
     done
     $ ls
     'Cool Map Folder/'   CoolMap.sit  CoolMap.sit.hqx
     $ cd "Cool Map Folder"
     $ ls
     'Cool Map'  'Read Me'

   The "Read Me" file may be unreadable but you can ignore it.

3. Copy the map file to the right place:

     $ cp "Cool Map" ~/.alephone

4. The map should now show up in the list when clicking on the "Map" item of
   the Environment preferences section of Aleph One.


Films and saved games
---------------------

Saved games and films are stored in

Unix:
  ~/.alephone/Saved Games
 and
  ~/.alephone/Recordings

BeOS:
  /boot/home/config/settings/Aleph One/Saved Games
 and
  /boot/home/config/settings/Aleph One/Recordings

Windows:
  Directories "Prefs\<user name>\Saved Games" and "Prefs\<user name>\Recordings"
  in the Aleph One application directory

If you want to restore games or replay films you have downloaded (or copied
from another computer), you have to copy them into these directories or
they won't show up when clicking on "Continue Saved Game" or "Replay Saved
Film" on the main menu.


Themes
------

Aleph One/SDL supports selectable user interface themes which determine the
look of the game's dialog boxes (but not the title menu which is a fixed
picture). The themes are stored in

Unix:
  /usr/local/share/AlephOne/Themes
 and
  ~/.alephone/Themes

BeOS:
  The "Themes" directory in the Aleph One application directory
 and
  /boot/home/config/settings/Aleph One/Themes

Windows:
  The "Themes" directory in the Aleph One application directory
 and
  The directory "Prefs\<user name>\Themes" in the Aleph One application
  directory

There is one subdirectory for each theme and you can install new themes by
unpacking them into the "Themes" directory. Additional themes can be found
on the Aleph One/SDL home page (see below).


File compatibility
------------------

This section gives a summary of the cross-platform compatibility of the
various data files used by Aleph One and the original Marathon games:

  "Images" - on Aleph One/SDL this is a data file and not a resource file
    as on the MacOS versions of Aleph One and Marathon, but the file format
    is exactly the same, and compatible across all platforms supported by
    Aleph One/SDL
  "Shapes" - fully compatible across all versions of Aleph One/Marathon 2/
    Marathon Infinity
  "Sounds" - fully compatible across all versions of Aleph One/Marathon 2/
    Marathon Infinity
  Map files - maps without resource forks are fully compatible across all
    versions of Aleph One/Marathon 2/Marathon Infinity; maps with resource
    forks need to be in one of three formats:
      a) data and resource forks in separate files, <name> and <name>.rsrc/
         <name>.resources
      b) an AppleSingle encoded file containing data and resource fork
      c) a MacBinary II encoded file containing data and resource fork
    All of these formats are fully compatible across all platforms supported
    by Aleph One/SDL.
  Saved games - fully compatible across all versions of Aleph One/
    Marathon 2/Marathon Infinity (but the MacOS versions save a small picture
    of the map at the current player's position in the resource fork of
    saved games, which is not preserved or used by Aleph One/SDL)
  Films - fully compatible across all versions of Aleph One/Marathon 2/
    Marathon Infinity
  "Aleph One Preferences" - platform-specific, not compatible with the MacOS
    versions of Aleph One/Marathon nor across the platforms supported by
    Aleph One/SDL
  Themes - fully compatible across all versions of Aleph One/SDL; the MacOS
    versions of Aleph One and Marathon don't support themes


Marathon Markup Language (MML)
------------------------------

The Marathon Markup Language (MML) is a subset of the Extensible Markup
Language (XML). MML scripts can be used to configure some aspects of
Aleph One. These scripts are stored in

Unix:
  /usr/local/share/AlephOne/MML
  /usr/local/share/AlephOne/Scripts
 and
  ~/.alephone/MML

BeOS:
  The "MML" and "Scripts" directories in the Aleph One application directory
 and
  /boot/home/config/settings/Aleph One/MML

Windows:
  The "MML" and "Scripts" directories in the Aleph One application directory
 and
  The directory "Prefs\<user name>\MML" in the Aleph One application
  directory

Upon startup, Aleph One reads and parses all scripts found in these
directories, in alphabetical order. For a description of their contents and
what you can do by writing your own MML scripts, please consult the file
"docs/MML.html" that comes in the Aleph One/SDL distribution archive.


Bug Reports
-----------

If you find a bug that's not already in the list above, please submit it
using the bug database on SourceForge:

  http://sourceforge.net/bugs/?group_id=1997


Tips
----

You can start the game at any level by holding the Shift and Control keys
while clicking on the "Begin New Game" button on the main menu.

To activate the cheat codes, see the file "docs/Cheat_Codes" that is included
in the Aleph One archive. But remember: Winners don't cheat and cheaters
don't usually win! :-)

If you're stuck in the game, there's an excellent walkthrough at

  http://pinky.wtower.com/marathon/


Troubleshooting
---------------

If the game runs very slowly, try running it in 8 bit mode. Under Linux,
using XFree86 4.0 instead of 3.x may also greatly increase the speed. If you
don't have hardware accelerated OpenGL, you should specify the "-g" argument
to enable software rendering (unless you configured Aleph One with the
"--disable-opengl" option). If Aleph One crashes or performs poorly when
using OpenGL, disable the "Static Effect" option in the Graphics/OpenGL
preferences menu.


Support
-------

Aleph One is not officially supported by Bungie Software, so don't bother
contacting them about it.

The official Aleph One home page is at

  http://source.bungie.org/

My home page for the SDL port is at

  http://alephone.cebix.net

The Aleph One pages on SourceForge

  http://www.sourceforge.net/projects/marathon/

provide discussion forums, a database of bugs and feature requests and much
more.

If you have questions about Marathon in general, you should post them to
the established marathon forums, such as alt.games.marathon.


Happy carnage!
Christian Bauer <www.cebix.net>