This wiki is archived and useful information is being migrated to the main bzflag.org website

Difference between revisions of "BZFlag README"

From BZFlagWiki
Jump to: navigation, search
m (README moved to BZFlag README: Wierd linking if the file was just called README)
(update)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<pre>
 
<pre>
    BZFlag 2.0.8
+
    BZFlag 2.4.10
 
http://BZFlag.org/
 
http://BZFlag.org/
Copyright (c) 1993 - 2006 Tim Riker
+
Copyright (c) 1993-2017 Tim Riker
 
+
Maintainer
+
==========
+
 
+
Tim Riker <Tim@Rikers.org>
+
http://rikers.org/
+
 
+
Original Author
+
===============
+
 
+
Chris Schoeneman
+
475 Hawthorne Av
+
Palo Alto, CA 94301
+
crs23@bigfoot.com
+
 
+
See the AUTHORS file for more authorship details.
+
 
+
 
+
Introduction
+
============
+
  
 
BZFlag is an Open Source OpenGL multiplayer multiplatform Battle Zone
 
BZFlag is an Open Source OpenGL multiplayer multiplatform Battle Zone
Line 28: Line 8:
 
tank simulation where opposing teams battle for dominance.  The game
 
tank simulation where opposing teams battle for dominance.  The game
 
was originally written for SGI computers running Irix, but now runs
 
was originally written for SGI computers running Irix, but now runs
and is actively maintained on Windows, Linux, Mac OS X, BSD, Solaris,
+
and is actively maintained on Windows, Linux, Mac OS X, and other
and other platforms. The game is distributed under the LGPL license.
+
platforms.
 +
 
 +
BZFlag may be redistributed under either the LGPL or MPL licenses.
 +
 
 +
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.
 +
 
  
This is the BZFlag README file.  It includes simple build
+
Table of Contents
instructions, user community references, other information for BZFlag
+
=================
development, and a manifest of the source code layout.
+
    Introduction
 +
    Table of Contents
 +
    Obtaining BZFlag
 +
    Compiling and Installation
 +
Short Version
 +
Long Version
 +
    Communication
 +
Internet Relay Chat
 +
Forums
 +
Wiki
 +
    Bug Reports and Support
 +
    Providing Contributions
 +
    Source Tree Organization
 +
    Public Internet Servers and the "list server"
 +
    Notes on "CHEAT" servers and network abuse
 +
    Project History and Contributions
 +
    Contact
  
  
Line 40: Line 44:
  
 
Main BZFlag Website:  http://BZFlag.org
 
Main BZFlag Website:  http://BZFlag.org
BZFlag Project Site:  http://sf.net/projects/bzflag
+
BZFlag Github Site:  https://github.com/BZFlag-Dev/bzflag
  
 
The main BZFlag website provides access to most all of the resources
 
The main BZFlag website provides access to most all of the resources
 
available for the game.  The binary and source distributions of BZFlag
 
available for the game.  The binary and source distributions of BZFlag
are, however, provided on the Sourceforge project site.  Compiled
+
are, however, provided on the GitHub project site.  Compiled versions
versions are distributed as installable packages, disk images, and
+
are distributed as installable packages, disk images, and more, with
more, with details varying depending on the platform.  Source code
+
details varying depending on the platform.  Source code distributions
distributions are provided and archived in various formats as well.
+
are provided and archived in various formats as well. See the project
See the project site for the download links.
+
site for the download links.
  
BZFlag is also available directly from CVS.  To obtain BZflag from
+
BZFlag is also available directly from GitHub.  To obtain BZFlag from
CVS, a bit more familiarity with software development is expected.
+
git, a bit more familiarity with software development is expected.
Sometimes active BZFlag development is on CVS HEAD, sometimes it is on
+
If you're familiar enough, anonymous GIT access is provided from the
a branch, sometimes it's in multiple places.  Inquire on the #bzflag
+
repository:
IRC channel on irc.freenode.net or to the bzflag-dev mailing list as
+
to where the current development activity resides.  If you're familiar
+
enough, anonymous CVS access is provided:
+
  
    cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/bzflag login
+
  https://github.com/BZFlag-Dev/bzflag.git
[ press return for no password ]
+
    cvs -z3 -d:pserver:anonymous@cvs.sf.net co -P bzflag
+
  
  
Line 70: Line 69:
 
installed:
 
installed:
  
    ./autogen.sh
+
  ./autogen.sh
    ./configure --enable-optimized
+
  ./configure
    make
+
  make
    ./src/bzflag/bzflag
+
  ./src/bzflag/bzflag
  
 
If configure detected everything it needed to build the BZFlag client,
 
If configure detected everything it needed to build the BZFlag client,
Line 88: Line 87:
 
The Longer Version:
 
The Longer Version:
  
To build sources checked out directly from CVS you need to create a
+
To build sources directly from a git clone you need to create a
configure script. You can skip this step if you grab an distribution
+
configure script. You can skip this step if you grab a distribution of
of BZFlag that already has a ./configure script in it, such as from a
+
BZFlag that already has a ./configure script in it, such as from a
 
source distribution tarball.  To generate the configure script, you
 
source distribution tarball.  To generate the configure script, you
run the provided autogen.sh script:
+
need to run the provided autogen.sh script:
  
   % sh autogen.sh
+
   ./autogen.sh
  
 
The script will report whether sufficient versions of the GNU Build
 
The script will report whether sufficient versions of the GNU Build
Line 100: Line 99:
 
and if successful, a configure script will be generated.  If the
 
and if successful, a configure script will be generated.  If the
 
script fails, submit a report to the developers containing the output
 
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
+
of "sh autogen.sh -v". This will run autogen.sh in verbose mode.  One
the most common failures is having insufficient versions or mismatched
+
of the most common failures is having insufficient versions or
combinations of the GNU Build System tools, make sure your tools are
+
mismatched combinations of the GNU Build System tools, so make sure
recent.
+
your tools are recent.
  
Now that you have a configure script and presuming the previous step
+
If the previous step was successful you now have a script for
was successful, you can configure BZFlag:
+
configuring BZFlag.  This command:
  
   % ./configure --help
+
   ./configure --help
  
There are a variety of options possible when configuring BZFlagMost
+
will list the variety of configuration options.  The script adapts
notably, you'll probably want to use the --enable-optimized option for
+
well to various system configurations, so it may be enough to simply
performance and the --enable-shared option if you are building server
+
run it as:
plugins.
+
  
   % ./configure --enable-optimized --enable-shared
+
   ./configure
  
 
You may want to create a 'work' directory and configure from there to
 
You may want to create a 'work' directory and configure from there to
Line 129: Line 127:
 
   OpenGL 1.0+
 
   OpenGL 1.0+
 
   libSDL 1.2+
 
   libSDL 1.2+
  libCURL 7+
 
  
If you're on an operating sytem that uses a packaging system
+
If you're on an operating system that uses a packaging system
 
(e.g. apt, portage, ports, etc), be sure to install the development
 
(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
 
kit versions of each of those (e.g. xlibmesa-gl-dev package) so that
headers are made available.
+
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
 +
  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 final summary at the end of running configure will report whether
Line 141: Line 148:
 
multiprocessor system, you can build in parallel with the -j option:
 
multiprocessor system, you can build in parallel with the -j option:
  
   % make -j4
+
   make -j4
  
 
If compilation was successful, the client will be in src/bzflag and
 
If compilation was successful, the client will be in src/bzflag and
Line 148: Line 155:
 
with or without installing:
 
with or without installing:
  
   % src/bzflag/bzflag
+
   src/bzflag/bzflag
  
BZFlag looks for data files in a path defined during compile, in ./data/ ,
+
BZFlag looks for data files in a path defined during compile, in
or in the previously specified data path only.  As part of the tarball/cvs
+
./data/ , or in the previously specified data path only.  As part of
checkout, the base data library is located in <installed-locale>/bzflag/data.  
+
the tarball/git clone, the base data library is located in
This means that to test in a working directory you need to tell bzflag  
+
<installed-locale>/bzflag/data. This means that to test in a working
where to find these files if there is not a 'data' directory in your current
+
directory you need to tell bzflag where to find these files if there
directory.  This can be done with a symlink:
+
is not a 'data' directory in your current directory.  This can be done
 +
with a symbolic link:
  
   % ln -s ./path/to/bzflag/data
+
   ln -s ./path/to/bzflag/data
  
 
After testing you can install BZFlag by running 'make install' with
 
After testing you can install BZFlag by running 'make install' with
Line 164: Line 172:
 
system-wide:
 
system-wide:
  
   % sudo make install
+
   sudo make install
  
 
You should now have BZFlag in the system directory ready to run.
 
You should now have BZFlag in the system directory ready to run.
Line 172: Line 180:
 
append to the configure command the prefix option:
 
append to the configure command the prefix option:
  
   % ./configure --prefix=YourHomeDirectoryHere
+
   ./configure --prefix=YourHomeDirectoryHere
  
 
You will then be able to perform a "make install" without needing to
 
You will then be able to perform a "make install" without needing to
Line 181: Line 189:
  
 
Again, some platforms may be different.  See the README file
 
Again, some platforms may be different.  See the README file
appropriate to your system for more information:
+
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, README.DEVC++
+
 
+
  
 
You can also build an installable package using:
 
You can also build an installable package using:
  
   % make package
+
   make package
  
 
The package will be placed in ./dist; the exact form of the package
 
The package will be placed in ./dist; the exact form of the package
Line 211: Line 210:
 
packages, directories created during the build, and the platform
 
packages, directories created during the build, and the platform
 
configuration; this should get the source tree back to its state in
 
configuration; this should get the source tree back to its state in
CVS.
+
the Git repository.
  
 
To build BZFlag for an unsupported platform, see PORTING.
 
To build BZFlag for an unsupported platform, see PORTING.
Line 224: Line 223:
 
The BZFlag project has several resources set up for communicating both
 
The BZFlag project has several resources set up for communicating both
 
with other developers and with the community.  There is an IRC
 
with other developers and with the community.  There is an IRC
channel, several mailing lists, bulletin boards, and a wiki.
+
channel, forums, and a wiki.
  
 
Internet Relay Chat
 
Internet Relay Chat
Line 232: Line 231:
 
(irc.freenode.net, port 6667) to get involved.
 
(irc.freenode.net, port 6667) to get involved.
  
See http://irc.bzflag.org for a web based interface for first-time
+
See https://webchat.freenode.net for a web based interface for
users.  Individuals that intend to stay in the channel are expected to
+
first-time users.  Individuals that intend to stay in the channel are
get a non-web-based IRC client.  See http://irchelp.org or search the
+
expected to get a non-web-based IRC client.  See http://irchelp.org or
web for IRC clients for your operating system.
+
search the web for IRC clients for your operating system.
  
Mailing Lists
+
Forums
-------------
+
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 CVS 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/mail/?group_id=3248 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
+
There are extensive and active forums used by players, server
 
operators, administrators, and others available here:
 
operators, administrators, and others available here:
  
http://my.bzflag.org/bb/
+
https://forums.bzflag.org
  
Registering an account on the bulletin board presently also registers
+
Registering an account on the forums presently also registers your callsign
your callsign for use inside of BZFlag.  Some servers require
+
for use inside of BZFlag.  Some servers require registration in order to
registration in order to play.  See the board FAQ and Getting Started
+
play.  See the board FAQ and wiki getting Started pages for new users.
pages for new users.
+
 
+
In addition to the main bulletin boards, there are forums on the
+
Sourceforge project site available here:
+
 
+
http://sourceforge.net/forum/?group_id=3248
+
 
+
The main bulletin boards are considerably higher volume for day-to-day
+
player discussions.  The forums are often used for informally
+
resolving issues with new users.
+
  
 
Wiki
 
Wiki
 
----
 
----
 
The main BZFlag website contains a wiki that may be edited by the
 
The main BZFlag website contains a wiki that may be edited by the
community available at: http://BZFlag.org/wiki
+
community available at: https://wiki.bzflag.org
  
 
The wiki does require a simple registration in order to make
 
The wiki does require a simple registration in order to make
Line 280: Line 256:
 
communication forum and ongoing discussion arena for the game's
 
communication forum and ongoing discussion arena for the game's
 
development.
 
development.
 
 
Contributions
 
=============
 
 
Patches should be entered into the BZFlag patch tracking system at:
 
 
http://sourceforge.net/tracker/?group_id=3248&atid=303248
 
 
Patches are preferred in the unified diff format.  From a CVS
 
checkout, a unified diff patch file may be created as follows:
 
 
  % cvs diff -u > patch.diff
 
 
If you like, you may also send mail to either the BZFlag development
 
mailing list or to Tim@Rikers.org (the development mailing list is
 
preferred) to discuss contributions to the official BZFlag source
 
code.  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.
 
  
  
Line 309: Line 264:
 
tracking system at:
 
tracking system at:
  
http://sourceforge.net/tracker/?group_id=3248&atid=103248
+
https://github.com/BZFlag-Dev/bzflag/issues
  
Alternatively, you can email bug reports to the development mailing
+
If you require assistance with some issue, please visit the BZFlag
list or to Tim@Rikers.org but the web based method is preferred.  See
+
IRC channel at #bzflag at irc.freenode.net
the BUGS file in the source distribution for other known issues.
+
  
If you require assistance with some issue, please visit BZFlag support
+
Alternatively, discussion forums are also available for resolving issues.
tracking system at:
+
  
http://sourceforge.net/tracker/?group_id=3248&atid=203248
 
  
Alternatively, the IRC channel, discussion forums, and mailing lists
+
Providing Contributions
are also viable avenues for resolving issues.
+
=======================
  
 +
Pull Requests should be entered submitted via the GitHub pull system:
  
Contributors
+
https://github.com/BZFlag-Dev/bzflag/pulls
============
+
  
BZFlag has a long history of development and considerable community
+
Contributions are gladly accepted for modifications that do not
involvement since it became an Open Source projectSee the AUTHORS
+
affect the core gameplayInteracting with the other developers in
file for more details.
+
the IRC channel is recommended for any changes which will affect
 +
gameplay.
  
  
Line 335: Line 288:
 
========================
 
========================
  
After unpacking a source distribution, you should have the following
+
After unpacking a source distribution, you should have at least the
files in the new 'bzflag' directory:
+
following files in the new 'bzflag' directory:
  
 
   README - this file
 
   README - this file
 
   README.* - platform specific details
 
   README.* - platform specific details
   BUGS - a list of known bugs
+
   AUTHORS - project contributors
  BZFlag.xcode  - Mac OS X XCode project
+
  ChangeLog - source code changes since previous release
+
 
   COPYING - the license for BZFlag
 
   COPYING - the license for BZFlag
   NEWS - history of visible changes for each release
+
   ChangeLog - source code changes since previous release
 
   DEVINFO      - information for developers
 
   DEVINFO      - information for developers
 +
  NEWS - history of visible changes for each release
 
   PORTING - a guide for porting BZFlag
 
   PORTING - a guide for porting BZFlag
   RELNOTES - placeholder - see NEWS
+
   autogen.sh - build system preparation script
   TODO - incomplete list of things to do
+
   configure.ac - build system configuration script template
 
   data/ - data files (sounds, images, etc.)
 
   data/ - data files (sounds, images, etc.)
  debian/ - debian apt files
 
  Dev-C++/ - Dev-C++ project files
 
  doc/ - partial documentation in doxygen format
 
 
   include/ - include headers for libraries
 
   include/ - include headers for libraries
 
   man/ - man pages
 
   man/ - man pages
 
   misc/ - miscellaneous goo
 
   misc/ - miscellaneous goo
 +
  MSVC/ - stuff for building on the Windows platform
 
   package/ - stuff to build installable packages
 
   package/ - stuff to build installable packages
 +
  plugins/ - bzfs plugins
 
   src/ - bzflag, bzfs, etc. source code
 
   src/ - bzflag, bzfs, etc. source code
 
     3D/   - 3D code including texture manager
 
     3D/   - 3D code including texture manager
Line 363: Line 314:
 
     bzfs/   - bzfs app source code (game server)
 
     bzfs/   - bzfs app source code (game server)
 
     common/   - general purpose classes
 
     common/   - general purpose classes
 +
    date/        - unified version and build date stamping for apps
 
     game/   - game library used by both the server and client(s)
 
     game/   - game library used by both the server and client(s)
 
     geometry/   - geometry rendering classes
 
     geometry/   - geometry rendering classes
Line 370: Line 322:
 
     ogl/   - OpenGL utility classes
 
     ogl/   - OpenGL utility classes
 
     platform/   - platform dependent code
 
     platform/   - platform dependent code
      MacOSX/      - Mac OS X specific files
 
 
     scene/   - high level rendering algorithms
 
     scene/   - high level rendering algorithms
    zlib/   - compression library
 
 
   tools/ - various helper utilities
 
   tools/ - various helper utilities
   win32/ - stuff for building on the Windows platform
+
   Xcode         - Mac OS X Xcode project and associated files
  
 
Note that include/ does not have all the include files.  If a header
 
Note that include/ does not have all the include files.  If a header
Line 386: Line 336:
  
  
Miscellaneous
+
Public Internet Servers and the "list server"
=============
+
=============================================
  
UDP added by Frank Siegert, frank@this.net, frank@bzflag.de
+
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, BZFlag 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
 +
https://my.bzflag.org/listkeys/
  
BZFlag implements UDP unicast relay networking. This provides much
 
better timing and stability compared to just TCP.
 
  
One of the more frequent questions, UDP does not work, why?
+
Notes on "CHEAT" servers and network abuse
 +
==========================================
  
- When I connect to a newer server with this client others report they
+
While the license for BZFlag certainly allows users to run any server
  can see me but I get 'black caps' after a few seconds for all other
+
modification that they wish or to modify the code in any way, we ask
  players?
+
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.
  
Two possibilities:
+
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.
  
a) you are behind a NAT router that is not forwarding UDP traffic to
+
Any individuals that are found to be contributing to abuse of the
  your system. Try reconfiguring the router to do NAT on UDP packets.
+
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.
  
b) you are behind a firewall or a desktop firewall (e.g. ZoneAlarm)
+
The BZFlag project administrators reserve the right to remove public
  that is blocking incoming UDP traffic. Please reconfigure or disable
+
listings of any game servers for any reason whatsoever, including
  your firewall(extreme solution) for the game, for more intelligent
+
removal of servers or banning of individuals that do not follow this
  desktop firewalls set them up to let UDP port 17200 to 17220 through.
+
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, 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.
  
Notes on "CHEAT" servers
+
 
=============
+
Project History and Contributions
While the license for bzflag 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" type clients or servers that ruin the game for people.
+
BZFlag was primarily originally authored by Chris Schoeneman
We understand the desire to expand and modify the game and it's sources, so we
+
<crs23@bigfoot.com> in the early 1990's. After several years of
ask that anyone wishing to run a game that uses modified code or logic on
+
development, Chris turned over copyright and maintainership of the
a different network protocol then the current public release. This will let
+
game to Tim Riker.
moded games be played, and prevent moded clients from being used on public un-moded
+
 
games. The bzflag project administrators reserve the right to remove public listing
+
BZFlag continues today to be maintained and developed by the Open
of any game servers that do not follow this rule. We also reserve the right to
+
Source community by a project administration team with contributions coming
remove any global accounts or access to public services at any time.
+
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:
 +
 
 +
Scott Wichser (blast007) <blast007@users.sourceforge.net>
 +
Jeff Makey (BulletCatcher) <bullet_catcher@users.sourceforge.net>
 +
 
 +
Happy Shooting!
 +
The BZFlag Development Team
 
</pre>
 
</pre>

Latest revision as of 15:17, 13 March 2017

			    BZFlag 2.4.10
			 http://BZFlag.org/
		Copyright (c) 1993-2017 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, and other
platforms.

BZFlag may be redistributed under either the LGPL or MPL licenses.

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
	Forums
	Wiki
    Bug Reports and Support
    Providing Contributions
    Source Tree Organization
    Public Internet Servers and the "list server"
    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 GitHub 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 directly from a git clone you need to create a
configure script. You can skip this step if you grab a distribution of
BZFlag that already has a ./configure script in it, such as from a
source distribution tarball.  To generate the configure script, you
need to run the provided autogen.sh script:

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

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
the Git repository.

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, forums, 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 https://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.

Forums
---------------
There are extensive and active forums used by players, server
operators, administrators, and others available here:

https://forums.bzflag.org

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

Wiki
----
The main BZFlag website contains a wiki that may be edited by the
community available at: https://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 are also available 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.)
  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
    platform/	  - platform dependent code
    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.


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, BZFlag 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
https://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, 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:

Scott Wichser (blast007) <blast007@users.sourceforge.net>
Jeff Makey (BulletCatcher) <bullet_catcher@users.sourceforge.net>

Happy Shooting!
The BZFlag Development Team