This wiki is archived and useful information is being migrated to the main bzflag.org website
Difference between revisions of "Events (API)"
m (Deleting spam) |
m (Add new poll events) |
||
(23 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
− | {{ | + | {{BZFS_API_Doc|keeptitle=1}} |
− | + | ||
− | + | ||
− | + | ||
==Overview== | ==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. | 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== | ==Installation and Removal== | ||
− | The callbacks for events are typically installed during the [[bz_Load]] entry point in a plug-in, so they can be active when a plug-in is first loaded. | + | 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; | The plug-in must call the function; | ||
+ | 2.0.x | ||
BZF_API bool [[bz_registerEvent]] ( bz_eEventType eventType, [[bz_EventHandler]]* eventHandler ); | 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 ); | 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== | ==Event Handler== | ||
− | The plug-in must define a class that is derived from [[bz_EventHandler]] and pass a pointer to an object of that class when ever it registers an event callback. | + | 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' method of the installed callback class. | + | 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; | virtual void process ( bz_EventData *eventData ) = 0; | ||
+ | |||
+ | 2.4+ | ||
+ | virtual void Event ( bz_EventData *eventData ) = 0; | ||
==Event Data== | ==Event Data== | ||
Line 36: | Line 47: | ||
==Events== | ==Events== | ||
− | The following list contains all the event types currently supported by BZFS version 2. | + | 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_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_ePlayerDieEvent]] | ||
− | |||
− | |||
− | |||
[[bz_ePlayerJoinEvent]] | [[bz_ePlayerJoinEvent]] | ||
[[bz_ePlayerPartEvent]] | [[bz_ePlayerPartEvent]] | ||
+ | [[bz_ePlayerPauseRequestEvent]] | ||
+ | [[bz_ePlayerPausedEvent]] | ||
+ | [[bz_ePlayerSentCustomData]] | ||
+ | [[bz_ePlayerSpawnEvent]] | ||
+ | [[bz_ePlayerTeamChangeEvent]] | ||
+ | [[bz_ePlayerUpdateDoneEvent]] | ||
+ | [[bz_ePlayerUpdateEvent]] | ||
[[bz_eRawChatMessageEvent]] | [[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_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_eAllowPlayer]] | ||
− | [[ | + | [[bz_eAllowPollEvent]] |
− | + | ||
− | + | ||
[[bz_eAllowSpawn]] | [[bz_eAllowSpawn]] | ||
− | |||
[[bz_eBanEvent]] | [[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_eKickEvent]] | ||
[[bz_eKillEvent]] | [[bz_eKillEvent]] | ||
− | [[ | + | [[bz_eListServerUpdateEvent]] |
+ | [[bz_eLoggingEvent]] | ||
+ | [[bz_eMsgDebugEvent]] | ||
[[bz_eMessageFilteredEvent]] | [[bz_eMessageFilteredEvent]] | ||
− | [[ | + | [[bz_eNetDataReceiveEvent]] |
− | [[ | + | [[bz_eNetDataSendEvent]] |
− | [[ | + | [[bz_eNewNonPlayerConnection]] |
[[bz_ePlayerAuthEvent]] | [[bz_ePlayerAuthEvent]] | ||
− | [[ | + | [[bz_ePlayerDieEvent]] |
− | [[ | + | [[bz_ePlayerJoinEvent]] |
− | [[ | + | [[bz_ePlayerPartEvent]] |
− | [[ | + | [[bz_ePlayerPausedEvent]] |
− | [[ | + | [[bz_ePlayerScoreChanged]] |
+ | [[bz_ePlayerSpawnEvent]] | ||
[[bz_ePlayerUpdateEvent]] | [[bz_ePlayerUpdateEvent]] | ||
− | [[ | + | [[bz_ePluginLoaded]] |
− | [[ | + | [[bz_ePluginUnloaded]] |
− | [[ | + | [[bz_ePollStartEvent]] |
− | [[ | + | [[bz_ePollVoteEvent]] |
− | [[ | + | [[bz_ePollVetoEvent]] |
− | [[ | + | [[bz_ePollEndEvent]] |
+ | [[bz_eRawChatMessageEvent]] | ||
+ | [[bz_eReportFiledEvent]] | ||
+ | [[bz_eServerMsgEvent]] | ||
[[bz_eShotEndedEvent]] | [[bz_eShotEndedEvent]] | ||
− | [[ | + | [[bz_eShotFiredEvent]] |
− | [[ | + | [[bz_eSlashCommandEvent]] |
− | [[ | + | [[bz_eTeamScoreChanged]] |
− | [[ | + | [[bz_eTickEvent]] |
+ | [[bz_eUnknownSlashCommand]] | ||
[[bz_eWorldFinalized]] | [[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. | 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== | + | == See also == |
− | [[BZFS API]] | + | * [[BZFS API]] |
− | + | * [[Functions(API)|BZFS API Functions]] | |
− | [[ | + | * [[Plug-ins]] |
− | [[Category: | + | [[Category:BZFS_API_Functions]] |
Latest revision as of 09:18, 27 January 2017
BZFS API Documentation This page contains part of the BZFS API documentation for use by Plug-ins on the BZFS server. |
Overview[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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.