README

			    BZFlag 2.4.27
			 http://BZFlag.org/
		Copyright (c) 1993-2023 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
    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 and forums.

Internet Relay Chat
-------------------
Most of the BZFlag development activity and discussions occur over
IRC.  Join the #bzflag IRC channel on the Libera.Chat network
(irc.libera.chat, TLS port 6697) to get involved.

See https://web.libera.chat/ 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 Getting Started page on our site for more about registration.


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.libera.chat

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