Alien Arena 2011
                           Version 7.51

1. Scope

This document includes information about the GNU-Linux/Unix
version of Alien Arena 2011.  Custom options and other
information specific to Alien Arena are included here.

For general information, licensing, and contributers, see the
README.txt and license.txt documents (in the docs/ subdirectory
in the distribution archive).

For generic information about installation, see the GNU INSTALL
document.

The Alien Arena HomePage URL is:
  http://red.planetarena.org/
There are links there to the Alien Arena Forum and other helpful
Internet resources.

2. Changes from Previous Versions

This information is for packagers and those who have a previous
installation of Alien Arena.  (If this does not apply to you, it
is safe to skip to the next topic: Installation.)

Version 7.51 has improved performance, bug fixes, plus new and
updated game assets.  Significant changes from Version 7.50 that
are related to building and installing the game are:

  * The Open Dynamics Engine (ODE) is integrated with the main program;
    so libode is no longer a required dependency. But, g++ and libstdc++
    are required to build and link the integrated ODE.
  * A configure option to disable document installation is added.
  * An installation path for the icon, icondir, is added and the icon is
    renamed to alienarena.png.
  * The server terminal may be configured to support color output.

Briefly, important differences in previous Version 7.50 are:

  * Alien Arena 2011 uses a GNU Autotools build and install.
  * The game.so shared library no longer exists.
  * All file writes go to the user's HOME directory.
  * The dedicated server has been renamed to crx-ded.
  * There is an dedicated-server-only build option.
  * There is an "alternate" single directory install option.
  * Additional dependency: Open Dynamics Engine (libode)
    (optional in 7.51).
  * Additional dependency: FreeType 2 (libfreetype).

Warning: The game.so library is no longer a separate module.  If
a game.so file exists in an arena/ or data1/ directory, the
results are "undefined".  Configurable LIBDIR is no longer needed
and is eliminated.

Attempts to write into read-only space when data is installed in
a shared/ directory have been corrected.  Data file access using
a configurable DATADIR is now fully supported.  There is now a
botinfo/ directory in the user's HOME directory.  The default
directory name for Alien Arena data in the HOME directory is
.codered/.  That can be changed using an environment variable,
COR_GAME.

The dedicated server was renamed to simplify program name
translation using the standard configure option.  Also, the
dedicated server is intended to be an integral part of the
package.  We would prefer it not be distributed separately and
there is no particular reason to do so.  There is a configure
option, provided mostly for Game Server Providers, to disable
building the client program.

The standard installation now uses the GNU Autotools methods and
defaults.  In some cases, the "traditional" single directory
install in the user's HOME directory may be preferred.  See the
Alternate Install topic below for details.


3. Installation

Alien Arena uses OpenGL for 3D graphics rendering.  Alien Arena
can be played on many computers.  However, not all computers have
3D acceleration hardware and drivers with adequate performance
for 3D game play.

If you are installing Alien Arena using your distribution's
package manager, follow their instructions.

If you are reading this, you may have already unpacked the
distribution archive (aka, "tarball") into your HOME directory.
Otherwise, the terminal command line for unpacking the archive
is:
  $ tar -xzf alienarena-<some version numbers>.tar.gz
Or, using the graphical file browser, right click on the file
name, and left click on "Extract Here."

If the installation fails, check the error message for required
software packages that may be missing.  Alien Arena uses: X11,
OpenGL, OpenAL 1.1, Ogg-Vorbis, cURL, FreeType2, and JPEG.
Version 7.50 requires Open Dynamic Engine (ODE), but Version 7.51
does not.  For Ubuntu and similar systems, see the topic,
"Getting Required Packages with Synaptic", below.

Using the terminal, change to the alienarena-7.51 directory and
enter these commands:
  $ ./configure
  $ make
  $ sudo make install

For advanced configure options, see the topic, "Custom Configure
Options", below.

To run:
  $ crx

Command line options to crx are NOT standard.  There is NO
"--help".  They follow a format inherited from Alien Arena's
Quake 2 roots.  Command line options are the same as console
commands using a '+' character prefix.  The details are beyond
the scope of this document; but a simple example is:
  $ crx +set maxclients 10

By default, 'sudo make install' will install the game programs
and data like this:

  /usr/local/
    bin/
      crx
      crx-ded  (dedicated server)
    share/
      alienarena/
        arena/
        botinfo/
        data1/
      doc/
        alienarena/
          <various documents>
      icons/
        alienarena.png

When the program is run, a directory is created in the user HOME
directory.  Various kinds of data (config files, downloaded data,
custom bot setups) are written there.  The default directory name
is .codered/.  That can be changed using an environment variable,
COR_GAME.

For example:
  $ export COR_GAME=/home/user/.alienarena

Current settings are stored in .codered/arena/config.cfg.  For
custom settings, create a file, .codered/arena/autoexec.cfg.
Details about settings are beyond the scope of this document.  Go
to the websites, the forum and the IRC channel for more
information.

Following installation, intermediate files generated by the build
may be removed using:

  $ make clean

To uninstall the program and data that 'sudo make install'
installed, run:

  $ sudo make uninstall

The uninstall procedure may not remove all files and directories.
Some manual removal may be required.


4. Getting Required Packages with Synaptic

Tools and packages required to build Alien Arena may not be
installed.  For Ubuntu and similar systems, installing them is
easy with the graphical Synaptic Package Manager.  Select the
following packages.  Other packages that these depend on will be
automatically selected for installation.  This list is based on
Ubuntu 10.10.

  build-essential
  libx11-dev
  libgl1-mesa-dev
  libxxf86vm-dev
  libxxf86dga-dev (optional)
  libopenal-dev
  libjpeg8-dev (or libjpeg62-dev)
  libvorbis-dev
  libcurl4-gnutls-dev
  libode-dev (optional)
  libfreetype6-dev


5. Troubleshooting Tips

When the game exits, it stores settings in config.cfg.  The
default location for this file is /home/<user>/.codered/arena/
(might be in .alienarena rather than .codered).  Sometimes it
helps to delete config.cfg, and then re-enter menu settings.  For
persistent storage of custom settings, create a file named
autoexec.cfg in the same directory as config.cfg.  Settings in
autoexec.cfg will override settings in config.cfg.

If the game does not run smoothly, graphics settings may need to
be adjusted.  Also, a different or updated video driver may be
needed.  Enable the frame rate display in the "Game Options" menu
by setting "display fps" to yes.  There are settings in both the
"Game Options" and "Video Options" sections that affect
performance.  The maximum frame rate is set with the console
variable ("cvar"), cl_maxfps.  Sometimes lowering that from the
default "90" will help.  (Except for local testing, do not set
cl_maxfps higher than 145).  Get more information on the Forum,
Websites, and IRC channel.

If you have errors that output messages about "ODE", setting the
"ragdolls" option to off in the Game Options menu may help.

There are known sound problems related to PulseAudio and OpenAL
on some systems.  Check
/usr/share/doc/libopenal1/examples/alsoftrc.sample.gz
for information on OpenAL configuration.  See the Alien Arena
forum and other support forums for solutions.

The mouse may behave badly (always pointing up, for instance).
This can usually be fixed by setting the console variable (cvar),
in_dgamouse, to zero.  Put this line into the autoexec.cfg file:
  set in_dgamouse "0"
Alternatively, when building the program, use this configure
option:
  --without-xf86dga

For advanced users only (if you do not know what this means, do
not try it): Testing shows that some CFLAGS settings can give a
little performance improvement.  Some to try, depending on system
hardware are:
  * -O3
  * -march=core2
  * -msse or -msse2 or -msse3
  * -fpmath=sse


6. Custom Configure Options

Run '$ ./configure --help' for a list of options.  Note that many
of the options are built-in and some are not meaningful or useful
for Alien Arena.  Options are entered on the command line in the
usual way; the help output has the details.  Refer to the GNU
INSTALL document for general details.

To build the dedicated server only, use the following configure
option:
  --disable-client

By default, configure produces a status message giving
information on the configuration.  To hide that message, use:
  --disable-build-status

To rename the programs, use the standard configure option.  For
example:
  --program-transform-name='s/crx/alienarena/'

To install to a different location, use the standard configure
option.  For example:
  --prefix=/usr/local/games

To specify an installation location for the icon, use the
following option.
  --with-icondir=DIR

To use the system-supplied libode, rather than the integrated
ODE, use this option:
  --with-system-libode
Due to variations in the way libode may be built, this is deemed
an "unsupported" option.  The integrated ODE is built using these
compile options:
  * -DdDOUBLE
  * -DdTRIMESH_ENABLED
  * -DdTRIMESH_OPCODE
  * -DNDEBUG and -DdNODEBUG
Using a libode built with -DdSINGLE makes ragdolls excessively
"raggedy".  Other variations will likely result in program
failure.

To disable installation of documents, use the following option.
  --disable-documents

The server terminal will output color if the following option is
used.  This converts Quake-style color codes to ANSI color
escapes.  (It is not enabled by default because some terminal
configurations may not support ANSI color escapes.)
  --enable-ansi-color

Other Alien Arena custom options are intended mostly for
developer use.  If you use them, it is assumed that you know what
you are doing.


7. Tools

Tools/fuse.tar.gz contains a game server browser.  See documents
in that package for details.

Tools/LinuxScripts contains tools for server management.  See the
README there for details.


8. Alternate Install

This configures the installation to use the "traditional", single
directory, in-place install.  It does not define DATADIR, and the
executables need to be in the top game directory.  Normally, this
install would be done somewhere in your HOME directory.  Root
privileges would not be required to write the game data.
Currently, the configure option for renaming of the executables
is not supported.

If you are a map-builder, you should use this option.  Some
mapping tools may not work with the "standard" install.

If you regularly update to the latest development code from the
Subversion Repository, you may prefer this option.

The two install methods are not mutually exclusive.  With some
care, it is possible to use both.

The configure option is:
  --enable-alternate-install

Following the usual 'make', it requires

  $ make install-alternate

This just copies the executables to the top game directory.  The
effect of using any other 'install' make target is "undefined".