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 Events
(Redirected from Events (API))
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.
Events
The following list contains all the event types currently supported by BZFS version 2.99
bz_eAllowAutoPilotChangeEvent bz_eAllowCTFCaptureEvent bz_eAllowFlagGrabEvent bz_eAllowKillCommandEvent bz_eAllowPlayer bz_eAllowSpawn bz_eAnointRabbitEvent bz_eAutoPilotChangeEvent bz_eBZDBChange bz_eBanEvent bz_eCaptureEvent bz_eFilteredChatMessageEvent bz_eFlagDroppedEvent bz_eFlagGrabbedEvent bz_eFlagResetEvent bz_eFlagTransferredEvent bz_eGameStartEvent bz_eGameEndEvent bz_eGetAutoTeamEvent bz_eGetPlayerInfoEvent bz_eGetPlayerSpawnPosEvent bz_eGetWorldEvent bz_eHostBanModifyEvent bz_eHostBanNotifyEvent bz_eIdBanEvent bz_eIdleNewNonPlayerConnection bz_eKickEvent bz_eKillEvent bz_eListServerUpdateEvent bz_eLogingEvent bz_eLuaDataEvent bz_eMessageFilteredEvent bz_eNetDataReceiveEvent bz_eNetDataSendEvent bz_eNewNonPlayerConnection bz_eNewRabbitEvent bz_eNullEvent bz_ePlayerAuthEvent bz_ePlayerCollision bz_ePlayerCustomDataChanged bz_ePlayerDieEvent bz_ePlayerJoinEvent bz_ePlayerPartEvent bz_ePlayerPauseRequestEvent bz_ePlayerPausedEvent bz_ePlayerSentCustomData bz_ePlayerSpawnEvent bz_ePlayerTeamChangeEvent bz_ePlayerUpdateDoneEvent bz_ePlayerUpdateEvent bz_eRawChatMessageEvent bz_eReloadEvent bz_eReportFiledEvent bz_eServerMsgEvent bz_eShotEndedEvent bz_eShotExpiredEvent bz_eShotFiredEvent bz_eShotRicochetEvent bz_eShotStoppedEvent bz_eShotTeleportEvent bz_eSlashCommandEvent bz_eTeleportEvent bz_eTickEvent bz_eUnknownSlashCommand bz_eWorldFinalized bz_eZoneEntryEvent bz_eZoneExitEvent
The following list contains all the event types currently supported by BZFS version 2.4
bz_eAllowCTFCaptureEvent bz_eAllowFlagGrab bz_eAllowPlayer bz_eAllowPollEvent bz_eAllowSpawn bz_eBanEvent bz_eBZDBChange bz_eCaptureEvent bz_eFilteredChatMessageEvent bz_eFlagDroppedEvent bz_eFlagGrabbedEvent bz_eFlagTransferredEvent bz_eGameEndEvent bz_eGamePauseEvent bz_eGameResumeEvent bz_eGameStartEvent bz_eGetAutoTeamEvent bz_eGetPlayerInfoEvent bz_eGetPlayerMotto bz_eGetPlayerSpawnPosEvent bz_eGetWorldEvent bz_eHostBanModifyEvent bz_eKickEvent bz_eKillEvent bz_eListServerUpdateEvent bz_eLoggingEvent bz_eMsgDebugEvent bz_eMessageFilteredEvent bz_eNetDataReceiveEvent bz_eNetDataSendEvent bz_eNewNonPlayerConnection bz_ePlayerAuthEvent bz_ePlayerDieEvent bz_ePlayerJoinEvent bz_ePlayerPartEvent bz_ePlayerPausedEvent bz_ePlayerScoreChanged bz_ePlayerSpawnEvent bz_ePlayerUpdateEvent bz_ePluginLoaded bz_ePluginUnloaded bz_ePollStartEvent bz_ePollVoteEvent bz_ePollVetoEvent bz_ePollEndEvent bz_eRawChatMessageEvent bz_eReportFiledEvent bz_eServerMsgEvent bz_eShotEndedEvent bz_eShotFiredEvent bz_eSlashCommandEvent bz_eTeamScoreChanged bz_eTickEvent bz_eUnknownSlashCommand bz_eWorldFinalized bz_eZoneEntryEvent bz_eZoneExitEvent
There exists one additional event in the 'bz_eEventType' enumeration in 'bzfsAPI.h', bz_eLastEvent. This event is simply used by BZFS to assist in the counting of the total number of events, it will never be called and can not be installed.