Difference between revisions of "BZFlag README"
(→README (from v2.0.8 source))
Revision as of 17:32, 14 July 2007
BZFlag 2.0.8 http://BZFlag.org/ Copyright (c) 1993 - 2006 Tim Riker Maintainer ========== Tim Riker <Tim@Rikers.org> http://rikers.org/ Original Author =============== Chris Schoeneman 475 Hawthorne Av Palo Alto, CA 94301 firstname.lastname@example.org See the AUTHORS file for more authorship details. Introduction ============ 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. It includes simple build instructions, user community references, other information for BZFlag development, and a manifest of the source code layout. Obtaining BZFlag ================ Main BZFlag Website: http://BZFlag.org BZFlag Project Site: http://sf.net/projects/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 CVS. To obtain BZflag from CVS, a bit more familiarity with software development is expected. Sometimes active BZFlag development is on CVS HEAD, sometimes it is on a branch, sometimes it's in multiple places. Inquire on the #bzflag 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:email@example.com:/cvsroot/bzflag login [ press return for no password ] cvs -z3 -d:pserver:firstname.lastname@example.org co -P bzflag 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 --enable-optimized 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 CVS 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, make sure your tools are recent. Now that you have a configure script and presuming the previous step was successful, you can configure BZFlag: % ./configure --help There are a variety of options possible when configuring BZFlag. Most notably, you'll probably want to use the --enable-optimized option for performance and the --enable-shared option if you are building server plugins. % ./configure --enable-optimized --enable-shared 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+ libCURL 7+ If you're on an operating sytem 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. 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/cvs checkout, 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 symlink: % 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.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: % 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. 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://irc.bzflag.org 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 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 operators, administrators, and others available here: http://my.bzflag.org/bb/ 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. 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 ---- The main BZFlag website contains a wiki that may be edited by the community available at: http://BZFlag.org/wiki 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. 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. Bug Reports and Support ======================= For reporting bugs and unexpected behavior, please go to BZFlag bug tracking system at: http://sourceforge.net/tracker/?group_id=3248&atid=103248 Alternatively, you can email bug reports to the development mailing list or to Tim@Rikers.org but the web based method is preferred. See the BUGS file in the source distribution for other known issues. If you require assistance with some issue, please visit BZFlag support tracking system at: http://sourceforge.net/tracker/?group_id=3248&atid=203248 Alternatively, the IRC channel, discussion forums, and mailing lists are also viable avenues for resolving issues. Contributors ============ BZFlag has a long history of development and considerable community involvement since it became an Open Source project. See the AUTHORS file for more details. Source Tree Organization ======================== After unpacking a source distribution, 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 - source code changes since previous release COPYING - the license for BZFlag NEWS - history of visible changes for each release DEVINFO - information for developers PORTING - a guide for porting BZFlag RELNOTES - placeholder - see NEWS TODO - incomplete list of things to do 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 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 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 MacOSX/ - Mac OS X specific files scene/ - high level rendering algorithms zlib/ - compression library tools/ - various helper utilities win32/ - stuff for building on the Windows platform 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. Miscellaneous ============= UDP added by Frank Siegert, email@example.com, firstname.lastname@example.org 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? - 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 or disable your firewall(extreme solution) for the game, for more intelligent desktop firewalls set them up to let UDP port 17200 to 17220 through. Notes on "CHEAT" servers ============= 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. We understand the desire to expand and modify the game and it's sources, so we ask that anyone wishing to run a game that uses modified code or logic on a different network protocol then the current public release. This will let 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 of any game servers that do not follow this rule. We also reserve the right to remove any global accounts or access to public services at any time.