Events (API)

From BZFlagWiki
Revision as of 09:25, 22 August 2015 by Alezakos (Talk | contribs) (See also: Add link to functions)

Jump to: navigation, search
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_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_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