
                       Alien Arena Reloaded
                           Version 7.60.1

BUG FIX UPDATE: 7.60.1 corrects a "stack smashing" bug caused
by a player list buffer overflow in the "Join Server" in-game
browser. Only occurs if some on-line server has a large player
list.


ATTENTION: Build and install for 7.60 has some significant
differences from 7.53.

ATTENTION: The executables are now "alienarena" and "alienarena-
ded", NOT "crx" and "crx-ded".

ATTENTION: Distro packagers: please review installation.  The
standard install for the Unix/Linux supports both read-only data
in a shared directory and writable data in a user's home
directory.  The shared directory is defined at compile time (see
source/Makefile.am) to be exactly "$(pkgdatadir)".  The program
expects the "arena", "botinfo", and "data1" shared subdirectories
to be there.  A configure variable, "ALIENARENA_HOMEDIR", has
been added for customizing the user home directory location at
compile time.  This is in addition to the environment variable,
COR_GAME, for changing the user home directory from the default
".codered"

ATTENTION: Version 7.60 does NOT work with Open Dynamics Engine
(ODE) Version 0.12.

ATTENTION: The configuration default for the DGA library
(Xxf86dga) is now "without".

ATTENTION: The Home Page and Forum have been upgraded.  Home Page
URL is the same.  The Forum URL is not -- see the Home Page for
the new link.


1. Scope

This document includes information about the GNU-Linux/Unix
version of Alien Arena Reloaded.  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.


2. Resources

The Alien Arena Home Page URL is:

  http://red.planetarena.org/

There are links there to the Alien Arena Forum and other helpful
Internet resources.  The Alien Arena IRC (Internet Relay Chat)
channel is now served by:

  irc.planetarena.org

The in-game IRC connects to #alienarena there.

There are web sites with 3rd party maps, skins, etc.  See the
Home Page for links.

There is a Subversion (SVN) repository for Alien Arena.  See the
topic "Getting Alien Arena from SVN" below.

3. Changes for version 7.60

Version 7.60 is "Alien Arena Reloaded."  There are new features
and new maps; see the Home Page for the change log and more info
on those.

The Autotools build used autoconf 2.68, and automake 1.11.5.  The
m4 macros are updated and configure.ac modified accordingly.  The
build and install procedure is mostly the same with some option
changes and additions.  (Note: AM_MAINTAINER_MODE is used. See
"configure.ac".)

As noted above, the install is not the old quake-style.  There
appears to have been some confusion about that, so please review
it.  We apologize for not making that clear (Editors note:
programmers writing user manuals ... not a good idea.)  (If you
like the old ways, see Alternate Install below.)


4. Open Dynamic Engine

The Open Dynamics Engine (ODE) is integrated with the main
program; so libode is, optionally, not required. ODE is written
in c++, so g++ and libstdc++ are required to build and link the
integrated ODE.

As noted above, ODE 0.12 is not compatible with 7.60.  The
preferred approach is to use the integrated ODE.  The system ODE
library may be used if it is version 1.11 or 1.11.1 and if it
uses double precision math. See below for more details.

5. Requirements

Alien Arena uses OpenGL for 3D graphics rendering.  Not all
computers have 3D acceleration hardware and drivers with adequate
performance for 3D game play.  While some systems may perform ok
with open source drivers, a proprietary driver, such as those
from AMD/ATI and NVidia, is often needed.  The Video Settings
menu may be used to override the automatically selected
performance level.

Online performance will vary depending on the network connection
between the client and the server.  Servers with *lower* ping
will usually perform better.

Playing online may require firewall configuration.

These ports are used by the program:
  * UDP 27900 for the master server. Used for getting server list.
  * UDP 27901 for the client.
  * UDP 27902 for account/stats system password validation.
  * UDP 27910 is the default for a server, but is often configured otherwise.
  * TCP 6667 is the default for in-game connection to the IRC channel.

The cURL library is used to retrieve game resources, player
ranking information, and current version information from these
URLs:
  * http://red.planetarena.org/sv_downloadurl
  * http://stats.planetarena.org/playerrank.db
  * http://red.planetarena.org/version/crx_version


6. Installation

If you are installing Alien Arena using your distribution's
package manager, follow their instructions.  Distributions
install the user's configuration in places other than the default
"~/.codered" directory.  This is important if you want to create
the "arena/autoexec.cfg" file to customize your settings.  Search
for "arena/config.cfg" to find the configuration directory.

Two installation alternatives are PlayDeb and Desura.  If using
those, follow their installation procedures.  PlayDeb is at
http://www.playdeb.net/.  Desura is at http://www.desura.com/.

The version available with a distribution or the game
distribution services may not be the latest.

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."  Then follow the
instructions below to build the program.

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.  Some
major distributions have "dev" versions of the libraries that are
needed to build programs.  These are not installed by default, so
you may need to install them using your distributions package
manager.  Version 7.60 does not require the ODE library (it is
integrated).  There is a configure option to use the system ODE
library (see below.)

For Ubuntu and similar systems, see the topic, "Getting Required
Packages with Synaptic", below.

For advanced configure options, see the topic, "Custom Configure
Options", below.  It is not necessary, but it would be a good
idea to take a look at those.

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

To run:
  $ alienarena

In the menu, Single Player will run a simple pre-configured local
game.  For more single player options, go to the Host Server
menu.  Setting "public server" to no will keep your local game
from being broadcast with the master server list.  For
multiplayer, online play, first enter your player name and a
password in the Player Setup menu.  Then go to the Join Server
menu to find a Server.

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

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

  /usr/local/
    bin/
      alienarena
      alienarena-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

This may also be changed using a new (in 7.60) configure
variable, ALIENARENA_HOMEDIR.  It is an environment variable.  It
is relative to the user home directory, NOT the full path.  You
might find it is preferable to use something other than the
hidden ".codered" directory, because downloaded resources are
written into this directory.  Also, 3rd party maps, skins, etc.
are usually put into the "arena" subdirectory in this directory.

For example:
  $ ./configure ALIENARENA_HOMEDIR=my_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.


7. 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 (optional. needed for full screen display)
  libxxf86dga-dev (optional)
  libopenal-dev
  libjpeg8-dev (or libjpeg62-dev)
  libvorbis-dev
  libcurl4-gnutls-dev
  libode-dev (optional. using integrated ODE instead is recommended)
  libfreetype6-dev


8. Notes about Console Variables (cvars)

Version 7.60 adds some console variables.  Details are beyond the
scope of this document.  (Editors note: yeah, sure. Just ran out
of time, didn't ya.)  There are changes and additions to the HUD
display.  Check the forum for more info.  Or ask the friendly
people in the IRC channel.

Alien Arena is based on Quake games.  Many of the cvars are the
same as Quake 2.  More information can be found on the Forum and
on the Web.


9. Troubleshooting and Configuration Tips

When the game program exits, it stores settings in "config.cfg".
The default location for this file is
"/home/<user>/.codered/arena/", but it might be elsewhere
depending on your distribution or configuration.  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 video 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".  Get more information on
the Forum, Websites, and IRC channel.

In the past, there have been sound problems related to PulseAudio
and OpenAL with some versions of those sound drivers.  Check for
for information on OpenAL configuration using "~/.alsoftrc" in
your distributions shared doc directory.

If you have a high resolution mouse, you may need to set the
mouse sensitivity cvar.  The cvar name is "sensitivity" and it
may be set to fractional values between 0.0 and 1.0.  Use the
console to determine the value, then put it in autoexec.cfg.

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"
By default, the program is built "without" DGA, so this only
applies if the following configure option was set.
  --with-xf86dga

For advanced users (if you do not know what this means, it is ok
to ignore it): Testing shows that some CFLAGS settings can give a
little performance improvement.  Add CFLAGS="<put options here>"
to the ./configure command.  Some to try, depending on system
hardware are:
  * -O3 (-O2 is the default)
  *  -march=native
  * -msse, -msse2, -msse3 or other sse options, and -mfpmath=sse
If you modify CFLAGS, you probably also want the "--disable-
silent-rules" configure option.


10. 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/alienarena/alien-arena/'

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
As noted above, Alien Arena is not compatible with ODE version
0.12.  Due to variations in the way libode may be built, this is
may not work.  It may be preferable to use the system library,
however, if it was built with double precision math.  If 'pkg-
config --cflags ode' returns -DdDOUBLE, it is probably safe to
use the system library.  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 libode build 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.


11. 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.


12. 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.  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".


13. Getting Alien Arena from SVN

The repository has the latest development version of Alien Arena.
It contains tools and other resources that are not a part of the
regular distribution.

The SVN repository may be browsed at:

http://svn.icculus.org/alienarena/trunk/

Anonymous read-only checkout is available using this command:

svn co svn://svn.icculus.org/alienarena/trunk alienarena

More information about Subversion may be found at:
http://subversion.apache.org/

