BZFlag 2.4.2
			 http://BZFlag.org/
		Copyright (c) 1993-2013 Tim Riker

BZFlag is an Open Source OpenGL multiplayer multiplatform Battle Zone
capture the Flag game.  At its heart, the game is a 3D first person
tank simulation where opposing teams battle for dominance.  The game
was originally written for SGI computers running Irix, but now runs
and is actively maintained on Windows, Linux, Mac OS X, BSD, Solaris,
and other platforms.  The game is distributed under the LGPL license.

This is the BZFlag README file.  This file includes introductory build
instructions, user community interaction references, information for
getting involved in BZFlag development, a manifest of the source code
layout, basic usage expectations, contact information, and more.


Table of Contents
=================
    Introduction
    Table of Contents
    Obtaining BZFlag
    Compiling and Installation
	Short Version
	Long Version
    Communication
	Internet Relay Chat
	Mailing Lists
	Bulletin Boards
	Wiki
    Bug Reports and Support
    Providing Contributions
    Source Tree Organization
    Frequently Asked Questions
    Notes on "CHEAT" servers and network abuse
    Project History and Contributions
    Contact


Obtaining BZFlag
================

Main BZFlag Website:  http://BZFlag.org
BZFlag Github Site:  https://github.com/BZFlag-Dev/bzflag

The main BZFlag website provides access to most all of the resources
available for the game.  The binary and source distributions of BZFlag
are, however, provided on the SourceForge project site.  Compiled
versions are distributed as installable packages, disk images, and
more, with details varying depending on the platform.  Source code
distributions are provided and archived in various formats as well.
See the project site for the download links.

BZFlag is also available directly from GitHub.  To obtain BZFlag from
git, a bit more familiarity with software development is expected.
If you're familiar enough, anonymous GIT access is provided from the
repository:

     https://github.com/BZFlag-Dev/bzflag.git


Compiling and Installation
==========================

To compile a playable BZFlag, the following steps should get you up
and running quickly if everything external to BZFlag is properly
installed:

    ./autogen.sh
    ./configure
    make
    ./src/bzflag/bzflag

If configure detected everything it needed to build the BZFlag client,
after make the client will be sitting in src/bzflag as 'bzflag'.  The
game can be run from there, though you will probably want to "sudo
make install" or otherwise become a privileged user and install the
game properly for your system.

If you're building on a platform that has a README.* file, you should
consult that file as they usually contain additional instructions or
details specific for building on that platform.  There are often hints
for common problems specific to those platforms as well.

The Longer Version:

To build sources checked out directly from SVN you need to create a
configure script. You can skip this step if you grab an distribution
of BZFlag that already has a ./configure script in it, such as from a
source distribution tarball.  To generate the configure script, you
run the provided autogen.sh script:

  % sh autogen.sh

The script will report whether sufficient versions of the GNU Build
System tools (i.e. autoconf, automake, and libtool) that were detected
and if successful, a configure script will be generated.  If the
script fails, submit a report to the developers containing the output
of "sh autogen.sh -v". This will run autogen.sh in verbose mode.  One
of the most common failures is having insufficient versions or
mismatched combinations of the GNU Build System tools, so make sure
your tools are recent.

If the previous step was successful you now have a script for
configuring BZFlag.  This command:

  % ./configure --help

will list the variety of configuration options.  The script adapts
well to various system configurations, so it may be enough to simply
run it as:

  % ./configure

You may want to create a 'work' directory and configure from there to
have all the build products and binary executables get placed in a
directory separate from the sources.  To do this, simply create a
directory then run configure and make from there instead.

After configure completes, it will report whether all the requisite
packages were found that it needs in order to build the client and the
server.  The client is reliant upon the following external
dependencies that should be installed before running configure:

  OpenGL 1.0+
  libSDL 1.2+

If you're on an operating system that uses a packaging system
(e.g. apt, portage, ports, etc), be sure to install the development
kit versions of each of those (e.g. xlibmesa-gl-dev package) so that
headers are made available.  You may also want to manually install
other dependencies that BZFlag automatically provides if you do not
have them pre-installed:

  c-ares
  GLEW
  libCURL
  libregex (usually provided as part of libc)
  zlib

The README.Linux file includes a detailed list of of the packages
needed to compile and run BZFlag on some popular Linux distributions.

The final summary at the end of running configure will report whether
the client will be built or not.  Once configure has been run, you may
compile by simply running 'make'.  If you have GNU Make and are on a
multiprocessor system, you can build in parallel with the -j option:

  % make -j4

If compilation was successful, the client will be in src/bzflag and
the server will be in src/bzfs as 'bzflag' and 'bzfs' respectively.
You can run the client or the server directly from those locations
with or without installing:

  % src/bzflag/bzflag

BZFlag looks for data files in a path defined during compile, in
./data/ , or in the previously specified data path only.  As part of
the tarball/git clone, the base data library is located in
<installed-locale>/bzflag/data.  This means that to test in a working
directory you need to tell bzflag where to find these files if there
is not a 'data' directory in your current directory.  This can be done
with a symbolic link:

  % ln -s ./path/to/bzflag/data

After testing you can install BZFlag by running 'make install' with
sufficient system installation privileges.  Use 'sudo', 'su', or
similar methods to elevate your privileges when installing BZFlag
system-wide:

  % sudo make install

You should now have BZFlag in the system directory ready to run.

If you do not have admin privileges on your platform, you can install
files in a directory that you own; for this to work, you have to
append to the configure command the prefix option:

  % ./configure --prefix=YourHomeDirectoryHere

You will then be able to perform a "make install" without needing to
elevate your privileges, and all bzflag executable files will be
installed in the subdir bin of the specified path.

For additional information on installing, see INSTALL file.

Again, some platforms may be different.  See the README file
appropriate to your system for more information:

  Platform			README file
  --------			-----------
  UNIX, Linux			README
  IRIX				README.IRIX
  Solaris			README.SOLARIS
  Mac OS X			README.MacOSX
  Windows XP and up		README.WINDOWS, README.MINGW32


You can also build an installable package using:

  % make package

The package will be placed in ./dist; the exact form of the package
depends on the platform.

There are three cleanup targets: clean, distclean, and
maintainer-clean.

`make clean' removes intermediate files but leaves bzflag and other
programs and any man pages.

`make distclean' removes everything clean does and also programs and
man pages. This should get things back to a tarball state.

`make maintainer-clean' removes everything distclean does and also
packages, directories created during the build, and the platform
configuration; this should get the source tree back to its state in
SVN.

To build BZFlag for an unsupported platform, see PORTING.

The ./configure script has a number of build options that you may find
interesting.


Communication
=============

The BZFlag project has several resources set up for communicating both
with other developers and with the community.  There is an IRC
channel, several mailing lists, bulletin boards, and a wiki.

Internet Relay Chat
-------------------
Most of the BZFlag development activity and discussions occur over
IRC.  Join the #bzflag IRC channel on the Freenode network
(irc.freenode.net, port 6667) to get involved.

See http://webchat.freenode.net for a web based interface for
first-time users.  Individuals that intend to stay in the channel are
expected to get a non-web-based IRC client.  See http://irchelp.org or
search the web for IRC clients for your operating system.

Mailing Lists
-------------
There are several BZFlag mailing lists, but the two of particular
interest to most are the user's list and the main developer's list.
The former is for general BZFlag discussion and announcements.  The
latter is for coding and development discussion only.  There are also
lists dedicated to SVN activity, league discussions, and server
administration.

To join a mailing list, go to the SourceForge mailing list page on the
project site: http://sourceforge.net/p/bzflag/mailman/ and follow
the links for joining the respective mailing lists that interest you.

Bulletin Boards
---------------
There are extensive and active bulletin boards used by players, server
operators, administrators, and others available here:

http://forums.bzflag.org

Registering an account on the bulletin board presently also registers
your callsign for use inside of BZFlag.  Some servers require
registration in order to play.  See the board FAQ and Getting Started
pages for new users.

Wiki
----
The main BZFlag website contains a wiki that may be edited by the
community available at: http://wiki.bzflag.org

The wiki does require a simple registration in order to make
modifications as a means to minimize abuse, but serves as a
communication forum and ongoing discussion arena for the game's
development.


Bug Reports and Support
=======================

For reporting bugs and unexpected behavior, please go to BZFlag bug
tracking system at:

https://github.com/BZFlag-Dev/bzflag/issues

If you require assistance with some issue, please visit the bzflag
IRC channel at:
#bzflag at IRC.freenode.net

Alternatively, discussion forums, and mailing lists
are also viable avenues for resolving issues.


Providing Contributions
=======================

Pull Requests should be entered submitted via the GitHub pull system:

https://github.com/BZFlag-Dev/bzflag/pulls

Contributions are gladly accepted for modifications that do not
affect the core gameplay.  Interacting with the other developers in
the IRC channel is recommended for any changes which will affect
gameplay.


Source Tree Organization
========================

After unpacking a source distribution, you should have at least the
following files in the new 'bzflag' directory:

  README	- this file
  README.*	- platform specific details
  AUTHORS	- project contributors
  COPYING	- the license for BZFlag
  ChangeLog	- source code changes since previous release
  DEVINFO       - information for developers
  NEWS		- history of visible changes for each release
  PORTING	- a guide for porting BZFlag
  autogen.sh	- build system preparation script
  configure.ac	- build system configuration script template
  data/		- data files (sounds, images, etc.)
  doc/		- partial documentation in Doxygen format
  include/	- include headers for libraries
  man/		- man pages
  misc/		- miscellaneous goo
  MSVC/	- stuff for building on the Windows platform
  package/	- stuff to build installable packages
  plugins/	- bzfs plugins
  src/		- bzflag, bzfs, etc. source code
    3D/		  - 3D code including texture manager
    bzadmin/      - bzadmin app source code (text admin/chat client)
    bzflag/	  - bzflag app source code (game client)
    bzfs/	  - bzfs app source code (game server)
    common/	  - general purpose classes
    date/         - unified version and build date stamping for apps
    game/	  - game library used by both the server and client(s)
    geometry/	  - geometry rendering classes
    mediafile/	  - classes for reading resources
    net/	  - networking classes and functions
    obstacle/	  - collision detection stuff
    ogl/	  - OpenGL utility classes
    other/	  - Third-party libraries
    platform/	  - platform dependent code
      MacOSX/       - Mac OS X specific files
    scene/	  - high level rendering algorithms
  tools/	- various helper utilities
  Xcode	        - Mac OS X Xcode project and associated files

Note that include/ does not have all the include files.  If a header
is used entirely within a library (i.e. it doesn't directly provide
functionality outside the library) then the header is found in the
library's directory under src/.  An include file goes in include/ only
if it's required by another library or libraries or executables.
While this complicates locating a header file (it can be in one of two
places instead of just one place), you can instantly tell if a header
file is (can be) used by clients of the library.


Frequently Asked Questions
==========================

- When I connect to a newer server with this client others report they
  can see me but I get 'black caps' after a few seconds for all other
  players?

BZFlag requires both TCP and UDP unicast relay networking for most
servers.  Make sure that your router and any configured firewall is
forwarding UDP traffic over the port you are connecting to on the
server.

- Every now and then the client seems to randomly crash.  Is there
  anything that can be done about it?

There are LOTS of reasons why the client might crash and unfortunately
no means to readily diagnose the cause without developer tools.  You
can try to disable the 'Lighting' option in the menu, which is a known
cause of issues on some platforms (e.g. Mac OS X).  Otherwise, please
report the issue and, if possible, provide a stack trace of the crash
(these are auto-generated for Windows and Mac OS X platforms).

Public Internet Servers and the "list server"
=============================================

The bzflag project offers a public server listing service that allows
players to find servers to play on. This service is run for the
benefit of the project. As of Version 2.4, BZFLS servers that wish to
be listed on the public list server must provide an authentication key
that ties the server to a specific global user. This is done to
provide contact information for players and project
staff. Authentication keys are automatically generated at
http://my.bzflag.org/listkeys/

Notes on "CHEAT" servers and network abuse
==========================================

While the license for BZFlag certainly allows users to run any server
modification that they wish or to modify the code in any way, we ask
that people do not publish or host "cheat" clients or servers to the
general public for use.  We also expect that users will abide by basic
usage guidelines of reasonable and tolerable behavior that are not
detrimental to the game's heritage of a fun gaming environment for
all.

We understand the desire to expand, modify, and improve the game and
its sources including the ability to test out new features publicly.
These modified clients and servers generally provide some advantage
over unmodified clients and are generally discouraged for widespread
use.  As such, we ask that anyone wishing to host or otherwise
participate in a game that involves a modified client or server to
register under a different network protocol than the current public
release by modifying BZ_PROTO_VERSION in the src/date/buildDate.cxx
file.  This will let modified games be played and prevent modified
clients from being used on public unmodified servers.

Any individuals that are found to be contributing to abuse of the
public services being provided may be subject to bans or other access
restrictions.  Abuse generally consists of any disruption to one of
BZFlag's network services including denial of service attacks,
spamming of BZFlag web sites or servers, disruptive gameplay on
multiple public servers, intrusion attempts, password sniffing, or any
other behavior that is deemed inappropriate.

The BZFlag project administrators reserve the right to remove public
listings of any game servers for any reason whatsoever, including
removal of servers or banning of individuals that do not follow this
request.  Similarly, the BZFlag project administrators also reserve
the right to limit access or otherwise block any players from public
service access at any time.  These actions may include the suspension
or removal of global accounts and limiting access to the web site
services including web site services, list server access, bulletin
board forum access, and any league resources.

In general, the entire network is provided by the community for the
community as an entirely volunteer and contributed effort.  We ask
that all players recognize and respect the time, effort, and resources
involved and that we're all generally here to have a good time.


Project History and Contributions
=================================

BZFlag was primarily originally authored by Chris Schoeneman
<crs23@bigfoot.com> in the early 1990's.  After several years of
development, Chris turned over copyright and maintainership of the
game to Tim Riker.

BZFlag continues today to be maintained and developed by the Open
Source community by a project administration team with contributions coming
in from all over the world.  See the AUTHORS file for more details on
contributions to the project.


Contact
=======

Any of the core developers listed in the AUTHORS file are generally
receptive to being contacted for most matters relating to the game.
Internet Relay Chat (IRC) or e-mail is generally the expected method
of interaction with IRC being generally preferred.  The project
maintainer Tim Riker <Tim@Rikers.org> is available for most legal matters,
but day to day development is handled by the Project Administrators:

Jeff Myers (JeffM2501) <JeffM2501@users.sourceforge.net>
Scott Wichser (blast007) <blast007@users.sourceforge.net>

Happy Shooting!
The BZFlag Development Team