BZFS 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.

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.

See also

• BZFS API
• BZFS API Functions
• Plug-ins