This wiki was in read-only mode for many years, but can now be edited again. A lot of information will need to be updated.
BZFS API
|
There is still documentation to be done here!! If you feel up to the task, please have a go at it. Specifically what needs to be added is: Update to 2.4.x spec |
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.
Note: 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.
API Functions
| BZFS API Function | 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. |
API Events
Note: 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.
| BZFS API event | 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. |
| BZFS API Documentation This page contains part of the BZFS API documentation for use by Plug-ins on the BZFS server. |
Overview
API events are callbacks that a plug-in can install into BZFS to be called in response to specific actions or state changes in the server side game world. Events are the primary method of communication from BZFS to installed plug-ins. Specific events exist for nearly all logical actions that can happen during a game of BZFlag.
Installation and Removal
The callbacks for events are typically installed during the bz_Load (2.0.x) or Init (2.4+) entry point in a plug-in, so they can be active when a plug-in is first loaded.
The plug-in must call the function;
2.0.x
BZF_API bool bz_registerEvent ( bz_eEventType eventType, bz_EventHandler* eventHandler );
2.4+
Register ( bz_eEventType );
The plug-in registers and event callback derived from bz_EventHandler (2.0.x) or bz_Plugin (2.4+) for each specific event types it wishes to monitor.
When a plug-in no longer needs to monitor an event, or when it is unloaded in the bz_Unload (2.0.x) or Cleanup (2.4+) entry point, the plug-in must remove the installed callback by calling the function;
2.0.x
BZF_API bool bz_removeEvent ( bz_eEventType eventType, bz_EventHandler* eventHandler );
2.4+
Flush();
In BZFlag 2.4, events are no longer removed individually but instead they are all removed automatically by calling on the 'Flush()' method.
Event Handler
The plug-in must define a class that is derived from bz_EventHandler (2.0.x) or bz_Plugin (2.4+) and pass a pointer to an object of that class when ever it registers an event callback.
When ever a specific event is triggered, BZFS will call the 'process' (2.0.x) or 'Event' (2.4+) method of the installed callback class.
2.0.x
virtual void process ( bz_EventData *eventData ) = 0;
2.4+
virtual void Event ( bz_EventData *eventData ) = 0;
Event Data
With each call to the 'process' method of the installed event handler, BZFS will pass the plug-in a pointer to a class that contains all the data provided by the event. Each event derives a specific data class from bz_EventData that contains the specific member variables that contain the data. The base class bz_EventData contains the data member;
bz_eEventType eventType;
This data member allows a plug-in to identify the specific event and cast the 'bz_EventData' pointer to the appropriate specific data class. This is usefull for plug-ins that use the same 'bz_EventHandler' to process more then one specific message.
Please see the descriptions of each specific event for information and descriptions of the data classes for each event. Some specific events allow plug-ins to change the values of data members in the data class and will use the modified values instead.
Plug-ins should never delete or free the memory for a data class. BZFS will manage all pointers passed to plug-ins.
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 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 article: 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;
| 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 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 article: 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 article: 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.