Information for the BZFlag Developer
====================================

BZFlag source code lives in the following directories:

applications
------------
src/bzflag	- the BZFlag client
src/bzfs	- the BZFlag server
src/bzadmin	- the BZFlag admin tool and chat client
tools/		- various helper tools

game dependent libraries
------------------------
src/game	- core game logic

game independent, platform independent libraries
------------------------------------------------
src/common	- general utility
src/3D		- 3D geometry
src/geometry	- geometric mathematics
src/obstacle	- collision detection
src/scene	- scene graph
src/ogl		- wrapper classes for OpenGL
src/mediafile	- sound and image file support
src/regex	- BSD regular expression library
src/zlib	- Zlib compression library

game independent, platform dependent libraries
----------------------------------------------
src/date	- build dates and versioning
src/net		- networking
src/platform	- general platform dependent code

"other stuff"
-------------
doc/		- documentation in docbook format
include/	- public headers
misc/		- kitchen sink of anything
web/		- website stuff

Note that only a few directories contain code directly related to the
game BZFlag.  In particular: bzflag, bzadmin, bzfs, and game. (And
obstacle, but that will hopefully be made more general some day.) The
rest of the code could potentially be used in a different game. If
your code is BZFlag specific then it should go into one of the above
directories (game if it can potentially be used by more than one app,
otherwise into the appropriate app directory).  If not then put it in
one of the other directories or add a new directory.


Coding conventions
==================

If you plan on contributing any source code to BZFlag, we would like
you to follow certain conventions.  Contributions that don't conform are
likely to be ridiculed and rejected until they do.

Code Organization
-----------------
Follow the above organization when introducing new files.  Any code
that would potentially be useful in another game goes outside of the
app directories and outside the game directory.  Platform dependent
code normally goes into platform, net.  Code that is specific to
bzflag should go into the game directory.  There are README files in
most all of the source directories that describe what belongs in those
directories

Header files that are private to a library go into that library's
directory.  Header files exported from a library go into the include
directory off the top-level.  Header files for classes introduced in
an application directory should never go into a #include outside of
that application directory.

C files use the .c extension. C++ files use the .cxx extension.
Header files for both C and C++ use the .h extension.

Headers
-------
Don't put interface headers into the common.h header.  Class interface
headers should include just what is necessary to make the interface
work.  The source implementation file should include it's interface
and whatever else it might need specific to the implementation.  For C
code, the header file should include everything the C code needs
(otherwise there's no point to the header) including prototypes for
all non-static functions.

The include order for headers within a header is common.h, system
headers, common interface headers, and then local interface headers.

The include order for headers within a source file is its own
interface header if there is one, or common.h otherwise, system
headers, common implementation headers, and then local implementation
headers.

 Adhering to this order will avoid nasty
ordering dependencies and makes it easy to change things down the road.

Ideally, there should be one class per file.  There are, of course,
exceptions to this such as simple utility classes that are local to
that same file's implementation.  If it's a public class, though, it's
usually best to separate it out into another file by itself.

Avoid "extern" in C files. This prevents the compiler from type checking in
most cases. If you need access to something, put it in a header. That's what
headers are for.

C++ features
------------
Earlier versions of BZFlag avoided certain features of C++ that have
matured enough to be widely and well supported.  These features are
now permitted and encouraged including:

  bool			-- the boolean type and True and False are gone
  standard C++ library	-- use where appropriate (AList is gone)
  templates		-- use sparingly where appropriate

These should still be avoided:

  exceptions		-- still poorly supported on old lame compilers
  run-time typing	-- if you find yourself needing RTTI, its often a
			   sign of bad design. try to find another way to
			   implement your idea.

Multiple inheritance is strongly discouraged unless in the Java style
of single implementation inheritance and multiple interface
inheritance.  Multiple inheritance otherwise can quickly lead to very
hard to understand code.

Formatting
----------
Everybody has their own style and has things they don't like about any
other style.  Well we can't have a zillion styles in the code. So
follow the BZFlag if you want your contribution included.  The source
code serves for examples but some rules:

  1)  indents are 2 characters. Tabs are 8 characters. There are vi and
      emacs settings in each file to adopt, enforce, remind, and
      encourage this convention. Suggestions welcome here for setting
      up other environments. Here are the lines that should be included
      at the end of source files:

	// Local Variables: ***
	// mode: C++ ***
	// tab-width: 8 ***
	// c-basic-offset: 2 ***
	// indent-tabs-mode: t ***
	// End: ***
	// ex: shiftwidth=2 tabstop=8

  2)  the opening brace of all blocks goes on the same line as the
      statement introducing it except for functions and classes where
      it goes on the following line. the closing brace is indented
      like the statement except for functions where it aligns with the
      open brace.  for example:

        void foo()
        {
          for (;;) {
            if (expr) {
            }
          }
        }

  3)  an else clause goes on the same line (there are many unacceptable
      alternatives):

        if (expr) {
        } else {
        }
	*note that old code had the else on the next line,
	 please clean this up wherever you may find it*

  4)  if *either* the if block or else block requires brackets then
      they both get brackets.  if neither requires brackets then use
      brackets on both or neither at your discretion. In case both
      styles are allowed, don't change the existing code just because
      it is not coded like you prefer.

  5)  when using `delete' or `delete[]' don't bother to test the
      pointer if it's NULL first.  use new and delete rather than
      malloc and free.

  6)  data members should be usually private unless making plain old
      data.  separate methods from data in class definitions with
      (possibly redundant) access specifiers.  public c'tors/d'tors
      should be first, followed by public member functions, protected
      member functions, private member functions, and data members.

  7)  macro names are all capitals, class names have the first letter
      of each word capitalized, all other names have the first letter
      of each word except the first capitalized.  only macros may use
      underscores except a leading underscore in a method parameter
      name is allowed to make it different from a member variable.

        #define FOO bar
        class MyClass {
        public:
            void        addStuff(int addMe, int _y) { y = addMe + y; }

        private:
            int         y;
        };

  8)  put spaces after statements followed by expressions and spaces
      around operators.  for example:
        if (a == b)
      not
        if(a==b)

  9)  Do not leave old commented code hanging around and do not submit
      patches with "// Added by foo on xx" comments. This is what
      version control software is for.

Violations of these rules in the existing code are not excuses to
follow suit.  Non-conformant code may be fixed.  Patches to
non-conformant code should follow the non-conformant code's style if
following the rules would cause an ugly mess.


CVS commit
=======

Make atomic changes in a way that a system will be working, or at
least will be buildable, before and after the commit.
(CVS does not enforce atomic changes)
Try to separate big commit, involving multiple functionality changes,
in smaller coherent chunk; in case of bug, they can be simply undone.

Testing
=======

If you have rendering problems, you might want to try setting:

LIBGL_ALWAYS_INDIRECT=1

On many systems this will force software rendering.  It will greatly
reduce the performance, but may assist in solving rendering issues.

A debug build may be specified via:

./configure --enable-debug

A profile build is specified via:

./configure --enable-profile


Sounds
======
Sounds are stored as uncompressed 22.050KHz WAV files. We will likely move to
OGG someday.


Images
======
Images are stored as portable network graphics (.png). Compression is
okay, but no additional options such as interlacing.


BZDB
====
BZDB is the generic name:value pair database within bzflag and
bzfs. Its useful for data that can be serialized to a string that
needs to be accessible to many areas of the code. It also provides
facilities for saving persistent pairs to the config file and
downloading variables from the server.

BZDB is not an object broker, and isn't meant to be. If you have data
within an object that needs to be accessible from a number of places,
but don't want to pass the object around, you could store that data
within BZDB (if accessed often, such as game variables like gravity,
you will need a cached version anyway to avoid the overhead of
lookup). Using BZDB adds unnecessary overhead if objects generally
keep their data hidden without needing persistent state.

Basically, if your data can be serialized to a string, and it makes
sense to do so (eg: config file option, game variable downloaded from
server), use BZDB. If you wanted an object broker, use a freakin'
global.


Version numbers
===============
The BZFlag versioning info is defined in:   include/version.h

There are a number of #defines in that file that define the Major,
Minor, and Revision versions, as well as the build type, build date,
build user, and network protocol version.

The BZFlag version number is in the format of:

  MajorVersion.MinorVersion.Revision

All "development" versions use an odd number for the minor version
number.  All "release" versions use an even number for the minor
version, e.g.. 1.9.x is a development version for a future 1.10
release.  Release versions also use even revision version
numbers. Maintenance work is done on odd numbered revisions and
releases are even numbered. For development versions the revision
version represents significant feature changes or stages in a
development version, such as a change to the network protocol or a
move to a definite testing stage.  For "release" versions, the
revision represents patches or bug fixes to the base release, but not
new feature development.  This allows the developers to "leave some
room" for patches and emergency fixes to a release line.

The network protocol version is a string. When changes to the protocol
are made that render it incompatible with prior releases, the version
number of the protocol must be changed.  This is necessary to prevent
incompatible clients from attempting connections.  When a change is
made, the network protocol version needs to be set to the application
version that is current at that time.  This is also when the revision
of the application should be incremented.

The displayed application version includes additional information in
the format:

  Major.Minor.Revision-BuildOS-BuildType-BuildDate

BuildOS is the operating system that the building system is running;
on systems that use the automake build system this is automatically
generated.

BuildType is a string that represents the intended use of the build.
For development releases, the build type is normally "CVS".  For
testing releases, the build type can be "testing", "beta",
"releasecandidate", etc.  For final release versions the build type
should be "release".  The build type provides a human readable keyword
for the version and intended or expected stability of the build.

BuildDate represents the date of the build in the format YYYYMMDD.
This string is generated during runtime by the compiler's preprocessor
__DATE__ macro.


Making a Release
================
In order to make a release, there are handful of steps that need to be
taken.  If any step fails to be completed successfully, the release
cannot proceed.  A checklist of items to be completed follows:

- All code is committed to CVS

- ChangeLog includes a comment for all items added since the previous
  release, preferably denoting who made what changes.

- Man files, bzfs_conf.html, and bzfs.conf files are updated with
  latest changes.

- Version numbers are updated to the next expected release number.
  This minimally includes updating README, buildDate.cxx, and
  ChangeLog.  Version numbers in all other platform-specific
  README.* files should also be verified.

- Update package/win32/nsis/*.nsi (for windows) with appropriate
  version numbers

- Perform a "make distcheck" on multiple (preferably all) platforms.
  This will verify that a proper source distribution can be made.
  Also verify that all non-autotools builds build properly.

- Tag the release.  Tag format should be consistent with the other
  tags using the format of vMAJOR_MINOR_RELEASE
	e.g. cvs tag v1_10_2

- Perform a "cvs export -r vMAJOR_MINOR_RELEASE" from somewhere else
  in the filesystem to obtain a tagged version of the sources.

- Perform a "make dist" of that export to generate a source release
  tarball.

- Verify that the source tarball can be expanded, builds, and runs.

- Build platform-specific binaries from the source tarball.

- Post the source tarball and platform-specific binaries to
  SourceForge.

- Increment and commit the version number in the CVS source
  configure.in file so that later builds are immediately
  distinguished.

- Notify the following (at least):

bzflag-users@lists.SourceForge.net
news on http://BZFlag.org/
news on http://sourceforge.net/projects/bzflag/
http://slashdot.org/
http://freshmeat.net/projects/bzflag/ (rank BZFlag here!)
http://happypenguin.org/ (BZFlag is now #2 in the ratings!)
news@linuxgames.com - http://LinuxGames.com/
John Gowin <jgowin@linuxorbit.com> (thanx for the review!)
jd@linuxgaming.co.uk
updates@superdownloads.com.br
mail -s add LSM@execpc.com < bzflag.lsm
http://www.gbld.net/

Testing the server
==================

An example line to use for bzfs testing is:

src/bzfs/bzfs -c -d -d -d +f good +f bad -fb -j -ms 3 -password \
 password -s 10 -sa -sb -sw 1 -st 15 -world misc/hix.bzw