Editing Events (API)

{{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]] 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;

 BZF_API bool [[bz_registerEvent]] ( bz_eEventType eventType, [[bz_EventHandler]]* eventHandler );

The plug-in registers and event callback derived from [[bz_EventHandler]] 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]] entry point, the plug-in must remove the installed callback by calling the function;

 BZF_API bool [[bz_removeEvent]] ( bz_eEventType eventType, [[bz_EventHandler]]* eventHandler );

==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]]