|
|
| Line 1: |
Line 1: |
| <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/
| | #REDIRECT [[BZFS API]] |
| | |
| 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_Doc|keeptitle=1}}
| |
| ==Overview==
| |
| API events are callbacks that a [[Plug-ins|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_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]]
| |
| * [[Functions(API)|BZFS API Functions]]
| |
| * [[Plug-ins]]
| |
| | |
| [[Category:BZFS_API_Functions]]
| |