BZFlagWiki - User contributions [en]

2.0 Releases

2025-12-01T12:06:28Z

Loymdayddaud: fix 2.0.2 using 2.0.4 as the name in one place

The 2.0.x series had 8 releases total.

{|{{Prettytable}}
|-
| {{Hl3}} |'''Release Version:'''
| {{Hl3}} |'''Release Date:'''
|-
| [[BZFlag 2.0.0]] || 01/17/2005
|-
| [[BZFlag 2.0.2]] || 03/18/2005
|-
| [[BZFlag 2.0.4]] || 09/30/2005
|-
| [[BZFlag 2.0.6]] || 04/09/2006
|-
| [[BZFlag 2.0.8]] || 05/13/2006
|-
| [[BZFlag 2.0.10]] || 11/17/2007
|-
| [[BZFlag 2.0.12]] || 06/25/2008
|-
| [[BZFlag 2.0.14]] || 02/15/2010
|-
| [[BZFlag 2.0.16]] || 04/01/2010
|-
|}

One of the notable features, was the introduction of the server side API for plugins in 2.0.4 and versions above.

==2.0.0==
BZFlag version 2.0.0 is a version of the BZFlag game that was released on 2005-01-17 under the title "Falcor's Despair".

v2.0.0 was a major version upgrade for the project and included a number of new features, including new [[BZFlag Graphics System|graphics engine]] and [[BZW|map]] features.

v2.0.0 had a large list of features and was the first released version to allow for arbitrary world geometry via [[Mesh]] objects.

* Added a .desktop file - David Trowbridge
* Tool for converting obj to bzw - Jeff Myers
* Addition of converted ProFont font - Andrew Keyser
* Added a file syntax section to bzw.5 - Fred Cods
* Added a bzw.5 manpage to document world file format - Sean Morrison
* Added /quit command - Angelina Carlton
* Display player addr on join to admins - Sean Morrison
* Make -debug a public client option - Frank Thilo
* Communicate autopilot state, display in scoreboard - Frank Thilo
* Observer counts and match times added to game queries - David Vuorio
* Central authentication - Tim Riker
* Avoid transfer flag cheat - Alfredo Tupone
* Cheat client flag obfuscation and hiding - Alfredo Tupone
* Added strong authentication via Kerberos - Alfredo Tupone
* BZFlag renders frames and accepts commands during joining - Alfredo Tupone
* Lag is computed only after entering game - Alfredo Tupone
* CTF world used for FFA make bases into boxes - Alfredo Tupone
* Allow elevated bases even without -fb - Alfredo Tupone
* Added optional duration option to /countdown - Sean Morrison
* Added shot mismatch cheat auto-kicking - Julio Jimenez
* Improved double-jump response - Anonymous
* Added physics drivers - Anonymous
* Unlimited altimeter height - Steve Krenzel
* Added /uptime command to print elapsed running time - Angelina Carlton
* Countdown command now shows players 10 sec countdown - Angelina Carlton
* Added a flapping sound for the wings flag - Sean Morrison
* Adding ability to load world from url (http, ftp, file) - Alfredo Tupone
* Reduce network load by buffering UDP packet (no delay) - Alfredo Tupone
* Allow server to control lat and long (-synclocation) - Daniel Remenak
* Added tank spawn expansion effect - Anonymous
* Added tank squishiness - Anonymous, Dave Brosius
* Added animated effects for T, N, TH, O, and CL flags - Anonymous
* BZAdmin now tells more specific reasons why it could not connect - Ian Agar
* MOTD from the master server - Jeff Myers, Daniel Remenak, Frank Thilo
* Add generic URL retrieval class - Jeff Myers, Alfredo Tupone
* Windows Multimedia and DirectInput joystick support - Daniel Remenak
* bzfs can now announce to multiple public list servers - Sean Morrison
* Global public server bans - Jeff M., Alfredo T., Daniel R., Sean M., Bryan J.
* Linux event device joystick and force feedback support - Micah Dowty
* Inform banned users of reason, originator, and source on login - Jeff Myers
* Added the SHORTBAN bzfs privilege - Anonymous, Daniel Leeds
* Added /date and /time to request server date and time - Ian Agar
* Added arc, cone, and sphere map objects - Anonymous
* Added user specified dynamic colors - Anonymous
* Added user specified texture matrices - Anonymous
* Improved BSP splitting algorithm - Anonymous
* Added /part command for disconnecting from server - Angelina Carlton
* Show status while trying to connect & download world - Daniel Remenak
* Update old configs to avoid broken keybindings - Daniel Remenak
* Config files are stored per-version, using older when needed - Jeff Myers
* Faster tank and shot collision detection using an octree - Anonymous
* Better linewrapping for control panel - Daniel Remenak
* Configurable font size for control panel and scoreboard - Daniel Remenak
* Textures are now reloaded on a mode change for optimal quality - Jeff Myers
* Automatic team joins changed to encourage team-play - Alfredo Tupone
* Fixed dropping flag while jumping from high places - Alfredo Tupone
* Lag stats are now sorted by lag value - Alfredo Tupone
* OpenGL context reloading bug fixed on SDL - Alfredo Tupone
* Roaming switch between player is now consistent - Alfredo Tupone
* Compensating jitter in Dead reckoning - Alfredo Tupone
* Ping packet loss are like high lag for warn/kick - Alfredo Tupone
* ColorBlindness now disable hunt flashing on radar - Alfredo Tupone
* SDL is made default platform, static and shared linkage - Alfredo Tupone
* Fixed bug where players get stuck on flipped pyramids - Alfredo Tupone
* Compressed map data going over the network and into caches - Anonymous
* Options to disable certain /poll's entirely on a server - Simon Richard Grint
* Lighting menu option now has "None / Fast / Best" - Anonymous
* Dev-C++ project files - Ian Agar, Daniel Remenak, Jeff Myers
* Shot accuracy statistics dialog - Daniel Remenak
* Faster zbuffer graphics using octree and dynamic occluders - Anonymous
* Faster startup times by making the SceneDatabase on the fly - Anonymous
* Autocompletion for commands & callsigns (ala bzadmin) - Ian Agar, Frank Thilo
* /clientquery can now be requested on single individuals - Ian Agar
* Added support for irc-like /me actions and /msg messages - Sean Morrison
* Seer flag now can see Invisible Bullets - Anonymous
* Added admin message sounds - Cameron Mandrake, Sean Morrison
* Better shot reflections for non-square pyramids - Anonymous
* Fixed collision detection impalement problem - Anonymous
* anti perm for pollkick, pollban, kick, ban, deregister - Sean Morrison
* antipoll bzfs anti perm to protect against poll kick/bans - Andrew Heyn
* Server Start Menu now selects Rabbit Chase styles - Ian Agar
* Tabbed Message Panel - Scott Wichser, Sean Morrison, Alfredo Tupone
* Fonts settable via BZDB - Daniel Remenak
* New font management system and fonts - Daniel Remenak, Jeff Myers
* Reduce network utilization (tolerance) - Alfredo Tupone, Sean Morrison
* WorldWeapons and EntryZones are saved client-side - Anonymous
* Improved client map saves using map 'options' - Anonymous
* Autopilot is now capable of playing CTF - Ian Agar
* bzadmin can now send and receive team and admin messages - Lars Luthman
* Added waterLevel (water-like feature for maps) - Anonymous
* Added _noShadows (to disable shadows on a server) - Anonymous
* bzadmin's curses menu will now update automagically - Lars Luthman
* Added message filter editor for bzadmin using menu or cmds - Lars Luthman
* Added team flag safety zones - Anonymous
* Added MsgScoreOver and MsgTimeUpdate to BZAdmin - Ian Agar
* Have BZAdmin allow whitespace in callsign and host - Ian Agar
* Prevent message flooding/spamming - Ian Agar
* Consolidated polling system bzfs options (-poll) - Ian Agar, Sean Morrison
* Improved server pause cheat detection and reporting - Ian Agar, Sean Morrison
* Changed the way Roaming keys drives the Observer - Alfredo Tupone
* Fixing cross-correlation between driving keys - Alfredo Tupone
* Added configuration of driving keys - Alfredo Tupone
* Server is now valgrind-happy - Alfredo Tupone, Daniel Remenak, Sean Morrison
* Limit quick rejoins - Anonymous
* Added 'options' section to world maps - Anonymous
* Added the '-set <name> <value>' option to bzfs - Anonymous
* Throw away bad or early links in world files - Tim Riker
* Added Record/Replay feature - Anonymous
* Added Random teleporter destinations - Anonymous
* Poll to reset flags and Poll-cheating prevention - Ian Agar
* Flag and Tank Entry Zones - Dave Brosius
* Spawn improvements - Dave Brosius, Daniel Remenak
* Added MAC's Agility (aka Dodge) flag - Sean Morrison
* QuickTurn flag symbol changed from A to QT - Sean Morrison
* Added MAC's handicap game style - Sean Morrison
* Added ReverseControls bad flag - Sean Morrison
* Added Wings good flag - Dave Brosius
* Added BZDB variables to allow for more realistic friction - Nils McCarthy
* Added ForwardOnly and ReverseOnly bad flags - Sean Morrison
* No Jumping and Trigger Happy flags - Nils McCarthy
* server option to disallow autopilot - Nils McCarthy
* SDL interface to audio/video/input - Tupone Alfredo
* /clientquery (was CLIENTQUERY) moved to server - Daniel Remenak
* "Leave Game" menu item to leave a game without quitting - Daniel Remenak
* Allow user to force input device to that of their choosing - Daniel Remenak
* Tanks can drive over bumps - Dave Brosius
* Remove Building scene nodes laying on the ground (or lower) - Dave Brosius
* Rip out ref counted texture system, TM controls this now - Dave Brosius
* Added Admin Message Queue - Michael Hoffmane - Frank Evers

==2.0.2==
BZFlag version 2.0.2 is a version of the BZFlag game that was released on 2005-03-18 under the title "Queen of Maybe".

v2.0.2 was a maintenance release of the 2.0.x code base that provided a large number of features compatible with all 2.0.x clients.

* Added TALK, MUTE, UNMUTE permissions - Angelina Carlton
* Added /mute, /unmute commands - Angelina Carlton
* Automatic team try to fix bad player behaviour - Alfredo Tupone
* bzadmin does not require opengl headers - Alfredo Tupone
* bzfs handle both -mp specification - Alfredo Tupone
* bzfs correctly handles ban time - Alfredo Tupone, Julio Jimenez
* bzfs no more put jittered players as Not Responding - Alfredo Tupone
* bzfs stop shot from dead player - Alfredo Tupone
* Roaming switching between player goes even on Dead Player - Alfredo Tupone
* Fixed bzfs crash associated to "Error adding player" - Alfredo Tupone
* bzflag count a single -1 score for a tk (like server does) - Alfredo Tupone
* Fixes on hostban handling - Alfredo Tupone
* Fixed force feedback on Windows - Scott Wichser
* New Kick/Ban options using slot numbers (rendered in client) - Julio Jimenez
* Added EndShot cheat detection - Julio Jimenez
* Avoid spawning on top of tanks with SR or BU - Daniel Remenak
* Add fine-grained permissions control of polling - Daniel Remenak
* Fixed loading of colormapped PNGs - Daniel Remenak
* Add SPAWN permission, remove -requireidentify - Steve Krenzel, Tim Riker
* A /say command for server messages - Julio Jimenez, Frank Evers
* Rejoin permission for avoiding _rejoinTime limit - Frank Evers, Julio Jimenez
* A player will auto ghost if they use global authentication - Steve Krenzel
* Server announces who started a countdown - Angelina Carlton
* Fixed server start menu for windows - Daniel Remenak
* Message spam checking bug fixed - Alfredo Tupone
* Fixed no flag on building - Alfredo Tupone
* Fixed MsgQueryPlayer eventually sending AddPlayer to all - Alfredo Tupone
* Removing kicking player for missing packet - Alfredo Tupone
* Player is unpaused when coming alive - Alfredo Tupone
* Observer of winner not updating the flag fixed - Alfredo Tupone
* Fixed 2 flag per team selecting ctf on world & CommandLine - Alfredo Tupone
* Fixed lag warning counted twice - Alfredo Tupone
* Allow user to select which physical joystick axes to use - Daniel Remenak
* Fix a number of server crash bugs - Daniel Remenak
* ctf make restarting on base even when dead - Anonymous
* Fixed weirdness on Console Panel when disabling chat display - Alfredo Tupone
* Fixed a segfault with SDL and no audio - Alfredo Tupone
* bzadmin wipes argv to hide possible password - Tim Riker
* Lagstats and Playerlist no longer filtered - Steve Krenzel
* print errors in red - Frank Thilo
* simple scroll indicator for control panel - Frank Thilo
* antiban perm actually counters a server ban now - Steve Krenzel

==2.0.4==

BZFlag version 2.0.4 is a version of the BZFlag game that was released on 2005-09-30 under the title "Shiny".
v2.0.4 was a maintenance release of the 2.0.x code base that provided a large number of features compatible with all 2.0.x clients.

v2.0.4 had a large list of features and was the first released version to include support for server side [[Plug-ins]].

* Fixed server join bug when cached worlds disappear - Sean Morrison
* Prevent phantom zoned players from pausing - Sean Morrison
* Implemented multiple player hunt - Mark Thomas
* Directional keys pressing works, even in joy/mouse mode - Tupone Alfredo
* Jitter compensation removed. Too bad behaviour on ME players - Tupone Alfredo
* Put spawn params in BZDB to let server owners mod them as needed - Jeff Myers
* Fixed ban admin bug - Julio Jimenez
* Added /sendhelp command - Mike Weisenborn, Mark Thomas
* /ban /hostban take time keywords (short ...) too - Jeff Myers, Alfredo Tupone
* Inertia style indicatio no more used - Alfredo Tupone
* No more restriction on M (Momentum) flag - Alfredo Tupone
* Fixing authentication when changing callsign/password - Alfredo Tupone
* Fixing authentication when joining from command-line - Alfredo Tupone
* Executing abbreviated server command '*' terminated - Alfredo Tupone
* Getting one-line-help on server command '?' terminated - Alfredo Tupone
* Fixing bzflag use of system-wide regex (--without-regex) - Alfredo Tupone
* Adding destination info to chat message log - Alfredo Tupone
* Adding syntax check to duration parameter of ban cmds - Alfredo Tupone
* Hud outlines go transparent with the hud panel - Jeff Myers, Daniel Mulford
* Better progress info when downloading textures - Garrett Padera, Jeff Myers
* Add Quake3 BSP import to modeltool - Jeff Myers
* Exit BZFS if -g is used with -mts or -mps - Joshua Rogers
* Experimental server colorizing in server list - Frank Thilo
* Added sort options to "/replay list" and "/record list" - Mark Thomas
* Map mismatch fixed - Alfredo Tupone
* Quick server command key works better - Alfredo Tupone
* Default server side plugins added to windows build - Jeff Myers
* Include web token verification script - Garrett Padera
* Fix texture cache on windows. - Jeff Myers
* Disallow + or @ as first char of callsign (bzfs) - Mark Thomas
* Wait for reverse DNS and authentication to enter game - Alfredo Tupone
* Antiban works even on IP number - Alfredo Tupone
* Sort lagstat to have non-observer at the bottom - Thomas Stauer
* Authentication credential are requested asap - Alfredo Tupone
* Allow the use of game device sliders as axes on Windows - Daniel Remenak
* Directional force feedback support - Daniel Remenak
* New icon and menu arrow - Harry Keller, Jeff Myers
* Special effects for many events - Jeff Myers, Daniel Remenak
* Server-side plugin API and plugins - Jeff Myers
* Join menu displays team icon - Daniel Remenak, Harry Keller
* Implemented "-advertise" option for bzfs - Mark Thomas
* The url now does not contain the password (sent with POST) - Tupone Alfredo
* Fixing Tiny tank shooting from the world edge - Tupone Alfredo
* Fixing client requesting lan server on some systems - Tupone Alfredo
* Observer are no more hunted - Tupone Alfredo
* Added 'Always Show Team Scores' option (GUI Options Menu) - Mark Thomas
* Added beautify scores - Julio Jimenez
* Added scoreboard sort option - Mark Thomas, Karsten Behrmann
* Shots fired over the boundary wall end at the wall - Daniel Remenak
* Increase range of radar size setting in GUI Option menu - Mark Thomas
* Fixed Menu rendering when radar size is great - Sean Morrison, Mark Thomas
* Fixed Linux name resolution (server list) problem - Sean Morrison
* Fixed Jitter problem on Windows, clock was wrong - Alfredo Tupone
* Windows platform can switch from SDL to native - Alfredo Tupone
* Instruction for X-build from linux to windows - Alfredo Tupone
* bzflag is much less blocking with libcurl - Alfredo Tupone
* Using c-ares instead of adns for DNS resolving - Alfredo Tupone
* Added CTF capture event trigger for world weapons - Jeff Myers, Nathan Goings
* FlipZ on meshpyrs behaves as expected (like pyramids) - Daniel Remenak
* Fixed /set and /reset command case bug - Daniel Remenak
* Fixed crash on /ban without -banfile - Daniel Remenak
* Shot reload timer on the HUD - Daniel Remenak
* Added timestamp to bzfs DEBUG output, and new CL option (-ts) - Mark Thomas
* Players without TALK can send to the Admin group - Sean Morrison
* Fixed bzfs crash because poll kick/ban - Julio Jimenez
* Allow additional group modify permission lines - Frank Evers
* bzfs creates default groups before parsing groupdb file - Frank Evers
* +ALL and -ALL adds/removes all perms from a group in groupdb - Frank Evers
* Support for +,- and ! operators in bzfs' groupdb file - Frank Evers

==2.0.6==
BZFlag version 2.0.6 is a version of the BZFlag game that was released on 2006-04-09 under the title "Good enough for now".

2.0.6 was replaced in less then a month by [[BZFlag 2.0.8]] due to a critical HTTP bug. It is recommended that all users upgrade to 2.0.8

v2.0.6 is an extension of the major features released with [[BZFlag 2.0.4|v2.0.4]]. It included a number of [[BZFlag Graphics System|graphics engine]] changes made by [[trepan]] as well as some major bugs.
v2.0.6 was released to give the users a minor update while issues with stagnation in development of [[BZFlag 2.99]].

* game variables no longer accept invalid values. - [[Jeff Myers]]
* Special Effects use tank (was team) color - Karsten Behrmann, [[Jeff Myers]]
* /reset uses the values from the config and the map as default - [[Jeff Myers]]
* Screenshots now remember where they left off - [[Jeff Myers]], Thomas Sowell
* Have windows dump std::error out to a file - [[Jeff Myers]]
* Various API enhancements - [[Jeff Myers]] and others ( from patches )
* Not applauding when capturing his own flag - [[Alfredo Tupone]]
* Fixing crash on invalid captured flag - [[Alfredo Tupone]]
* Fixed bots on a public server -[[Alfredo Tupone]]
* Don't send admin the server password when wrong - [[Alfredo Tupone]]
* Client config file can be saved on request - [[Alfredo Tupone]]
* Allow for longer help files (50 lines) - Angelina Carlton
* Allow selective /reload of databases - Bernt Hansen
* Fix wrong kick if pausing having V and moving - Julio Jimenez
* Prevent long distance tank warping through walls - [[Sean Morrison]]
* Display paused state when screen capturing while playing - [[Sean Morrison]]
* Added new logDetail plugin - Bernt Hansen
* Fixed issue with denial-of-service message attacks - [[Sean Morrison]]
* Support for -window on Mac command line executions - [[Sean Morrison]]
* Show slot numbers in lagstats (if admin) - Mark Thomas, Mike Weisenborn
* FPS limit energy saver option for laptops - Karsten Behrmann, [[Sean Morrison]]
* Send admin channel warning if /password fails - Garrett Padera, [[Jeff Myers]]
* Known players not authenticated are detected - [[Alfredo Tupone]]
* Added /checkip command - Frank Thilo
* "Enable Local Shot/Spawn Effects" affects "Driving with" - [[Daniel Remenak]]
* Show shot reload indicators when driving with a tank - [[Daniel Remenak]]
* Fix misc/bzfquery.pl to handle MsgGameTime - Tegan, Mark Thomas
* Simple server list searching - [[Daniel Remenak]]
* Added GUI option for email display length - Mark Thomas

==2.0.8==
BZFlag version 2.0.8 is a version of the BZFlag game that was released on 2006-05-13 under the title "Oops, Happy Mother's Day". It was a bug fix update from [[BZFlag 2.0.6]] primarily intended to fix a serious bug with HTTP connections on the server and client.

v.2.0.8 was replaced with [[BZFlag_2.0.10|v.2.0.10]] on 11/17/07.

v. 2.0.8 has a very short feature list:
*Add a plug-in to record matches - [[Jeff Myers]]
*Add an option to send out a UDP heartbeat message for observers behind flakey routers - [[Jeff Myers]]
*Replaced admin message sound - [[Sean Morrison]]
*Client and server now close http connections correctly - [[Daniel Remenak]]
*Fixed crash when rogue autopilot picks up a team flag - [[Daniel Remenak]]
*Fixed [[spawning|spawnpoint]] selection regression - [[Sean Morrison]]

==2.0.10==
BZFlag version 2.0.10 was a version of the BZFlag game for Windows and Mac OSX, released on 11/17/07.
It was released primarily to fix a number of small issues that have been found in 2.0.8 and provide good binary packages for the various Linux distributions for dual core and 64 bit systems.

* Added a work around for buggy DRI open source ATI drivers and the narrow flag - Jeff Myers
* Add /modcount command - Joshua Bodine, Anonymous
* Fix bug where users get locked into autopilot mode - Joshua Bodine
* Fix bug where poll results would not be announced - Joshua Bodine
* Fix antikill notice bug - Joshua Bodine
* Add -adminlagannounce and -lagannounce - Thomas Stauer
* Check for talk permission for part/quit messages - uso
* First map no longer ignored in Start Server menu - Ravu al Hemio
* Implemented Confine Mouse for Windows platforms - Daniel Remenak
* Implemented fullscreen->windowed mode toggle on Windows - Daniel Remenak
* Add the rabidRabbit plugin - LouMan
* Add packet loss kick and related admin commands - Thomas Stauer
* Reclaim lost memory from sound sample - Tupone Alfredo
* Fixed bashism on debian rules - Ryan Kavanagh
* Add the rabbitTimer plugin - L4m3r
* Fix some segfaults when re-joining - Tupone Alfredo
* Compliance with gcc-4.2 - Tupone Alfredo
* Fix the build system to be more distro friendly - Tupone Alfredo
* Plugins get flag resets/spawns/grab/drop/transfer - Jeff Myers, Bernt Hansen
* Fix compiler problem with gcc-4 - Tupone Alfredo
* Fixed high fps problem - Frank Thilo
* Added more info for observers - Jeff Myers, Frank Thilo
* torBlock plugin added - Jeff Myers, blast007
* Optionally use mesh position and height for radar - Thomas Stauer
* Add the regFlag plugin - Bernt Hansen
* Fix memory leak from cURL - blast007
* Add the Phoenix plugin - Jeff Myers
* Add favorite server - Frank Thilo
* SDL sound rate fix - Alfredo Tupone
* add bzID and server status to logDetail plugin - Bernt Hansen
* Add -tkannounce to announce tk on admin channel - Bernt Hansen
* Add the serverControl plugin - Bernt Hansen
* Add keepaway plugin - LouMan
* API calls to reset bzdb - Jeff Myers
* API call to get the player pause state. - Jeff Myers
* API calls to reload bans, and other files - Jeff Myers
* API event for shot ends - Jeff Myers
* API command to move a flag - Jeff Myers
* add API exposure for lag, jitter, and packetloss - Jeff Myers
* Add koth plugin - LouMan
* Add timedctf plugin - LouMan
* Add teamflagreset plugin - LouMan
* Add wwzones plugin - LouMan
* flagStay plugin added - Jeff Myers
* Give everyone notice of pause messages - Jeff Myers
* Fix for /silence command - Skeeve
* Fix mousebox edge positioning - Mark Thomas
* Fixed on spanish localization - xukosky@yahoo.es
* Instructions to fix sound on ALSA added - Tupone Alfredo
* Change filename format for easier location of matches - uso
* Adding jitter kick and related admin commands - Thomas Stauer
* Global banlist reload with local banlist - uso
* Fix to spawned and lag attributes in bz_updatePlayerData - Matthew Marshall
* Ability to change the killer in a PlayerDieEvent - Matthew Marshall
* Added shotID to bz_PlayerDieEventData - Matthew Marshall
* Expose the countdown and game time stuff to the api - Jeff Myers
* Backport the record stop function from 2.1 - Jeff Myers
* Backported WW GMs from 2.1 - Matthew Marshall
* Converts box & pyramids to mesh if required - Anonymous
* Allows leading face specification (x+,x-,y+,y-,z+,z-) - Anonymous
* Authorization is invariant to case - Anonymous

==2.0.12==
BZFlag version 2.0.12 was aversion of the BZFlag game for Linux and source packages released on 6/25/08.
It was released primarily to fix a small number of build issues on various linux distributions, most notibly Gentoo and Debian based systems. There are no new features from 2.0.10.

* Fix build with -ffast-math avoiding use of isnan for fog - Alfredo Tupone
* Fix for memory leaks -
* libGLEW requirement controlled by --with-glew - Alfredo Tupone
* Actually build with SDL_Image, if required - Alfredo Tupone
* Remove extra dir separator from cache entries - Jeff Myers
* Configurable "defaultFOV" (60 deg) for widescreen users - Jeff Myers
* Adjust shown coordinate for observers - Jeff Myers
* Use the foghack only if the config says - Jeff Myers
* Queue spawns after flag captures - Chris Wibble
* Fix kill callback when is coming from server - Jeff Myers
* Fix intermix of chat messages and api callback - Jeff Myers
* Various permission fixes - Jeff Myers
* Plugins path fixed -
* Kerberos and thread removed (never used) - Alfredo Tupone
* Event log fixed - Jeff Myers
* Workaroung to a driver bug - Jeff Myers
* Word filtering is case unsensitive -
* Correctly interface with c-ares 1.5.1 and lower - Alfredo Tupone
* Not showing a "new rabbit" message when player ID == NoPlayer - blast007
* gcc-4.3 fixes - Tim Riker, Alfredo Tupone
* MacOSX: Consistent search of resource files - Sean Morrison
* MacOSX: update the project to XCode 2.4.1 - Sean Morrison
* Added _countdownResumeDelay to control resume delay. - Thomas Stauer
* Slot numbers on scoreboard now appear regardless of hideAdmin - Joshua Bodine

==2.0.14==
BZFlag version 2.0.14 '''"This isn't the release you are looking for"''', was released on 02/15/2010.
It is being released primarily to fix a number of small issues that have been found in 2.0.12, and to replace the fonts due to licensing issues. The version is also being used to provide a set of binary updates for Windows and OSX, most notably support for Intel based Macintosh computers.

The version contains no new major features, but does have a few bugfixes and back-ports from Version 3.

* Add Options -> Display -> AntiFlicker option - trepan
* Add Options -> Input -> Confine Mouse (MotionBox) - trepan
* Adjust advanced ground rendering for texture flicker - trepan
* Change the default stencil bitplanes to 1 to fix stencil shadows and various other stencil features - trepan
* Backport fix for /idbanlist and /hostbanlist crashes - trepan
* Add support for gcc-4.4 and libtool-2.2 - Jeff Makey
* Update to Microsoft Visual C++ 9 from 8.0 - Jeff Myers
* Update to directInput 8 from 7 - Jeff Myers
* Fix player ghosting failure - Steven Mertens
* Provide API support for using bz_moveFlag on team flags - Scott Wichser
* Add pushstats plugin for future statistics gathering system - Jeff Myers
* Increase restrictions on incompletely joined players - Jeff Myers, Scott W.
* Announce saved file name in recordmatch plugin - Jeff Makey
* Fix buffer overflow in menu subsystem - Jeff Myers
* Fully support glob-style wildcards in hostbans and make name comparisons case insensitive - Bryan Jennings
* Properly limit maximum message size in /showgroup command - Jeff Makey
* Reset team scores in case of a capture during a countdown - Jeff Makey
* Block spoofed /me messages - Scott Wichser
* Keep flags within the world boundary - Jeff Makey
* Add the "roamView" BZDB variable - trepan
* Change fonts to DejaVu - Jeff Myers, Tim Riker
* Source cleanup - Tim Riker

==2.0.16==

BZFlag version 2.0.16 '''"No foolin"''', an an older version of the BZFlag game for Windows, Apple OSX, and Linux. It was released on 04/01/2010. (No it's not a joke, regardless of the release date.) It was released primarily to fix some build issues to allow inclusion in redhat based Linux distributions. Additional small security fixes have been added as well. The version is being used to provide a set of binary updates for Windows and OSX, most notably support for Intel based Macintosh computers.

The version contains no new major features.

* Fix command line options in Windows launcher - Scott Wichser
* Fix regression in protocol handling by server - Jeff Makey, Scott Wichser
* Add bullet tails as seen out the viewport - trepan
* Add observer mouse controls for roaming and tracking modes - trepan
* Add the /forceradar client-side command for observers - trepan
* Minor cleanup of source and build system - Jeff Makey
* Explicitly link to the dl library when needed - Jeff Makey
* Remove unused dependency on Xi library - Jeff Makey
* Clarify copyright assignment terms for developers - Jeff Myers
* Allow only one Enter message per player instance - Jeff Makey
* Add TimeLimit plugin - Steven Mertens
* Remove broken vocaliser and obsolete torBlock plugins - Jeff Myers

[[Category:Versions]]
[[Category:Releases]]

Server authentication

2025-11-02T07:33:17Z

Loymdayddaud: -publictitle, not -public; typo fix

==Overview==
Version 2.4 and later of the BZFlag server ([[BZFS]]) require an authentication key in order to list on the global public list server.

==Authentication==
Authentication is required in order to provide players and project staff members a point of contact for any issues or problems that may arise with the server when it is being run publicly.

Any server that uses the -publictitle option and contacts the project's public list server (http://my.bzflag.org/db/) will be required to provide an authentication key in order to show up on the list.

===The Key===
The authentication key is automatically generated by the Key management site, and is tied to a specific domain name, or IP address. Server owners simply have to log into the Key Manager and they can generate as many keys as they need. The key is effectively tied to a single server machine, but can be used with any number of BZFS instances on any number of ports.

Servers that do not have static IPs or domain names, should look at using one of the many free DNS name services that are available such as http://www.no-ip.com. Dynamic IPs will need new keys every time the address changes if a domain name is not used.

The key is numeric and will be completely unique. Keys are not valid for domain names or IP address that they were not created with.

===Key Management===
Key Management is handled by the website: http://my.bzflag.org/listkeys/. After logging in with a global username and password (forum login) server owners can enter as many domain names or IP addresses as they wish. Provide the key to bzfs using the "-publickey <key>" option.

==Questions==
'''Q)''' What happens if my key gets out?

'''A)''' Not much, the key is only valid for your server machine, so unless the user also has access to the same computer they can not use it.

'''Q)''' What if I run BZFS instances for other people?

'''A)''' Then you have 2 choices.
1) You can give out your key to your people and they can use it. This will make all servers show up as belonging to you.
2) You can tell your users to generate their own keys using the server address or domain name. Then each BZFS instance will be owned by each person.

'''Q)''' Does 2.0.x need a key?

'''A)''' No, 2.0.x servers do not need a key.

[[Category:Server]]

Creating a server

2025-11-02T07:30:48Z

Loymdayddaud: Use -publictitle instead of -public

Creating a server is the process of using [[BZFS]] software to host a game for users to play on.

==Overview==
Running a server can be done in both [[public]] or [[private]] modes. It involves running the server software [[BZFS]] on some host computer. For [[public]] servers this host computer must be connected to the internet, and be able to accept incoming connections on a fixed port.

== Planning a Server ==

Before you create a server, you need to decide what you want your server will be like. There are a few requirements in creating a server. First, you need a good connection. If you are on a high end DSL or higher connection you will be able to host a few players. With really fast connections, such as T1 or related, you could host dozens (although you may not want to do so).

You must provide an address to connect to. You will specify this address when you run the server (more on this below). The address may be your IP address (something like 192.12.193.123), or the domain name pointing to your computer (e.g. BZFlag.ducati.org). If your server is going to be on a machine that is connected via DSL or Cable, figure out if your provider is giving you a dynamic or a static IP. If the IP address is static, your life will be a little easier since you can specify that address once and forever. If the IP is dynamic, this means that your internet provider will change the address once in a while (without warning). In this case you probably want to "[[Alias Your IP Address]]" to a static name (click on the link for how to).

Next you need to have an idea of how your server is going to look: you are probably already familiar with the game style (CTF, Rabbit) from playing on existing servers. You may specify a map or ask your server to create a random one. You will also be able to specify many details of the game play (how many good and bad flags, jumping, ricochet, etc...). All of this is accomplished in the next step.

== Configure your Server ==

In this step, you specify all the server options. The cleanest way to accomplish this is to create a configuration file. Fortunately, the BZFlag installation provides you with a sample configuration file that you can modify according to your wishes. You will find this file in the directory where you installed BZFlag under a subdirectory called <code>misc</code>. The file is named <code>bzfs.conf</code>. Open <code>bzfs.conf</code> in a text editor (in windows, notepad will be just fine; in GNU/Linux, Unix, Debian, etc.. : vi would work nice).

Read through <code>bzfs.conf</code> to understand all the options. Remove the # sign on the lines corresponding to the options you want to set. Add # at the beginning of the line if you don't want that option. After you have finished your changes, you can save that file with a different name (this will be helpful if you want to run server with different configurations: just save many files with different names).

Note also that recent BZFlag installations come with a "nice" web-based configuration builder that lets you create a configuration using a simple web form. Run it by selecting "BZFS configuration builder" from the BZFlag folder in the start menu. Your web browser will pop up with a web form that will prompt you for several configuration choices. Please note that the form will not save the configuration file for you: you will still have to copy and paste the text generated by the web form into your configuration file.

Here is an incomplete list of things you must or can specify in the configuration file.

* Choose a password for administrative purposes. With this password, you can use the administrative operations, such as changing the lag kick threshold or setting environment variables. This is done by adding the following line to your configuration : <code>-passwd PASS</code> (replacing PASS with a password of your choice). Once the server is running, run your client and login as an administrator by entering "<code>/password PASS</code>" (without quotes "") as a chat message.
* If the server is to be public, you must specify the server people should connect to. The option is added with the following line "<code>-publicaddr server.name.com:5154</code>" (without quotes), or "<code>-publicaddr 111.111.111.111:5154</code>" where you should replace <code>111.111.111.111:5154</code> with your IP address. <code>5154</code> is the port the server will listen to. Make sure it is the same number as the one specified in a line starting with <code>-p 5154</code>. You can change the port but don't do that if you don't know what you are doing. We recommend you use port numbers that are proven to work in other servers.
* Specify other options. For example, if you want to allow jumping, then your conf file should have a line starting with <code>-j</code>. Other options are: ricochet, which needs a line starting with <code>+r</code>. Read through <code>bzfs.conf</code> and you'll find out how to specify the game style (rabbit, ctf, etc...), the number of flags, etc.... If you want to run different configurations you can create as many conf files as you like (with different names of course). Just specify the correct configuration file you want to invoke in the bat file mentioned in the previous paragraph. One of the options that you can set in the configuration file is a map the server should use.
* You can choose whether to use a custom map or a random one. If you use a random one, decide whether or not to include teleporters. If you want to include them, add (again, to your configuration) the option "<code>-t</code>". If you are playing CTF and you want a random map, use "<code>-cr</code>" instead of standard "<code>-c</code>", in addition to "<code>-t</code>". For a custom server, use: <code>-world "MAP_NAME"</code> ; replacing <code>MAP_NAME</code> with the file name of the map, which must be in the BZFS directory. You have probably seen that when you visit other server, one of the menus has the "save map" option. That means you can save that map for use on your server. Just save it somewhere in your pc, and specify the location of the map in the configuration file, next to the line that starts with <code>-world</code>
* You can choose the max number of players (for example <code>-mp 10</code> says there can't be more than 10 players). But just because you can host many, decide if you really want to. The more players on your server, the higher the overall latency will be and the more bandwidth your server will consume. Moreover, more than 4 players per team on a ctf or more than 6 players on a rabbit style is just not fun. Experiment if you plan to host a lot, otherwise don't worry. Not only latency that matters, but many players will make the field busy. Tanks will get killed often and there would be a lot of action. This is good, and bad. Good in that it is a lot of fun! But bad in that the average alive time may only be a few seconds.
* A server description would be nice. Note that there is a small limit on how many characters you can put for description, and it gets smaller based on how long the server address is. Add a description by adding option: <code>-publictitle DESCRIPTION</code>
* You can choose what flags, if any, to include or restrict. You must be familiar with the flag abbreviations, which are listed using command "<code>bzfs -help</code>" near the end of the help message. Add flags to the server using "<code>+f ABBR</code>" and restrict flags using "<code>-f ABBR</code>" replacing <code>ABBR</code> with the flag abbreviation.

This should get you started, but there are many more options you can set. Some of them are explained below in the section "Good Administration". In any event, most of the options can be understood by reading the file bzfs.conf provided with the installation.

== Getting your server on the public list ==

BZFlag has a central list server that keeps track of all the public servers. Using the <code>-publictitle "some text"</code> command line argument will tell your local server to attempt to register itself on the public server. This is normally all that is required to get your server listed.

The list server will need to be able to access your server just as other players will. This is done by connecting back to the public IP address where your server is running. The list server only checks the tcp connection back to your server at present, though players will also try udp on the same IP address and port number.

You can view the raw [http://my.bzflag.org/db/?action=LIST server list] in your web browser. If you do not see your server, then your server is firewalled or misconfigured and the list server cannot contact it. You will need to resolve this if you want your server to be publicly accessible.

Note: when you run the bzflag client on the same network as a server it should discover the server by using a broadcast ping. If your server shows up in the list, but without the description next to it, this means that you found it through broadcast discovery, and '''not from the public list server'''. If the server description that you included on the <code>-publictitle "this text"</code> command line option is there, then your server is correctly listed on the public server list.

Using multiple <code>-d</code> options to the server will result in some useful (and some useless) messages from the server.
{|
|
bzflag@phoenix:~/bzflag-1.10$ src/bzfs/bzfs -d -d -d -i 24.1.104.25 -p 51540 -publictitle "My Server Name"
style: 0
There is a voting arbiter with the following settings:
vote time is 60 seconds
veto time is 10 seconds
votes required are 3
vote percentage necessary is 50.099998
vote repeat time is 300 seconds
available voters is initially set to 200
Running a public server with the following settings:
public address is 24.1.104.25:51540
listening on 24.1.104.25:51540
with title of "My Server Name"
Sent ADD message to list server
GET /db/?action=ADD&nameport=24.1.104.25:51540&version=BZFS1910&gameinfo=0000000100000000000000000000c800c800c800c800c800c800c8&
build=1.10.7.20040809-RELEASE-linux-gnu&title=My+Server+Name HTTP/1.1
Host: my.BZFlag.org
Cache-Control: no-cache

Player [0] accept() from 24.1.104.25:50579 on 6
Player [0] on 6 removed: Disconnected
|}
* the -i parameter is used here to force an IP address. This server happens to have more than one IP address. This is not required on most servers.
* the -p parameter is used to pick a different port number than the default. If you are only running one server, it is recommended that you leave this off and use the default port number.
* notice the debug line that starts with "<code>GET</code>". This is the request that was sent to the bzflag list server to attempt to get listed
* notice the "<code>Player [0]</code>" lines. This indicates that the list server connected back and then disconnected. If you don't see this then it is likely that your server is firewalled and the list server is unable to connect back and so will '''not''' list your server.

== Running the server ==

There are different ways to run a server. On both Windows and *nix, the program (BZFS) is in the directory where you installed BZFlag (most likely: "<code>C:/Program Files/BZFlag2.4.8</code>", or on your usr account). The program containing the server is BZFS.exe. Double clicking on it will run a server with default options, but clearly you want to specify your own options, for example those you saved in the configuration file generated in the previous step. One way to do it is to specify all the commands for the server in a batch file, so you can just double click on it to start a server. On other systems such as Linux, create an executable with the commands, or a shell script, or see if there are any related ways to store console/text based command interface commands in a "shortcut" style.

On Windows: Here is a SampleBatchFile. Open notepad or any other text editor, copy the content of the file, make the changes that you need to change (notably: the location of BZFS and the config file bzfs.conf). Save the file with a nice name and extension .bat (for example: nicename.bat) on your desktop or a window of your choice. You probably understand what the batch file is doing: the lines beginning with "set" specify the content of some variables, such as the location of BZFS and the configuration files. The server is started on the line next to last (before "pause").

If you don't want to have a batch file or for some reason your batch file doesn't work, here is a procedure that always works: from the start menu in your windows machine, look for the "command prompt" and click on it. A black window will open up. Type: <code>cd "c:\Program Files\BZFlag2.4.8"</code> (this should work in most cases, unless you installed BZFlag in a different directory). Once you are there type: <code>bzfs -conf "C:\Program Files\BZFlag2.4.8\Data\bzfs.conf"</code> (change what is between quotes with the exact location of the configuration file).

On *nix: Use a config file, or a shell script. A config file can be made simply by taking all of your command line options you want to pass to BZFS, and placing them in a config file, one options on each line. An HTML file has been created that is shipped with BZFlag (in /data/ on binary releases, and in /misc/ in source releases or CVS). A shell script can be made the same way. A config file can be used, by changing directory to BZFS, and do "bzfs -conf CONF.conf", replacing CONF.conf with the config file in the same BZFS directory.

Once the server is running, log into it with your client and type /password PASS, where PASS is the password you chose in the configuration step. You'll be greeted by the client as an administrator. The KeysAndCommands and ServerCommands pages list a number of things you can do as an admin (although I don't think either of those pages is complete). If when you type one of those commands you get a "You do not have permission" message on client commands, it means that you forgot to login as admin (or somehow your login failed). Type in your client /password PASS replacing PASS with the password that you specified in the configuration phase. If this doesn't work shut down your server, go back to the configuration step and make sure you are getting the right password.

== Sharing Administration Status ==

Helpful links about this topic:

http://my.bzflag.org/bb/viewtopic.php?t=5960
and
http://my.bzflag.org/bb/viewtopic.php?t=6516

Sometimes people will want to share administrator status. Multiple people can be assigned permissions on a server, and all can do more than the normal DEFAULT group (general public). This allows a server to be better administrated, as when one admin is not watching it, another one can. So how do you do this? This is quite easy to do. First off, configure your server to accept group permissions. This is done through BZFS command "<code>-groupdb FILE</code>". This stores group names and permissions for that group. Its syntax for adding groups is: "GROUPNAME: permissions...", replacing GROUPNAME with the name of the group. Don't worry about adding ADMIN or DEFAULT groups, as those get thrown in automatically. Make one up, but please do not alter ADMIN group, as this is stuff administrators can do, and why limit yourself? Groupnames may not have spaces or quotes. Replace "permissions" with permissions, and take out the backslash in the command. For example, write "lagstats" instead of "/lagstats". So a sample line would be, "JRADMIN: playerlist ban kick". Separate permissions by a space, and DO NOT put permissions on different lines! Make sure the group name and ALL permissions are on the same line!

Now that you have your groups laid out, you must create a pas-swo-rd dat-ab-ase to store nicks and passwords created using "/register", as only registered users may be added to groups. To add people to a group, have them register, and enter BZFlag admin client command "/setgroup CALLSIGN GROUPNAME", replacing CALLSIGN with their callsign, case sensitive (add quotes around it if the callsign has spaces), and GROUPNAME with the name of the group to add them to. And that?s it! Easy as pie! This enables you to have multiple admins on one server. But what if you don't want other admins? Easy, create a smaller admin group, such as JRADMIN, in which they have more privileges than a normal person, but not as many as an admin. One privilege you MUST be very careful in giving a person is /shutdownserver. This is terrible if misused, as it kills the server. Trust wisely. And finally, if your server supports /report, starting in 1.11.*, people with privilege to "/viewreports" can see any reports filed, regardless of whether or not the person with that privilege has the computer that stores the reports.

== Shutting down your server ==

If you have had enough of your server, shut it down by entering /shutdownserver in the client. You can also just terminate BZFS execution, but this is not proper and takes a while for the client server list to realize it was terminated.

Now that the server is running, how does it work? Well, the BZFS window or execution must stay alive to keep the server alive. If you close the BZFS window or halt its execution, the server goes too. It will stay on the server list for a short time if halted suddenly.

Closing the server window, or halting its execution, is somewhat like turning off the power suddenly as a way to shutdown your computer - it is not proper, and is not recommended.

== Good Administration ==

Just because you have a server, that's not all. You must maintain it and keep your players satisfied. Check it often. One way to get feedback is to support the "/report" command.

Enable this using BZFS by setting the configuration option "-reportfile FILENAME" replacing FILENAME with a file to use to write reports to, or "-reportpipe FILENAME" replacing FILENAME with the file to pipe reports to. Reports are made through the client and are simply human messages.

But besides that, you must watch the people that come on your server. Often times people will pause or become "NR", not responding. "Not responding" means that they haven't sent a packet in a while (5 seconds by default). This happens to people with slow connections, or people with messed up connections because their connection simply can't send packets fast enough to be within the threshold. Usually they will be kicked automatically for idling too long, but if not, a kick is suitable. Take action against teamkillers (people who kill their own team on PURPOSE, not by occasional mistake), cheaters (a ban is usually nice :), people who log in/off constantly (people who constantly log on & off to reset their score, a warning is suitable), and any other nasty behavior.

You may want to implement a filter to filter chat or callsigns or both from abusive words. Make a file with a phrase/word that should be filtered on every line, and add it to the server using configuration option "-badwords FILE", replacing FILE with the file name IN QUOTES that is found in the BZFS directory. Then set whether to filter chat, callsigns, or both using "-filterCallsigns" and/or "-filterChat". Sometimes, BZFS will be too strict and filter things that aren't bad. You can make simple exact matches happen using "-filterSimple".

So you have a filter, but what if a bad person comes on? Take reasonable action, a warning to start, a permanent ban at worst. Punishment severity is, in order, a warning (use the chat), a kick (/kick REASON), a temporary ban (/ban IP DURATION REASON), and a permanent ban (/ban IP REASON). IP is delinquent's IP address (found using "/playerlist" admin command), DURATION is the amount of time in minutes (do not put a number alone if to ban forever), and REASON is an optional text string of the reason, which will be sent to the player and recorded in your logs. If you want to just kick a person off the server temporarily, use "/kick REASON", replacing REASON with an optional text string of the reason why. If you want bans to last after you shut down or restart your server, make sure you specified a [[ban file]], which is a file that BZFS can store banned IPs in, using BZFS command-line option "-banfile FILE", where FILE is the name of the file in the BZFS directory.

== World Files ==

World files should have the ".bzw" file extension and be in [[BZW]] format. If world files live in the "<code>worlds</code>" directory under the config directory they will be usable when you start a simple server from inside the client. You should not use this method to run a dedicated server, just for starting a LAN game etc. The "<code>worlds</code>" directory is located:

* "~/.bzf/worlds/" - on Linux and Unix Systems.
* "My Documents\My BZFlag Files\worlds\" - on Microsoft Windows.
* "~/Library/Application Support/BZFlag/worlds" - on Apple Mac OS X.

== Other Information ==

BZFlag has not been carefully audited for buffer overflows and other remote attacks, however, large packets or suspicious packets make the server kick the player that sent it. You should never trust the server to be your guard. It's a good idea to run your BZFlag server as a user with minimal permissions on your machine and to run it in a [[BZFS in a chroot jail|chroot jail]].

== Regarding "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, the project administration asks that users do not publish or host "cheat" type clients or servers. These cheats ruin the game for the average player, when they are mixed in with the normal game servers and clients. We understand the desire to expand and modify the game and its sources, so it is requested that anyone wishing to run a game that uses modified code or logic to do so using a different network protocol than the current public release. This will let modified games be played, and prevent modified clients from being used on public unmodified games, as they would be incompatible. The BZFlag project administrators reserve the right to remove the public listings of any game servers that do not adhere to this rule. Administrators also reserve the right to remove any global accounts or access to public services at any time.

==See also==
* [[Slash Commands]]
* [[Server Variables]]
* [[BZFS in a chroot jail]]
* [[Known Cheats]]
* [[Rotating Maps]]

==External Links==
http://my.bzflag.org/bb/viewtopic.php?t=2915 post on the BZFlag Forums

[[Category:Server]]
[[Category:Support]]
[[Category:Tutorials]]

BZFS

2025-11-02T07:20:05Z

Loymdayddaud: typo fixes

''This is an article specifically about the BZFS program. For general information on creating a BZFlag server, see [[Creating a server]].''

BZFS is name of the [[BZFlag]] server application. It is a command line application that can either be run manually or started from within the game. The server supports a large list of [[BZFS Command Line Options|command line options]] that can be used. All BZFlag games are hosted on BZFS servers, there is no 'single player' game that is run with only a client.

==Public Vs. Private Servers==
BZFS can be run in ether a public or private mode. Public servers are listed with the central [[List Server]] system and can take advantage of the [[Global Registration]] system for user management. Private servers will only be visible on the LAN they are started on. The in-game server menu can only start private servers.

==Command line options and Config files==
BZFS uses [[BZFS Command Line Options|command line options]] to set the various modes and options for a game. These options can be specified from the command line prompt of the host OS or inside a plain text configuration file. The path (relative or absolute) to the config file is specified with the '''-conf''' option.

See the [[Sample_conf|sample configuration]] for some examples of command line options. However, it is recommended that you create a configuration file from scratch, and test it every few lines. This will help in the case of configuration errors as you will have only modified a few lines that introduced the error.

==World Files==
BZFS can read in [[BZW]] formatted map files and use them to define the 3D world the game is played in.

==Plug-ins and the BZFS API==
BZFS can be extended by the use of server side [[Plug-ins]]. These [[Plug-ins]] are runtime loaded DLLs/SO files that use the [[BZFS API]] to modify and automate various game logic and settings.

==See also==
* [[BZFS Command Line Options]]
* [[BZFS API]]
* [[Plug-ins]]
* [[Sample conf|Sample Config File]]

[[Category:Server]]

Single Player Mode

2025-11-02T05:11:41Z

Loymdayddaud: add limit information

Single Player Mode is a term (misnomer) often used to describe the act of playing BZFlag on a local server using the computer-controlled player (bots) of a client. BZFlag itself is designed to be a multiplayer game.

=Overview=
Using bots on a local server is a way to play the game without an internet connection, or to gain experience in playing without the need for other human players. Bots are currently only run by the game client and can be run on any server. The term "Single Player Mode" is most commonly used to describe a single client that is logged in to a local server with a number of bots. It is mostly used to test maps, as the simple robots do not offer any real gameplay challenge.

Bots can be used on remote servers, but many of the owners of public servers do not allow bots to join with players. Use of bots on public servers is not recommended and can lead to being banned from the server.

=Starting a Single Player Session=
The basic idea behind starting a single player session is the following.
#Start a local server, ether by using the in-game menu, or via the command line.
#Start the game client using the '''-solo''' [[BZFS Command Line Options| command line option]].
#Join the local server using the client and begin play.

==Starting a local server==
The simplest way to start a local server is to use the in-game '''Start Server''' menu. This menu is found on the [[Join Game Menu]] at the very bottom. This menu gives a number of settings for the server, including shot counts, and world options such as [[jumping]] and [[ricochet]]. Specific flags or more advanced options can not be set via the '''Start Server''' menu.

To set additional options one must run [[BZFS]] manually and enter in a number of [[BZFS Command Line Options| command line options]]. See [[Creating A Server|creating a server]] for more options. To keep the server local, do not use the '''-public''' option.

==Starting the client with bots==
The game client must be started with a command-line option to enable bots. Bots can not be enabled from within the game menus.

===Linux and Unix===
On Linux or other Unix-like systems the game client can be started with command line options directly from the terminal.
{|
|
bzflag -solo ##
|}
Where <nowiki>##</nowiki> is the number of bots you want to run. Note that there is a limit of 40 bots per command.

===Microsoft Windows===
Microsoft Windows users can follow the following steps to create a shortcut that starts the game client with bots.
# Locate the BZFlag shortcut installed in the programs section of the start menu.
# Drag the BZFlag shortcut with the right mouse button on to the desktop.
# Pick the "Copy here" item from the context menu that pops up when the drag is complete.
# Click on the Copied shortcut with the right mouse button and pick the "properties" item.
# Find the "Target" field in the shortcut properties window that is opened, and click in it.
# Use the right arrow key to find the end of the text in the target field. It will end in bzflag.exe".
# After the last quote(") add a space and then '''-solo''' <nowiki>##</nowiki>. Where <nowiki>##</nowiki> is the number of bots you wish to have. Note that there is a limit of 40 bots per command.
# Save the changes by hitting the OK button at the bottom.

Running this shortcut will now start the server with bot support.

===Mac OS X===
The Mac OS X method for starting the game with bot support is the same as the Linux method, but the path to the bzflag client is required. If you installed BZFlag in your applications folder, then the command that needs to be typed into terminal will be along the lines of:
{|
|
/Applications/BZFlag.app/Contents/MacOS/bzflag -solo <nowiki>##</nowiki>
|}
Where <nowiki>##</nowiki> is the number of bots you want to run. Note that there is a limit of 40 bots per command.

==Joining the Local Server==
Once the client is started with bot support you must do the following to join the local server
# Go to the Join Game menu.
# Enter "127.0.0.1" in the server name field. This is called "localhost".
# Enter "5154" in the port field.
# Choose the "Connect" item to join the server.

This will connect to the local server with the number of bots specified to with the '''-solo''' option.

=Autopilot=
The aforementioned bot method creates what may be called 'simple' bots, which simply shoot and attempt to dodge bullets.
A feature called autopilot, is activated when you press the "9" key on your keyboard while in-game, although as stated earlier, many servers do not allow this.
Some players may decide they want to open up 5 or 10 clients and place them on autopilot. When they do, it allows them to be able to jump, grab flags, and are slightly smarter than the 'simple' bots.

==See also==
* [[Creating A Server]]
* [[BZFS Command Line Options]]

[[Category:Concepts]]
[[Category:Client]]
[[Category:Tutorials]]

Meshbox

2025-11-02T05:08:37Z

Loymdayddaud: we also need periods

The meshbox is the 2.0 update to the original [[box]] object in BZFlag 1.0. The main difference between the [[box]] and the Meshbox is that the meshbox supports new features in BZFlag 2.0, such as physics drivers and textures.

==Code==
A very basic meshbox will include:
{|
|
meshbox
position 0 0 0 # x-pos, y-pos, height
rotation 0 # rotation in degrees
size 10 10 10 # x-len, y-len, height
end
|}

As with the [[box]] object, position defines where the meshbox should be located. Rotation defines the angle it should be rotated to (about the Z-axis), and size defines how big or small the object should be. Now, if you're looking for something a little fancier, you can try code similar to this:

{|
|
meshbox
name example
position 0 0 0
rotation 0
size 10 10 10
shift 0 0 0
shear 0 0 0
scale 0 0 0
spin 0 0 0 0
outside matref my_cool_wall
top matref my_cool_roof
phydrv example_physics
drivethrough
shootthrough
passable
end
|}

Valid parameters for a meshbox are:
{|{{Prettytable}}
|-
| {{Hl3}} |'''Parameter'''
| {{Hl3}} |'''Description'''
|-
| '''name''' || defines the name of meshbox, often unused.
|-
| '''position''' || defines the position of the meshbox in X-pos, Y-pos and the height of the meshbox in Z.
|-
| '''rotation''' || defines a rotation around the Z axis for the meshbox, in degrees.
|-
| '''size''' || defines the distance from the center to the side of the meshbox in X and Y, and the total height of the meshbox in Z.
|-
| '''shift''' || shift the meshbox (repeatable).
|-
| '''shear''' || (repeatable).
|-
| '''scale''' || defines the scale of the meshbox in x,y, and z, 1 is the default, lower values make it smaller (repeatable).
|-
| '''spin angle''' || rotate the meshbox around a vector by angle. The vector <nx, ny, nz> must be a unit vector. Because the BZFlag client doesn't clip objects against the ground, it is advisable to ensure that the meshbox is rotated up and away from the ground. Otherwise, the meshbox will appear to be super-imposed on the ground, rather than embedded into it. (repeatable).
|-
| '''phydrv''' || reference to a predefined [[physics|physics driver]].
|-
| '''matref''' || reference to a predefined [[material]].
|-
| '''drivethrough''' || tanks will pass through this object as if it does not exist.
|-
| '''shootthrough''' || shots will pass through this object as if it does not exist.
|-
| '''passable''' || both tanks and shots will pass through this object. This is the same as specifying both drivethrough and shootthrough.
|}

So what's the difference here? Well, this object will be treated as an obstacle. The outside walls (as opposed to inside, top, or bottom) will appear with the "my_cool_wall" [[material]], and the roof (top) will have "my_cool_roof." Of course, if you want a [[material]] on all sides of the object, you can simply omit the "top" specification at the start of the line, and simply have: "matref my_cool_material." Also, you can specify a [[Physics | physics driver]] to the object, to influence tank behavior a bit.

==Appearance==
By default, a meshbox will have red brick walls, and a grey stone roof. However, if a [[material]] is specified by the map creator, the appearance depends on the designer's choosing. Contrary to a [[Box]], a height 0 meshbox at ground level ''is not'' visible.

==History==
The meshbox was added in [[BZFlag 2.0.0]].

==Editor Support==
The meshbox IS supported by [[pyBZEdit]], [[Blender]] with the [[BZWTools]] plugin, and [[Wings3D]]. The meshbox is NOT supported by [[BZEdit]], [[IBZEdit]] or [[BZFed]].

[[Category:Map Making]]
[[Category:Map_Objects]]

Meshbox

2025-11-02T05:08:11Z

Loymdayddaud: we don't need this text bolded

The meshbox is the 2.0 update to the original [[box]] object in BZFlag 1.0. The main difference between the [[box]] and the Meshbox is that the meshbox supports new features in BZFlag 2.0, such as physics drivers and textures.

==Code==
A very basic meshbox will include:
{|
|
meshbox
position 0 0 0 # x-pos, y-pos, height
rotation 0 # rotation in degrees
size 10 10 10 # x-len, y-len, height
end
|}

As with the [[box]] object, position defines where the meshbox should be located. Rotation defines the angle it should be rotated to (about the Z-axis), and size defines how big or small the object should be. Now, if you're looking for something a little fancier, you can try code similar to this:

{|
|
meshbox
name example
position 0 0 0
rotation 0
size 10 10 10
shift 0 0 0
shear 0 0 0
scale 0 0 0
spin 0 0 0 0
outside matref my_cool_wall
top matref my_cool_roof
phydrv example_physics
drivethrough
shootthrough
passable
end
|}

Valid parameters for a meshbox are:
{|{{Prettytable}}
|-
| {{Hl3}} |'''Parameter'''
| {{Hl3}} |'''Description'''
|-
| '''name''' || defines the name of meshbox, often unused.
|-
| '''position''' || defines the position of the meshbox in X-pos, Y-pos and the height of the meshbox in Z.
|-
| '''rotation''' || defines a rotation around the Z axis for the meshbox, in degrees.
|-
| '''size''' || defines the distance from the center to the side of the meshbox in X and Y, and the total height of the meshbox in Z.
|-
| '''shift''' || shift the meshbox (repeatable).
|-
| '''shear''' || (repeatable).
|-
| '''scale''' || defines the scale of the meshbox in x,y, and z, 1 is the default, lower values make it smaller (repeatable).
|-
| '''spin angle''' || rotate the meshbox around a vector by angle. The vector <nx, ny, nz> must be a unit vector. Because the BZFlag client doesn't clip objects against the ground, it is advisable to ensure that the meshbox is rotated up and away from the ground. Otherwise, the meshbox will appear to be super-imposed on the ground, rather than embedded into it. (repeatable).
|-
| '''phydrv''' || reference to a predefined [[physics|physics driver]].
|-
| '''matref''' || reference to a predefined [[material]].
|-
| '''drivethrough''' || tanks will pass through this object as if it does not exist
|-
| '''shootthrough''' || shots will pass through this object as if it does not exist
|-
| '''passable''' || both tanks and shots will pass through this object. This is the same as specifying both drivethrough and shootthrough
|}

So what's the difference here? Well, this object will be treated as an obstacle. The outside walls (as opposed to inside, top, or bottom) will appear with the "my_cool_wall" [[material]], and the roof (top) will have "my_cool_roof." Of course, if you want a [[material]] on all sides of the object, you can simply omit the "top" specification at the start of the line, and simply have: "matref my_cool_material." Also, you can specify a [[Physics | physics driver]] to the object, to influence tank behavior a bit.

==Appearance==
By default, a meshbox will have red brick walls, and a grey stone roof. However, if a [[material]] is specified by the map creator, the appearance depends on the designer's choosing. Contrary to a [[Box]], a height 0 meshbox at ground level ''is not'' visible.

==History==
The meshbox was added in [[BZFlag 2.0.0]].

==Editor Support==
The meshbox IS supported by [[pyBZEdit]], [[Blender]] with the [[BZWTools]] plugin, and [[Wings3D]]. The meshbox is NOT supported by [[BZEdit]], [[IBZEdit]] or [[BZFed]].

[[Category:Map Making]]
[[Category:Map_Objects]]

Meshbox

2025-11-02T05:07:44Z

Loymdayddaud: Add drivethrough, shootthrough, and passable

The meshbox is the 2.0 update to the original [[box]] object in BZFlag 1.0. The main difference between the [[box]] and the Meshbox is that the meshbox supports new features in BZFlag 2.0, such as physics drivers and textures.

==Code==
A very basic meshbox will include:
{|
|
meshbox
position 0 0 0 # x-pos, y-pos, height
rotation 0 # rotation in degrees
size 10 10 10 # x-len, y-len, height
end
|}

As with the [[box]] object, position defines where the meshbox should be located. Rotation defines the angle it should be rotated to (about the Z-axis), and size defines how big or small the object should be. Now, if you're looking for something a little fancier, you can try code similar to this:

{|
|
meshbox
name example
position 0 0 0
rotation 0
size 10 10 10
shift 0 0 0
shear 0 0 0
scale 0 0 0
spin 0 0 0 0
outside matref my_cool_wall
top matref my_cool_roof
phydrv example_physics
drivethrough
shootthrough
passable
end
|}

Valid parameters for a meshbox are:
{|{{Prettytable}}
|-
| {{Hl3}} |'''Parameter'''
| {{Hl3}} |'''Description'''
|-
| '''name''' || defines the name of meshbox, often unused.
|-
| '''position''' || defines the position of the meshbox in X-pos, Y-pos and the height of the meshbox in Z.
|-
| '''rotation''' || defines a rotation around the Z axis for the meshbox, in degrees.
|-
| '''size''' || defines the distance from the center to the side of the meshbox in X and Y, and the total height of the meshbox in Z.
|-
| '''shift''' || shift the meshbox (repeatable).
|-
| '''shear''' || (repeatable).
|-
| '''scale''' || defines the scale of the meshbox in x,y, and z, 1 is the default, lower values make it smaller (repeatable).
|-
| '''spin angle''' || rotate the meshbox around a vector by angle. The vector <nx, ny, nz> must be a unit vector. Because the BZFlag client doesn't clip objects against the ground, it is advisable to ensure that the meshbox is rotated up and away from the ground. Otherwise, the meshbox will appear to be super-imposed on the ground, rather than embedded into it. (repeatable).
|-
| '''phydrv''' || reference to a predefined [[physics|physics driver]].
|-
| '''matref''' || reference to a predefined [[material]].
|-
| '''drivethrough''' || tanks will pass through this object as if it does not exist
|-
| '''shootthrough''' || shots will pass through this object as if it does not exist
|-
| '''passable''' || both tanks and shots will pass through this object. This is the same as specifying both '''drivethrough''' and '''shootthrough'''
|}

So what's the difference here? Well, this object will be treated as an obstacle. The outside walls (as opposed to inside, top, or bottom) will appear with the "my_cool_wall" [[material]], and the roof (top) will have "my_cool_roof." Of course, if you want a [[material]] on all sides of the object, you can simply omit the "top" specification at the start of the line, and simply have: "matref my_cool_material." Also, you can specify a [[Physics | physics driver]] to the object, to influence tank behavior a bit.

==Appearance==
By default, a meshbox will have red brick walls, and a grey stone roof. However, if a [[material]] is specified by the map creator, the appearance depends on the designer's choosing. Contrary to a [[Box]], a height 0 meshbox at ground level ''is not'' visible.

==History==
The meshbox was added in [[BZFlag 2.0.0]].

==Editor Support==
The meshbox IS supported by [[pyBZEdit]], [[Blender]] with the [[BZWTools]] plugin, and [[Wings3D]]. The meshbox is NOT supported by [[BZEdit]], [[IBZEdit]] or [[BZFed]].

[[Category:Map Making]]
[[Category:Map_Objects]]

Plug-ins

2025-11-02T05:04:33Z

Loymdayddaud: Add section on Plug-in Development

BZFS can be built to support the loading of external libraries as plug-ins. These plug-ins can alter or replace the logic applied by the server, as well as automate many common tasks.

Plug-ins are one of the more popular ways to apply modifications to the game. They do not require modifications of the BZFS application source code so it can be kept up to date with out the need to constantly apply patches. They have also proven to be a very simple method for distributing modifications from developers to players.

==Overview==
Plug-ins are compiled dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On [http://www.microsoft.com/windows Microsoft Windows] they are built as [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] files. On MacOS they are built as .dylib files. On [http://www.linux.org Linux] and other [http://www.unix.org/ Unix]-like systems they are built as .so files.

==Use==
Plug-ins are loaded at startup by the '''-loadplugin''' option, or at run time with the ''/loadplugin'' command. If the full path to the plug-in is not specified, then [[BZFS]] will search a number of known sub directories for the plug-in as it attempts to load it. Using a valid path to the plug-in on load is highly recommended. While playing, all plug-ins loaded onto the server are visible with the /listplugins command.
===Parameters===
Some plug-ins take parameters that are passed to the plug-in on load. This is often a numeric value, or a path to a file. To pass a parameter to a plug-in, simply add a ',' after the plug-in name or path, and then add the parameter. Parameters can not have spaces, due to the way [[BZFS]] parses command line options and / commands.

On load, plug-ins install a number of callbacks and event handlers with the hosting [[BZFS]] that are called when specific events happen. This allows the plug-in to perform additional actions on these events, or if need be, alter the results of the default logic of the server.
===Search Paths===
[[BZFS]] searches for plug-ins in two standard locations: the config directory and the global plug-ins directory. The config directory is where the BZFlag config.cfg file is located, and the global plug-ins directory is $(prefix)/lib/bzflag/.

==BZFS API==
All plug-ins are linked to the [[BZFS API]]. This programing layer provides the interface to the BZFS application. All events and functions that a plug-in can call are in the [[BZFS API]].

==Standard plug-ins==
The [[BZFlag Source]] distribution contains a number of plug-ins that are maintained by the project [[:Category:Developer|developers]].
These plug-ins are located in the ''/plugins'' directory.

{{Template:Plug-in list}}

==Third Party Plug-ins==
A number of non-developers have created plug-ins for BZFS, and usually release them on the [https://forums.bzflag.org/ BZFlag Forums].

=== On Linux ===

Here are the steps to compile a hypothetical third party plug-in named "Example":

==== For versions older than 2.4.3 ====

# In the plugins directory of the BZFlag source tree run the command '''./newplug.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplug.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# In the top-level BZFlag source directory run '''autogen.sh''', '''configure''', and '''make''' as usual

==== For versions on or after 2.4.3 ====

# Store the distributed plugin files into the plugins/''Example'' directory
# In the top-level BZFlag source directory run:
<div style="margin-left: 45px;">
./autogen.sh
./configure --enable-custom-plugins=''Example''
./make

Note that you can use a comma-separated list to specify multiple plugins to be built:
./configure --enable-custom-plugins=''Example'',''AnotherExample'',''AnotherPlugin''
</div>
When that finishes successfully the plug-in should be ready to use as described above.

=== On Mac OS X ===

In Xcode on Mac OS X, follow these instructions:

# Create a new target for your plug-in.
#* '''Xcode 5 (and below)''': Click on the BZFlag project name in the project navigator. Click Add Target, and create a new C/C++ Library. Name the plugin, and select "Dynamic" for type.
#* '''Xcode 6''': Click on the BZFlag project in the project navigator. Go the File > New > Target. When prompted for the template for the target, under the "OS X" section, select the "Framework & Library" section and finally select "Library." In the next dialog, select "None (Plain C/C++ Library)" for the Framework and "Dynamic" for the type.
# In the project navigator, move the new library target from the bottom of the screen into the "Targets" group.
# Click on the BZFlag project name in the project navigator again. In the list of targets, select the BZFlag application target. In the Build Phases tab, in the Target Dependencies pane, add your new library target as a dependency of the application target. Also add it to the Copy Files phase for the PlugIns directory.
# Select your new library target. Select the Build Settings tab, and locate the Other Linker Flags option. Add the option "-undefined dynamic_lookup"
# Find the Architecture build setting for your new library. Make sure it is the same architecture as the main codebase, or click Levels, click the Architecture setting under your library target, click Other, and delete the setting. This will make it assume the overall project build architecture.
# If your plug-in uses "plugin_utils.h", then ensure that under Build Phases the '''libplugin_utils.a''' library is listed under "Link Binary With Libraries"; add the library if it is not already listed.
# Find the Executable Prefix build setting for your new library, and delete the "lib" setting.
# Add your source file(s) to the project, and make them members of your library target; ensure you select the "Copy items if needed" checkbox and to choose "Create groups."
# Build as usual.

==Preparing a Linux BZFS==

In order to run plugins in BZFS, you need to recompile it with the --enable-shared option on the configure script.

''Note that as of 2.4.0 the BZFlag configuration has --enable-shared automatically enabled.''

$ ./configure --enable-shared --disable-client;
make;
make install;

==Plug-in Development==
To begin a plugin, use [https://bzflag-plugin-starter.allejo.org/ allejo's plugin skeleton generator] to create the initial logic.
Next, look at the [https://bzflag.org/documentation/developer/bzfs_api documentation] and update the event portion of your plugin to perform the desired behavior. A tutorial on creating plugins can be found [https://allejo.io/anthologies/ here].
Note that the plugin generator adds '''const char *config''' to your plugin Init function. Unless you want command-line options for your plugin, this can be commented out.

==History==
The plug-in system was added in BZFlag v. 2.0.4 and was initially met with a lukewarm reception by some of the core developers and the maintainer. The community has since embraced the concept and built a multitude of useful modifications, many that have been incorporated into the project as standard plug-ins.

For Version 3.0 major changes to the [[BZFS API]] have been made to increase its lifespan.

[[Category:Server]]
[[Category:Development]]
[[Category:Plug-Ins]]

Plug-ins

2025-11-02T04:52:04Z

Loymdayddaud: Small update

BZFS can be built to support the loading of external libraries as plug-ins. These plug-ins can alter or replace the logic applied by the server, as well as automate many common tasks.

Plug-ins are one of the more popular ways to apply modifications to the game. They do not require modifications of the BZFS application source code so it can be kept up to date with out the need to constantly apply patches. They have also proven to be a very simple method for distributing modifications from developers to players.

==Overview==
Plug-ins are compiled dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On [http://www.microsoft.com/windows Microsoft Windows] they are built as [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] files. On MacOS they are built as .dylib files. On [http://www.linux.org Linux] and other [http://www.unix.org/ Unix]-like systems they are built as .so files.

==Use==
Plug-ins are loaded at startup by the '''-loadplugin''' option, or at run time with the ''/loadplugin'' command. If the full path to the plug-in is not specified, then [[BZFS]] will search a number of known sub directories for the plug-in as it attempts to load it. Using a valid path to the plug-in on load is highly recommended. While playing, all plug-ins loaded onto the server are visible with the /listplugins command.
===Parameters===
Some plug-ins take parameters that are passed to the plug-in on load. This is often a numeric value, or a path to a file. To pass a parameter to a plug-in, simply add a ',' after the plug-in name or path, and then add the parameter. Parameters can not have spaces, due to the way [[BZFS]] parses command line options and / commands.

On load, plug-ins install a number of callbacks and event handlers with the hosting [[BZFS]] that are called when specific events happen. This allows the plug-in to perform additional actions on these events, or if need be, alter the results of the default logic of the server.
===Search Paths===
[[BZFS]] searches for plug-ins in two standard locations: the config directory and the global plug-ins directory. The config directory is where the BZFlag config.cfg file is located, and the global plug-ins directory is $(prefix)/lib/bzflag/.

==BZFS API==
All plug-ins are linked to the [[BZFS API]]. This programing layer provides the interface to the BZFS application. All events and functions that a plug-in can call are in the [[BZFS API]].

==Standard plug-ins==
The [[BZFlag Source]] distribution contains a number of plug-ins that are maintained by the project [[:Category:Developer|developers]].
These plug-ins are located in the ''/plugins'' directory.

{{Template:Plug-in list}}

==Third Party Plug-ins==
A number of non-developers have created plug-ins for BZFS, and usually release them on the [https://forums.bzflag.org/ BZFlag Forums].

=== On Linux ===

Here are the steps to compile a hypothetical third party plug-in named "Example":

==== For versions older than 2.4.3 ====

# In the plugins directory of the BZFlag source tree run the command '''./newplug.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplug.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# In the top-level BZFlag source directory run '''autogen.sh''', '''configure''', and '''make''' as usual

==== For versions on or after 2.4.3 ====

# Store the distributed plugin files into the plugins/''Example'' directory
# In the top-level BZFlag source directory run:
<div style="margin-left: 45px;">
./autogen.sh
./configure --enable-custom-plugins=''Example''
./make

Note that you can use a comma-separated list to specify multiple plugins to be built:
./configure --enable-custom-plugins=''Example'',''AnotherExample'',''AnotherPlugin''
</div>
When that finishes successfully the plug-in should be ready to use as described above.

=== On Mac OS X ===

In Xcode on Mac OS X, follow these instructions:

# Create a new target for your plug-in.
#* '''Xcode 5 (and below)''': Click on the BZFlag project name in the project navigator. Click Add Target, and create a new C/C++ Library. Name the plugin, and select "Dynamic" for type.
#* '''Xcode 6''': Click on the BZFlag project in the project navigator. Go the File > New > Target. When prompted for the template for the target, under the "OS X" section, select the "Framework & Library" section and finally select "Library." In the next dialog, select "None (Plain C/C++ Library)" for the Framework and "Dynamic" for the type.
# In the project navigator, move the new library target from the bottom of the screen into the "Targets" group.
# Click on the BZFlag project name in the project navigator again. In the list of targets, select the BZFlag application target. In the Build Phases tab, in the Target Dependencies pane, add your new library target as a dependency of the application target. Also add it to the Copy Files phase for the PlugIns directory.
# Select your new library target. Select the Build Settings tab, and locate the Other Linker Flags option. Add the option "-undefined dynamic_lookup"
# Find the Architecture build setting for your new library. Make sure it is the same architecture as the main codebase, or click Levels, click the Architecture setting under your library target, click Other, and delete the setting. This will make it assume the overall project build architecture.
# If your plug-in uses "plugin_utils.h", then ensure that under Build Phases the '''libplugin_utils.a''' library is listed under "Link Binary With Libraries"; add the library if it is not already listed.
# Find the Executable Prefix build setting for your new library, and delete the "lib" setting.
# Add your source file(s) to the project, and make them members of your library target; ensure you select the "Copy items if needed" checkbox and to choose "Create groups."
# Build as usual.

==Preparing a Linux BZFS==

In order to run plugins in BZFS, you need to recompile it with the --enable-shared option on the configure script.

''Note that as of 2.4.0 the BZFlag configuration has --enable-shared automatically enabled.''

$ ./configure --enable-shared --disable-client;
make;
make install;

==Plug-in Development==
{{DoDoc|Describe the basics of plug-in development.}}

==History==
The plug-in system was added in BZFlag v. 2.0.4 and was initially met with a lukewarm reception by some of the core developers and the maintainer. The community has since embraced the concept and built a multitude of useful modifications, many that have been incorporated into the project as standard plug-ins.

For Version 3.0 major changes to the [[BZFS API]] have been made to increase its lifespan.

[[Category:Server]]
[[Category:Development]]
[[Category:Plug-Ins]]

User:Loymdayddaud

2025-11-02T04:48:40Z

Loymdayddaud: Create userpage

A relatively new BZFlag player who joined in 2023. Has created several plugins and maps.

BZFS API Functions

2025-11-02T04:45:39Z

Loymdayddaud: Add link to main website documentation

<b>Note:</b> The most up-to-date information on this subject can be found here: https://www.bzflag.org/documentation/developer/bzfs_api/functions/

A comparison and overview of BZFS API Functions.

{|{{Prettytable}}
|-
| {{Hl3}} |'''BZFS API Function'''
| {{Hl3}} |'''Description'''
|-
| [[bool bz fileReport]] || API function will file a report message to the report channel.
|-
| [[bz addURLJob]] || This function is used to send out HTTP requests from bzfs to external websites. It can be used to send data to a site, or request data from a site. It will transfer the data in the background and call the handler parameter as the data is updated.
|-
| [[bz_BZDBItemExists]] || This function checks to see if a BZDB variable exists.
|-
| [[bz_cancelCountdown]] || This function stops the countdown before a match has been started.
|-
| [[bz_canPlayerSpawn]] || This function returns true if the specified player is allowed to spawn, false if they are not.
|-
| [[bz debugMessage]] || This function prints a standard debug message.
|-
| [[bz debugMessagef]] || This function outputs a debug message to.
|-
| [[bz_deleteIntList]] || This function deletes the bz_APIIntList given freeing up memory.
|-
| [[bz fireWorldGM]] || This function fires a Guided Missile at a player.
|-
| [[bz fireWorldWep]] || This API function will fire w worldweapon at the specified location with the specified parameters.
|-
| [[bz flagPlayer]] || This API function returns the ID of the player that is carrying the specified flag. If the flag is on the ground, it will return -1.
|-
| [[bz_freePlayerRecord]] || This API function frees the player record specified. This should be called on each player record after it's no longer needed, to release the memory used by that player record.
|-
| [[Bz gameOver]] || This API function creates a Game Over, announcing the players and/or team(s) specified as the winner.
|-
| [[bz_getAdmin]] || This API function checks to see if the specified player is an administrator (has the ability to ban).
|-
| [[bz_getBZDBBool]] || This API function gets the value of a variable. (ex. _shotsKeepVerticalVelocity, _speedChecksLogsOnly, ect)
|-
| [[bz_getBZDBDouble]] || This API function returns the value of a variable. (ex. _shotSpeed, _tankSpeed, ect)
|-
| [[bz_getBZDBInt]] || This API function gets the value of a variable. (ex. _tankSpeed, _shotSpeed, ect)
|-
| [[bz_getBZDBString]] || This API function gets the value of a variable. (ex. _rainType, _rainTexture, ect)
|-
| [[bz getClientWorldDownloadURL]] || This API function returns the current string used for the URL of the cached world. This is the URL that will be sent to all clients as an optional download location for the map file.
|-
| [[bz_getCountdownRemaining]] || This API function retrieves the time remaining in a running countdown.
|-
| [[bz_getCurrentTime]] || This API function gets the current server time.
|-
| [[bz_getDebugLevel]] || This API function gets the debugging level of the server.
|-
| [[bz getFlagName]] || This API function returns the flag code for the specified flag.
|-
| [[bz getFlagPosition]] || This API function fill out the '''pos''' parameter with the position of the specified flag and return true. If the specified flag ID is invalid, the function will return false.
|-
| [[bz getGameType]] || This API function returns a value of type bz_eGameType representing the game type the server is playing
|-
| [[bz_getGroupList]] || This API function returns the groups on the server.
|-
| [[bz_getGroupPerms]] || This API function returns the list of permissions for the group provided.
|-
| [[bz_getIdleTime]] || This API function returns the amount of time a player has been idle in seconds. If the player ID does not exist or the player is an observer, it will return -1; otherwise it will return 0 if the player has not been idle.
|-
| [[bz_getLagWarn]] || This API function gets the amount that players will the a lag warning. (ex. 300ms, 500ms)
|-
| [[bz_getLoadedPlugins]] || This API function retrieves the names of all loaded plugins and counts how many of them there are.
|-
| [[bz_getLocaltime]] || This API function fills a bz_localTime object with values for the current time on the server.
|-
| [[bz_getMaxWaitTime]] || This API function returns the maximum wait (or idle) time for the server.
|-
| [[bz getNumFlags]] || This API function returns the total number of flags in the game.
|-
| [[bz_getPausedTime]] || This API function returns the amount of time a player has been paused in seconds.
|-
| [[bz_getPlayerByIndex]] || This API function gets the information for the player at the index specified. The index should be one of the elements of the list returned by bz_getPlayerIndexList. The returned player info won't update as the game progresses.
|-
| [[bz_getPlayerBySlotOrCallsign]] || This API function gets the information for the player with the specified slot index or callsign. The returned player info won't update as the game progresses.
|-
| [[bz_getPlayerCallsign]] || This API function retrieves the callsign of a player.
|-
| [[bz_getPlayerCount]] || This API function returns the number of users on the server.
|-
| [[bz_getPlayerCurrentState]] || This API function gets the specified player's current state. This includes information about how fast they're traveling, if they're in the air, if they're rotating, and more.
|-
| [[bz_getPlayerFlag]] || This API function gets the flag ID of the flag that the specified player is currently holding.
|-
| [[bz getPlayerFlagID]] || This API function returns the flag ID for the flag a player is carrying. If the player does not exist or does not have a flag, it will return -1.
|-
| [[bz_getPlayerHumanity]] || This API function returns true if the player has reported that they are human and not a robot.
|-
| [[bz_getPlayerIndexList]] || This API function returns a list of players indexes. Same as bz_getPlayerIndexList(bz_APIIntList), but a new bz_APIIntList is created and returned. This newly-created api int list must be deleted when it is no longer needed.
|-
| [[Bz getPlayerIndexList(bz APIIntList)]] || This API function gets the current list of players, and places them in the int list specified. The values are the player indexes, which can be passed to bz_getPlayerByIndex to get information about the player.
|-
| [[bz_getPlayerIPAddress]] || This API function returns the player's IP Address.
|-
| [[bz_getPlayerJitter]] || This API function returns the amount of jitter the player has.
|-
| [[bz_getPlayerLag]] || This API function returns the amount of lag the player has.
|-
| [[bz_getPlayerLosses]] || This API function returns the amount of losses for the player given.
|-
| [[bz_getPlayerPacketloss]] || This API function returns the amount of packetloss the player has.
|-
| [[bz_getPlayerRank]] || This API function returns the rank of the player given.
|-
| [[bz_getPlayerSpawnAtBase]] || This API function checks if a player is supposed to spawn at their base on their next respawn.
|-
| [[bz_getPlayerTeam]] || This API function returns the player's team.
|-
| [[bz_getPlayerTKs]] || This API function returns the amount of TKs for the player given.
|-
| [[bz_getPlayerWins]] || This API function returns the amount of wins for the player given.
|-
| [[bz_getPublic]] || This API function retrieves whether the server is successfully connecting and authenticating with the list server.
|-
| [[bz_getPublicAddr]] || This API function returns the string that was specified with the BZFS option -publicaddr or the default address that is used when starting up a public server.
|-
| [[bz_getPublicDescription]] || This API function retrieves the string with the title of the server, generally displayed on the list server when players are finding a game to join. This is what one would specify with the -publictitle BZFS option.
|-
| [[bz_getPublicPort]] || This API function retrieves the port the server communicates with. Normally this is specified with the -p BZFS option, but defaults to 5154.
|-
| [[bz_getReports]] || This API function retrieves reports made by other players in the same format as the /viewreports command does.
|-
| [[bz getShotGUID]] || This API function will return the Globally Unique Identifier(GUID) for the specified shot if it exists, or 0 if it does not.
|-
| [[bz getShotMetaData]] || This API function will return the data associated with the specified name for the specified shot. If the shot does not exist, or does not have any data for the name the function will return 0.
|-
| [[bz_getShotMismatch]] || This API function returns true if the server checks for shot mismatches.
|-
| [[bz_getTeamCount]] || This API function gets the amount of players on a team.
|-
| [[bz_getTeamLosses]] || This API function gets the losses of a team.
|-
| [[bz getTeamPlayerLimit]] || This API function will return the maximum number of players that the server is configured to allow for the specified team.
|-
| [[bz_getTeamScore]] || This API function gets the score for a team.
|-
| [[bz_getTeamWins]] || This API function gets the wins of a team.
|-
| [[bz_getTimeLimit]] || This API function retrieves the value of the time limit that was last set.
|-
| [[bz_getUTCtime]] || This API function fills a bz_Time object with values for the Universal Time Coordinated (UTC) time.
|-
| [[bz givePlayerFlag]] || This API function will give the specified player the specified flag. If the player has no flag, they will get a flag. If they have a flag and the force parameter is true the new flag code will replace the old flag code. If the force parameter is false, and the player has a flag, no action will be taken.
|-
| [[bz_grantPerm]] || This API function grants the specified player the specified permission. After this method has been called, calls to bz_hasPerm, passing in this player's id and the permission specified, will return true.
|-
| [[bz_groupAllowPerm]] || This API function grants the group a certain permission.
|-
| [[bz_hasPerm]] || This API function checks to see if the player specified has the permission specified.
|-
| [[bz_HostBanUser]] || This API function sets up a new Host ban Rule in the ban list.
|-
| [[bz_HostUnbanUser]] || This API function unbans a host name that has been previously banned.
|-
| [[bz_IDUnbanUser]] || This API function unbans a bzID address currently listed in the ban list. Note: The bzID is automatically assigned via the registration process at the BZBB.
|-
| [[bz_incrementPlayerLosses]] || This API function increments the losses of a player.
|-
| [[bz_incrementPlayerTKs]] || This API function increments the team-kill count of a player.
|-
| [[bz_incrementPlayerWins]] || This API function increments the wins of a player.
|-
| [[bz_incrementTeamLosses]] || This API function increment the losses of a team.
|-
| [[bz_incrementTeamWins]] || This API function increment the wins of a team.
|-
| [[bz_IPBanUser]] || This API function sets up a new IP Rule in the ban list. Note that if the player is currently playing when their IP address is banned it will not take effect immediately until they rejoin. This can be counteracted by kicking the player upon the ban, or using bz_IDBanUser() instead.
|-
| [[bz_IPUnbanUser]] || This API function unbans an IP address that is currently listed in the ban list.
|-
| [[bz_isCountDownActive]] || This API function retrieves whether or not the countdown is active. The countdown timer is active if the timer is continuing to go down every second.
|-
| [[bz_isCountDownInProgress]] || This API function retrieves whether or not the countdown to the start of the match is occurring.
|-
| [[bz_isCountDownPaused]] || This API function retrieves whether or not the countdown is paused.
|-
| [[bz_isPlayerPaused]] || This API function returns true if the specified player is currently paused, false if they are not.
|-
| [[bz_isPlayerSpawnable]] || This API function checks if player has the ability to spawn. This is not to be confused with the SPAWN permission but instead, this should be used together with bz_setPlayerSpawnable.
|-
| [[bz_isTimeManualStart]] || This API function retrieves whether or not the time limit has to be started via a player issuing the /countdown command. The -timemanual BZFS option would make this return value true.
|-
| [[bz_kickUser]] || This API function kicks an user from the server (same as the /kick command).
|-
| [[bz_loadPlugin]] || This API function attempts to load a plugin with the given path and filename along with any passed parameters.
|-
| [[bz moveFlag]] || This API function moves the specified flag. If the flag is carried, it will be dropped. If reset is true, the flag is also "zapped" to the new location ( ring graphical effect).
|-
| [[bz_newIntList]] || This API function creates a new bz_APIIntList.
|-
| [[bz_pauseCountdown]] || This API function pauses the countdown that is currently running.
|-
| [[bz_pollActive]] || If a poll is active, this function will return true.
|-
| [[bz_pollVeto]] || This API function vetos an active poll.
|-
| [[bz RegisterCustomFlag]] || This API function registers a custom flag. The registered abbreviation must be unique (that is, may not conflict with existing built-in or API flags).
|-
| [[bz_registerCustomSlashCommand]] || This API function registers a custom slash commands that is used by the plugin. The event listener must later be unregistered by a call to bz_removeCustomSlashCommand in the bz_Unload (2.0.x) or Cleaup() (2.4+) function.
|-
| [[bz_registerEvent]] || This API function registers a new event handler. This event handler will receive events of the event type specified.
|-
| [[bz_reloadBadwords]] || This API function reloads the bad words for the server.
|-
| [[bz_reloadGroups]] || This API function reloads the group file for the server.
|-
| [[bz_reloadHelp]] || This API function reloads the help files for the server.
|-
| [[bz_reloadLocalBans]] || This API function reloads the local ban list.
|-
| [[bz_reloadMasterBans]] || This API function reloads the master ban list.
|-
| [[bz_reloadUsers]] || This API function reloads the user database for the server.
|-
| [[bz_removeCustomSlashCommand]] || This API function removes all custom slash commands that were created with the plugin. The event listener must previously have been added by a call to bz_registerCustomSlashCommand.
|-
| [[bz_removeEvent]] || This API function removes the specified event listener. The event listener must previously have been added by a call to bz_registerEvent.
|-
| [[bz removePlayerFlag]] || This API function forces the specified player to drop the flag that is currently carried. The flag will be reset following the standard flag spawn logic.
|-
| [[bz_resetALLBZDBVars]] || This API function resets all the BZDB (/set) variables.
|-
| [[bz_resetBZDBVar]] || This API function resets the value of a variable. (Putting "" as the variable will reset them all).
|-
| [[bz resetFlag]] || This API function reset (respawn) the flag corresponding to the specified flag ID. If the flag is carried by a player, the player will loose the flag.
|-
| [[bz resetFlags]] || This API function will force all flags to be reset and respawned. If the onlyUnused parameter is true, then flags carried by players will not be reset, otherwise all flags will be reset. If the keepTeamFlags parameter is true, then team flags will not be reset.
|-
| [[bz_resetPlayerScore]] || This API function resets the score of a player.
|-
| [[bz_resetTeamScore]] || This API function resets the score of a team.
|-
| [[bz_resetTeamScores]] || This API function resets all team scores.
|-
| [[bz restart]] || This API function will cause the server to do a full restart. This restart will perform the following actions kick all players, stop any countdowns, stop any recordings, unload the world, reload the world, resets all flags, accept new connections.
|-
| [[bz_resumeCountdown]] || This API function resumes the countdown that is currently paused.
|-
| [[bz_revokePerm]] || This API function revokes the specified permission on the specified player. The player then loses this permission.
|-
| [[bz saveWorldCacheFile]] || This API function forces the server to save out a world cache file into the specified file. The function will return true if the write was sucsessfull, or false if there was an error.
|-
| [[bz sendTextMessage]] || This API function will cause the server to send a text message to a single player, all players, or team. The text message can be made to appear from any user or the server itself.
|-
| [[bz sendTextMessagef]] || This API function sends a message to a single player, all players, or all players on a team using printf-style formatting.
|-
| [[bz_setBZDBBool]] || This API function sets a BZDB variable to a given '''bool''' value.
|-
| [[bz_setBZDBDouble]] || This API function sets a BZDB variable to a given '''double''' value.
|-
| [[bz_setBZDBInt]] || This API function sets a BZDB variable to a given '''int''' value.
|-
| [[bz_setBZDBString]] || This API function sets a BZDB variable to a given '''string''' value.
|-
| [[bz setClientWorldDownloadURL]] || This function sets the current URL used to download a cached world file. It will be sent to clients that connect giving them the option of using that file. This is helpful if the plug-ins have changed the map file during a a call to bz_restart.
|-
| [[bz_setLagWarn]] || This API function sets the maximum lag a player can have before triggering a lag warning.
|-
| [[bz_setMaxWaitTime]] || This API function sets the maximum wait (or idle) time.
|-
| [[bz_setPlayerOperator]] || This API function marks this player as a server operator. A player typically becomes a server operator by providing the correct password to the /password command.
|-
| [[bz_setPlayerSpawnable]] || This API function marks this player as allowed to spawn or not allowed to spawn.
|-
| [[bz_setPlayerSpawnAtBase]] || This API function forces a player to spawn at their base on '''only''' their next respawn.
|-
| [[bz_setPlayerTKs]] || This API function sets the tks of a player.
|-
| [[bz_setPlayerWins]] || This API function sets the wins of a player.
|-
| [[bz setShotMetaData]] || This API function will set the specified data and associated it with the specified shot. If the shot does not exist the function will do nothing. Setting data for a name on a shot will replace any previous data that was associated with the name.
|-
| [[bz_setShotMismatch]] || This API function enables or disables the check for a shot mismatch.
|-
| [[bz_setTeamLosses]] || This API function sets the losses of a team.
|-
| [[bz_setTeamWins]] || This API function sets the wins of a team.
|-
| [[bz_setTimeLimit]] || This API function sets the countdown timer to a new value. '''Note:''' Any players that retrieved the countdown value before this function is called will not see the changes until they rejoin or a new countdown is triggered via bz_startCountdown().
|-
| [[bz shotHasMetaData]] || This API function will return true if the specified shot exists and has data stored under the specified name.
|-
| [[bz_shutdown]] || This API function shutsdown the server.
|-
| [[bz_startCountdown]] || This API function begins the starting countdown process as if a player were to type '''/countdown'''.
|-
| [[bz_superkill]] || This API function kicks all users from the server.
|-
| [[bz_unloadPlugin]] || This API function unloads a plugin that is currently loaded.
|-
| [[bz_updatePlayerData]] || This API function updates the data in a bz_BasePlayerRecord to the current state of that player. The information in a base player record instance is not kept up-to-date as the game progresses, so this method must be called to get the most up-to-date information.
|-
| [[bz validAdminPassword]] || This API function will return true if the passed in password is a valid server admin password.
|}

[[Category:BZFS API Docs]]

BZFS API Events

2025-11-02T04:44:21Z

Loymdayddaud: Add link to main website documentation

<b>Note:</b> The most up-to-date information on this topic can be found here: https://www.bzflag.org/documentation/developer/bzfs_api/events/

A comparison and overview of BZFS API events.

{|{{Prettytable}}
|-
| {{Hl3}} |'''BZFS API event'''
| {{Hl3}} |'''Function'''
|-
| [[bz eAllowAutoPilotChangeEvent]] || bz_eAllowAutoPilotChangeEvent is an API event that is called each time a player is about to change autopilot.
|-
| [[bz eAllowCTFCaptureEvent]] || bz_eAllowCTFCapEvent is an API event that is called each time a flag is about to be captured.
|-
| [[bz eAllowFlagGrab]] || bz_eAllowFlagGrab is an API event that is called each time a player is about to grab a flag.
|-
| [[bz eAllowKillCommandEvent]] || bz_eAllowKillCommandEvent is an API event that is called each the /kill command is executed.
|-
| [[bz eAllowPlayer]] || bz_eAllowPlayer is an API event that is called each time a player connects to the server.
|-
| [[bz eAllowSpawn]] || bz_eAllowSpawn is an API event called before a player respawns.
|-
| [[bz eAnointRabbitEvent]] || Bz_eAnointRabbitEvent is an API event that is called each time a new rabbit is to be selected.
|-
| [[bz eAuthenticatonComplete]] || bz_eAuthenticatonComplete is an API event that is called each time global authentication for a player is complete.
|-
| [[bz eAutoPilotChangeEvent]] || bz_eAutoPilotChangeEvent is an API event that is called each time a player is about to change autopilot.
|-
| [[bz eBanEvent]] || bz_eBanEvent is an API event that is called each time a regular ban is executed.
|-
| [[bz eBZDBChange]] || bz_eBZDBChange is an API event that is called each time a BZDB variable is changed.
|-
| [[bz eCaptureEvent]] || bz_eCaptureEvent is an API event that is called each time a team's flag has been captured.
|-
| [[bz eFilteredChatMessageEvent]] || bz_eFilteredChatMessageEvent is an API event that is called for each chat message the server receives. It is called after the server or any plug-ins have done chat filtering.
|-
| [[bz eFlagDroppedEvent]] || bz_eFlagDroppedEvent is an API event that is called each time a flag is dropped by a player.
|-
| [[bz eFlagGrabbedEvent]] || bz_eFlagGrabbedEvent is an API event that is called each time a flag is grabbed by a player.
|-
| [[bz eFlagResetEvent]] || bz_eFlagResetEvent is an API event that is called each time a flag is reset.
|-
| [[bz eFlagTransferredEvent]] || bz_eFlagTransferredEvent is an API event that is called each time a player with Thief steals a flag.
|-
| [[bz eGameEndEvent]] || bz_eGameEndEvent is an API event that is called each time a game ends. This only triggers when the game countdown ends (A Game Over), or when /superkill is initiated.
|-
| [[bz eGamePauseEvent]] || bz_eGamePauseEvent and bz_eGameResumeEvent are API events triggered when a game (i.e., a time- or score-limited match) pauses or resumes, respectively
|-
| [[bz eGameResumeEvent]] || bz_eGamePauseEvent and bz_eGameResumeEvent are API events triggered when a game (i.e., a time- or score-limited match) pauses or resumes, respectively.
|-
| [[bz eGameStartEvent]] || bz_eGameStartEvent and bz_eGameEndEvent are API events triggered when a game (i.e., a time- or score-limited match) begins or ends, respectively.
|-
| [[bz eGetAutoTeamEvent]] || bz_eGetAutoTeamEvent is an API event that is called for each new player is added to a team.
|-
| [[bz eGetPlayerInfoEvent]] || bz_eGetPlayerInfoEvent is an API event that is called each time the server sends out a player info update message to a remote player.
|-
| [[bz eGetPlayerMotto]] || bz_eGetPlayerMotto is an API event that is called when the player joins. It gives us the motto of the player.
|-
| [[bz eGetPlayerSpawnPosEvent]] || bz_eGetPlayerSpawnPosEvent is an API event that is called each time the server needs a new spawn position.
|-
| [[bz eGetWorldEvent]] || bz_eGetWorldEvent is an API event that is called before the BZFS server defines the world.
|-
| [[bz eHostBanModifyEvent]] || bz_eHostBanModifyEvent is an API event that is called each time before a hostban is going to happen.
|-
| [[bz eHostBanNotifyEvent]] || bz_eHostBanNotifyEvent is an API event that is called each time a hostban is executed.
|-
| [[bz eIdBanEvent]] || bz_eIdBanEvent is an API event that is called each time a ban on bzid (idban) is executed.
|-
| [[bz eIdleNewNonPlayerConnection]] || bz_eIdleNewNonPlayerConnection is an API event that is called each time there is an idle connection.
|-
| [[bz eKickEvent]] || bz_eKickEvent is an API event triggered when a player is kicked from the server. This event may be triggered by both the /kick Slash Command,another plug-in, or the game's core logic...
|-
| [[bz eKillEvent]] || bz_eKillEvent is an API event triggered when a player sends the /kill Slash Command to kill another player.
|-
| [[bz eListServerUpdateEvent]] || bz_eListServerUpdateEvent is an API event called before the server adds itself to the list server.
|-
| [[bz eLoggingEvent]] || bz_eLoggingEvent is an API event called whenever a debug message is outputted. These can normally be seen with the -d verbose options.
|-
| [[bz eLuaDataEvent]] || bz_eLuaDataEvent is an API event that is called each time a BZDB variable is changed.
|-
| [[bz eMessageFilteredEvent]] || bz_eMessageFilteredEvent is an API event that is called whenever a message is censored by the swear filter.
|-
| [[bz eMsgDebugEvent]] || bz_eMsgDebugEvent is an API event called every time packets are sent to the server.
|-
| [[bz eNetDataReceiveEvent]] || bz_eNetDataReceiveEvent is an API event that is called each time net data is received.
|-
| [[bz eNetDataSendEvent]] || bz_eNetDataSendEvent is an API event that is called each time net data is sent.
|-
| [[bz eNewNonPlayerConnection]] || bz_eNewNonPlayerConnection is an API event that is called each time there is a connection to the server not from a player.
|-
| [[bz eNewRabbitEvent]] || Bz_eNewRabbitEvent is an API event that is called each time a new rabbit is selected.
|-
| [[bz eNullEvent]] || bz_eNullEvent is the start point for the bz_eEventType enumeration. It is never called and has no data.
|-
| [[bz ePlayerAuthEvent]] || bz_ePlayerAuthEvent is an API event triggered when a player's authorization status changes.
|-
| [[bz ePlayerCollision]] || bz_ePlayerCollision is an API event that is called each time two players collide.
|-
| [[bz ePlayerCustomDataChanged]] || bz_ePlayerCustomDataChanged is an API event that is called each time bz_setPlayerCustomData() is run.
|-
| [[bz ePlayerDieEvent]] || bz_ePlayerDieEvent is an API event that is called each time a tank is killed.
|-
| [[bz ePlayerJoinEvent]] || bz_ePlayerJoinEvent is an API event that is called each time a player joins the game.
|-
| [[bz ePlayerPartEvent]] || bz_ePlayerPartEvent is an API event that is called each time a player parts (ie, leaves) a game.
|-
| [[bz ePlayerPausedEvent]] || bz_ePlayerPausedEvent is an API event that is called each time a playing tank is paused.
|-
| [[bz ePlayerPauseRequestEvent]] || bz_ePlayerPauseRequestEvent is an API event that is called each time a player wants to pause.
|-
| [[bz ePlayerScoreChanged]] || bz_ePlayerScoreChanged is an API event that is called when a player's score changes.
|-
| [[bz ePlayerSentCustomData]] || bz_ePlayerSentCustomData is an API event that is called each time a player is sent custom data.
|-
| [[bz ePlayerSpawnEvent]] || bz_ePlayerSpawnEvent is an API event that is called each time a playing tank is being spawned into the world.
|-
| [[bz ePlayerTeamChangeEvent]] || bz_ePlayerTeamChangeEvent is an API event that is called each time a player switches teams via bz_changeTeam().
|-
| [[bz ePlayerUpdateDoneEvent]] || bz_ePlayerUpdateDoneEvent is an API event that is called each time a player update finishes.
|-
| [[bz ePlayerUpdateEvent]] || bz_ePlayerUpdateEvent is an API event that is called each time a player sends an update to the server.
|-
| [[bz ePluginLoaded]] || bz_ePluginLoaded is an API event that is called each time a plugin is loaded.
|-
| [[bz ePluginUnloaded]] || bz_ePluginUnloaded is an API event that is called when a plugin is unloaded.
|-
| [[bz eRawChatMessageEvent]] || bz_eRawChatMessageEvent is an API event that is called for each chat message the server receives. It is called before any filtering is done.
|-
| [[bz eReloadEvent]] || bz_eReloadEvent is an API event that is called each time a player reloads.
|-
| [[bz eReportFiledEvent]] || bz_eReportFiledEvent is an API event that is called each time a player or plugin files a report.
|-
| [[bz eServerMsgEvent]] || bz_eServerMsgEvent is an API event that is called each time the server sends a message.
|-
| [[bz eShotEndedEvent]] || bz_eShotEndedEvent is an API event that is called each time a shot ends.
|-
| [[bz eShotExpiredEvent]] || bz_eShotExpiredEvent is an API event that is called each time a shot expires.
|-
| [[bz eShotFiredEvent]] || bz_eShotFiredEvent is an API event that is called each time a shot is fired.
|-
| [[bz eShotRicochetEvent]] || bz_eShotRicochetEvent is an API event that is called each time a shot ricochetes.
|-
| [[bz eShotStoppedEvent]] || bz_eShotStoppedEvent is an API event that is called each time a shot stops.
|-
| [[bz eShotTeleportEvent]] || bz_eShotTeleportEvent is an API event that is called each time a shot teleports via a teleporter.
|-
| [[bz eSlashCommandEvent]] || bz_eSlashCommandEvent is an API event that is called each time a player sends a slash command.
|-
| [[bz eTeamScoreChanged]] || bz_eTeamScoreChanged is an API event that is called when a team's score changes.
|-
| [[bz eTeleportEvent]] || bz_eTeleportEvent is called when a tank passes through a teleportor.
|-
| [[bz eTickEvent]] || bz_eTickevent is an API event that is called once for each BZFS main loop. The wait time between tick calls can vary greatly depending on server load network conditions. Plug-ins that wish to enforce a maximum wait time between ticks should call [[bz_setMaxWaitTime]] with the longest wait time that is acceptable.
|-
| [[bz eUnknownSlashCommand]] || bz_eUnknownSlashCommand is an API event that is called when the BZFS server does not have an installed handler for a specific slash command.
|-
| [[bz eWorldFinalized]] || bz_eWorldFinalized is an API event that is called when the world is done loading.
|-
| [[bz eZoneEntryEvent]] || bz_eZoneEntryEvent is an API event that is called each time a player enters a zone on a BZW map. The event is unused and has no data.
|-
| [[bz eZoneExitEvent]] || bz_eZoneExitEvent is an API event that is called each time a player leaves a zone on a BZW map. The event is unused and has no data.
|}

[[Category:BZFS API Docs]]

BZFS API

2025-11-02T04:39:58Z

Loymdayddaud: Add note about information on main site

{{DoDoc|
Update to 2.4.x spec<br>
}}

==Note==
The most up-to-date information about the BZFS API can be found here: https://www.bzflag.org/documentation/developer/bzfs_api/

The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by [[BZFS]] to be used by [[Plug-ins]]. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.

==Overview==
The BZFS API is defined entirely in the '''bzfsAPI.h''' header file that is part of the [[BZFlag Source]] code. The header is also included with each install of the BZFlag installer for Microsoft Windows.

Plug-ins include this file in their source code so that they may access the functions it contains.

==Naming Conventions==
All BZFS API code structures will begin with the prefix '''bz''' or '''bz_''' for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.

All wiki documentation references the newer BZFS 3.0 API.

==API Versions==
The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.

In version 3.0 of BZFlag, the entire API will be versioned and set up to use derived classes so that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures will be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out minor source code changes. Once an older plug-in has been updated to the new API it will not work in 2.0.x but will work in all versions after 3.0.

==Entry Points==
There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement.

BZF_PLUGIN_CALL int [[bz_Load]] ( const char* command );
BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
BZF_PLUGIN_CALL int [[bz_GetVersion]] ( void );

All entry point functions must be preceded with the BZF_PLUGIN_CALL macro. This macro tells the compiler to export these functions so bzfs can find them when the plug-in is loaded.

[[bz_Load]] is called when the plug-in is first initialized. This is when the plug-in should register any [[Event(API)|event handlers]] needed and initialize any "one time" startup data.

[[bz_Unload]] is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.

[[bz_GetVersion]] is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.

'''bzfsAPI.h''' defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro;

BZ_GET_PLUGIN_VERSION

somewhere in its sources, and then export the function. This will automatically return the API version that the plug-in was compiled with.

See the sample plug-ins for examples of each function. These will be the only 3 functions called by bzfs that are not tied to events or other actions installed by the plug-in after load.

==Types==

Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.

===bz_APIString===
Any text passed back from the API or events will come in the form of a [[bz_APIString]]. This is a class defined in the API that behaves much like a std::string. The 'c_str()' method can be used to get the text out as a normal 'const char*'. The class also supports many assignment functions for setting it's contents.

A plug-in should never need to make variables of its' own using the [[bz_APIString]] type, but should use a standard stl std::string instead, [[bz_APIString]] provides an appropriate assignment operator.

[[bz_APIString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.

{{main|bz_APIString}}

===bz_APILists===

A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function.
The lists types are;
{| border="1" cellpadding="3" cellspacing="0"
!List
!allocator function
!delete function
!contained type
|-
|[[bz_APIIntList]]
|[[bz_newIntList]]
|[[bz_deleteIntList]]
|int
|-
|[[bz_APIFloatList]]
|[[bz_newFloatList]]
|[[bz_deleteFloatList]]
|float
|-
|[[bz_APIStringList]]
|[[bz_newStringList]]
|[[bz_deleteStringList]]
|[[bz_APIString]]
|}

===Enumerations===
A number of enumerations exist in the API and are used by a number of API functions and events.
[[bz_eTeamType]]
[[Event(API)|bz_eEventType]]
[[bz_eShotType]]
[[bz_eGameType]]
[[bz_ePlayerStatus]]
[[bz_eWorldObjectType]]
[[bz_eAPIColType]]
[[bz_ePlayerType]]
[[bz_eRejectCodes]]
[[bz_ePlayerDeathReason]]

==Events==
Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.

{{main|Events (API)}}

==Functions==
The BZFS API provides a number of functions to plug-ins for use in querying the current game state. Functions are used both to get information about the game, and to trigger in game actions, such as activating a world weapon.

{{main|Functions (API)}}

==Wiki Documentation==
The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a ''History'' section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)

API developers should use the bzfsAPI.h file as for exact spellings of methods and parameters in the version they wish to use.

==See Also==

* [[Events (API)|API Events]]
* [[Functions (API)|API Functions]]
* [[Plug-ins]]
* [[BZFS]]

[[Category:Development]]
[[Category:Plug-Ins]]