
					 Alien Arena Warriors of Mars
                            Version 7.71.7
							
1. Scope and Introduction

This document includes information about the GNU-Linux/Unix version of
Alien Arena Warriors of Mars. This document applies to the Beta
release of October 14, 2017 and later "Generation 3" versions. This
document does not cover running a dedicated server.

Custom options and other information specific to this version are
included here. For general information, licensing, and contributers,
see the README, COPYING and GPLv2 documents. For generic information
about installation using GNU Autotools: the original GNU INSTALL
document is included at the end of this document.

There are links to the Alien Arena Forum and other helpful Internet
resources on the Alien Arena Homepage:

  red.planetarena.org

The Alien Arena IRC (Internet Relay Chat) channel is served by:

  irc.planetarena.org

The in-game IRC connects to the #alienarena channel there.


2. Requirements

2.1 System Requirements

See README for requirements.

A video adapter with 3D acceleration using the latest proprietary
OpenGL driver is recommended. If you have not previously run a 3D FPS
(First Person Shooter) at playable frame rates, or if you do not know
what this means, you may want to verify your system has adequate 3D
performance before proceeding.

2.2 Installing Tools and Libraries

For the Warriors of Mars Beta, there is no pre-built executable. The
executable is built after extracting the compressed distribution file
using an automated system called GNU Autotools. This system is also
used for installation of executables and data.

But, before that can be done, certain tools and libraries must be
installed. Use your distribution's package manager to install
these. Depending on your distribution, some of these may already be
installed. Some distributions have special development versions that
are not installed by default but are needed to build programs. These
will have a suffix of "-dev" or "-devel". Some example library names
are given below in parentheses. These libraries may depend on other
libraries; the package manager will automatically install those
dependencies.

  * gcc or g++  (the GNU 'c/c++' compiler tools)
  * pkg-config  (a library configuration information tool)

  * X11         (libx11-dev, libX11, libxxf86dga-dev, libxxf86vm-dev, libXxf86vm)
  * OpenGL      (libgl1-mesa-dev, libGL)
  * OpenAL 1.1  (libopenal-dev, libopenal)
  * Ogg-Vorbis, (libogg-dev, libvorbis-dev. libogg, libvorbis, libvorbisfile)
  * cURL,       (libcurl, libcurl4-gnutls-dev)
  * FreeType2   (libfreetype, libfreetype6-dev)
  * JPEG        (libjpeg8-dev, libjpeg8)
  * ZLib        (libz, libz-dev)
  * ODE         (libode, libode-dev)

For Debian-based distributions (such as Ubuntu and Mint), this command
should get all of what you need. Enter it all on one command line.

  $ sudo apt-get install build-essentials libx11-dev libxxf86vm-dev \
    libgl1-mesa-dev libopenal-dev libogg-dev libvorbis-dev \ 
    libcurl4-gnutls-dev libfreetype6-dev libjpeg8-dev libode-dev

3. Building and Installing

3.1 Unpacking the tarball.

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

3.2 Build and Install Commands

Using the terminal, change to the destination directory for the svn
checkout command (normally, ~/alienarena). If required libraries are
missing, the 'configure' command will exit with error messages.

Using the terminal, change to the "alienarena-7.7" directory and
enter these commands:

--- Simple Version ---

The following commands will build and install the program and data
with the default configuration:

  $ ./configure
  $ make
  $ sudo make install

--- Not-so-Simple Version ---

However, for better build and run-time performance, you should use
these commands instead:

  $ export CFLAGS='-march=native -O3 -g -pipe -DNDEBUG'
  $ ./configure
  $ make -jN  (where N is your CPU's number of cores + 1)
  $ sudo make install

If you are familiar with Linux/Unix, the installation may be
customized. For more information, run:

  $ ./configure --help

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

  $ make clean

3.3 Installation Information

By default, 'sudo make install' will install the game programs
and data using this directory hierarchy:

  /usr/local/
    bin/
      alienarena
      alienarena-ded  (dedicated server)
    share/
      alienarena/
        arena/
        data1/
      doc/
        alienarena/
      icons/
        alienarena/

3.4 Uninstall

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

  $ sudo make uninstall

The uninstall procedure does not remove all files and directories.
Some manual removal may be needed. For instance, while files in
/usr/local/share/alienarena are removed, directories are not. Also,
nothing in ~/.local/share/cor-games is automatically removed.


4. Running

4.1 Setup

Use the Menu for setting video configuration and other options.

For the first run, do the following in a terminal:

 $ cd
 $ alienarena

Go to the GAME OPTIONS menu, enter a Player name and password, then
Apply. A name and password is required for online play. Set the other
options to your preferences; details are beyond the scope of this
document.

Then, quit the game using the QUIT GAME menu selection. This is done
to make sure the configuration is created and saved.

Configuration, screen shots, and other data is stored in:

  ~/.local/share/cor-games/arena

Note that this is different from 7.66 and earlier versions of Alien
Arena. For those who know what this means, the location of this
user-writeable directory, ~/.local/share/cor-games, honors
XDG_DATA_HOME.

The file, 'config.cfg', stores the current settings when the game
exits normally. Do not edit this file. For custom settings, create a
file named 'autoexec.cfg'. Visit the Forums for more information on
custom configuration.

Note that with "Generation 3" previous 3rd party and legacy maps are
no longer compatible. If there are 3rd-party maps, they are not
installed as part of the standard installation.  These may be
downloaded and stored in the 'cor-games/arena' subdirectory. When
playing online, maps that you do not have are automatically downloaded
and stored there.

Installation and updates DO NOT alter files in the 'cor-games'
subdirectory.

Files in the 'cor-games' subdirectory have precedence over the
standard files in '/usr/local/share/alienarena'. Normally, this in not
a problem, but sometimes updates or downloads result in obsolete files
in 'cor-games' overriding newer files.

4.2 Normal Operation

To run:
  $ cd	
  $ alienarena

The distribution contains an alienarena.desktop file. You may manually
copy it to ~/.local/share/applications if you want a launch icon.

For more info about running the game, see the README file.

In the menu, PRACTICE OFFLINE 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. If "public server" is set to
"yes" and your network connection is configured to allow it, you will
be running a "listen server" that other players may connect to.

For multiplayer, online play, go to the JOIN SERVER menu to find a
Server. Bots will always show ping of 0. They have some mean sounding,
but amusing, taunts. Do not let it bother you, just frag 'em. They may
attack with the "probe", if you let them get close, watch out!

Command line options to 'alienarena' are NOT standard. 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.

4.3 Special "In-place" Operation

For various reasons (map making, for example), one may want to run the
program using data installed in one's HOME directory, rather than in
/usr/local/. Formerly, this required a special build. That is no
longer the case. Running the program from the directory containing
the data1/ sub-directory will cause the program to use that directory
for data instead of /usr/local/share/alienarena.

For example, assuming the program has been built in ~/alienarena and
installed in /usr/local

To run normally using files in /usr/local/share:

  $ cd
  $ alienarena

To run using the data files in ~/alienarena:

  $ cd ~/alienarena
  $ alienarena

Standard disclaimer: You should do this only if you know what you are
doing.


6. Network Information

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.

Online performance will vary depending on the network connection
between the your computer (the client) and the server. Servers
with *lower* ping are better.

Playing online may require firewall configuration.


7. Troubleshooting

If you encounter problems, first check in the Forums for the latest
information:

  red.planetarena.org/forum

Bug reports are posted in the Support/Bug Reports section. If you are
reporting a new bug, please include information about your system and
the version you are running.


************************************************************************
                              ADDENDUM
------------------------------------------------------------------------
NOTE: This following is a copy of the GNU Document, INSTALL, with
more technical details related to GNU Autotools than the above.
------------------------------------------------------------------------
************************************************************************

Installation Instructions
*************************

Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
2006, 2007, 2008, 2009 Free Software Foundation, Inc.

   Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without warranty of any kind.

Basic Installation
==================

   Briefly, the shell commands `./configure; make; make install' should
configure, build, and install this package.  The following
more-detailed instructions are generic; see the `README' file for
instructions specific to this package.  Some packages provide this
`INSTALL' file but do not implement all of the features documented
below.  The lack of an optional feature in a given package is not
necessarily a bug.  More recommendations for GNU packages can be found
in *note Makefile Conventions: (standards)Makefile Conventions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').

   It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring.  Caching is
disabled by default to prevent problems with accidental use of stale
cache files.

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.

   The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'.  You need `configure.ac' if
you want to change it or regenerate `configure' using a newer version
of `autoconf'.

   The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     Running `configure' might take a while.  While running, it prints
     some messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package, generally using the just-built uninstalled binaries.

  4. Type `make install' to install the programs and any data files and
     documentation.  When installing into a prefix owned by root, it is
     recommended that the package be configured and built as a regular
     user, and only the `make install' phase executed with root
     privileges.

  5. Optionally, type `make installcheck' to repeat any self-tests, but
     this time using the binaries in their final installed location.
     This target does not install anything.  Running this target as a
     regular user, particularly if the prior `make install' required
     root privileges, verifies that the installation completed
     correctly.

  6. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

  7. Often, you can also type `make uninstall' to remove the installed
     files again.  In practice, not all packages have tested that
     uninstallation works correctly, even though it is required by the
     GNU Coding Standards.

------------------------------------------------------------------------
