
				    BZFlag 2.0.0
				 http://BZFlag.org/
			Copyright (c) 1993 - 2005 Tim Riker

Maintainer
=========

Tim Riker <Tim@Rikers.org>
http://rikers.org/

Author
======

Chris Schoeneman
475 Hawthorne Av
Palo Alto, CA 94301
crs23@bigfoot.com


Introduction
============

This is the readme file for the BZFlag source tree.  It includes a
manifest, simple build instructions, and other information for BZFlag
development.


Getting BZFlag
==============

The home page provides access to the primary BZFlag download site.
This web site includes pages for downloading the compiled and source
code versions.  Compiled versions are distributed as installable
packages.  Source code is archived in various formats.  After
unpacking you should have the following files in the new bzflag
directory:

  README	- this file
  README.*	- platform specific details
  BUGS		- a list of known bugs
  BZFlag.xcode  - Mac OS X XCode project
  ChangeLog	- history of changes
  COPYING	- the license for BZFlag
  NEWS		- placeholder - see ChangeLog
  DEVINFO       - information for developers
  PORTING	- a guide for porting BZFlag
  RELNOTES	- placeholder - see ChangeLog
  TODO		- incomplete list of things to do
  data/		- data files (sounds, images, etc.)
  debian/	- debian apt files
  doc/		- partial documentation in doxygen format
  include/	- include headers for libraries
  man/		- man pages
  misc/		- miscellaneous goo
  package/	- stuff to build installable packages
  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
    geometry/	  - geometry rendering classes
    mediafile/	  - classes for reading resources
    net/	  - networking classes and functions
    obstacle/	  - collision detection stuff
    ogl/	  - OpenGL utility classes
    platform/	  - platform dependent code
      MacOSX/       - Mac OS X specific files, including PB project
    scene/	  - high level rendering algorithms
    zlib/	  - compression library
  tools/	- various helper utilities
  win32/	- extra stuff for building on win32 platforms


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

To build sources checked out directly from CVS you need to create a
configure script. You can skip this step if you grab an archive that
already has a ./configure script in it. Create the ./configure script
by running these commands inside the CVS directory:

  % aclocal
  % autoheader
  % automake --add-missing
  % autoconf

These commands are in the autogen.sh file, so you can just run that
script.  (again this is only required to create the configure script
which might already be present)

  % sh autogen.sh

Now that you have a configure script, create a work directory parallel
to the one you just downloaded and autoconfigured:

  % mkdir ../work

Go in this new directory and build:

  % cd ../work
  % ../bzflag/configure
  % make

bzflag looks for data files in a compiled in path or in ./data/
only. This means that to test in a working directory you need to tell
bzflag where to find these files.  This can be done with a symlink:

  % ln -s ../bzflag/data .

After testing you can install BZFlag by:

  % make install

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

If you have not 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.
E.g.:
../bzflag/configure --prefix=YourHomeDirectoryHere
At "make install" all bzflag exe files will be installed in the subdir bin of
the specified path.
If your exe is too big to you, and you don't need debugger information, run
make install-strip
instead of just make install; this will remove any debug information from the
binaries, and make those shorter.

For additional information on installing, see INSTALL file.

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

  Platform			README file
  --------			-----------
  UNIX, Linux			README.UNIX
  IRIX				README.IRIX
  Solaris			README.SOLARIS
  Mac OS X			README.MacOSX
  Windows 95/98/NT		README.WIN32, 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
CVS.

To build BZFlag for an unsupported platform, see PORTING.

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


Mailing Lists
=============

There are two BZFlag mailing lists, a user list and a developer's
list.  The former is for general BZFlag discussion and announcements.
The latter is for coding and development discussion only.

To join a mailing list, go to http://BZFlag.org/email-list.html/ and
follow the info there.

Contributions
=============

Patches should be entered into the patch tracking system on
http://sourceforge.net/projects/bzflag/ If you like you may also send
mail to either the BZFlag development mailing list, or Tim@Rikers.org
(the development mailing list is preferred) to discuss contributions to
the official BZFlag source code.  Small changes can be attached to the
mail in 'cvs diff -u' unified diff format.


Bug Reports
===========

For bug reports please go to bug tracking system on
http://sourceforge.net/projects/bzflag/ Alternatively, you can email
bug reports to Tim@Rikers.org but the web based method is preferred.


Known Bugs
==========

See BUGS.


Contributors
============

see AUTHORS


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

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.


UDP added by Frank Siegert, frank@this.net, frank@bzflag.de

BZFlag implements UDP unicast relay networking. This provides much
better timing and stability compared to just TCP.

UDP does not work, why?

- 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?

Two possibilities:

a) you are behind a NAT router that is not forwarding UDP traffic to
   your system. Try reconfiguring the router to do NAT on UDP packets.

b) you are behind a firewall or a desktop firewall (e.g. ZoneAlarm)
   that is blocking incoming UDP traffic. Please reconfigure the
   firewall or disable ZoneAlert for the game, for more intelligent
   desktop firewalls set them up to let UDP port 17200 to 17220
   through.

