|
Events
A plugin is basically useless if it can't react to events in game. To allow this
a plugin needs to tell bzfs that it would like to listen for events. To do that
the plugin will need to call the following function:
bool bz_registerEvent ( bz_teEventType eventType, bz_EventHandler* eventHandler
);
where
eventType
is one of the following enumerations;
| bz_eCaptureEvent
|
A team flag is captured in a CTF game |
| bz_ePlayerDieEvent
|
A player gets killed
|
| bz_ePlayerSpawnEvent
|
A player joins as a tank |
| bz_eZoneEntryEvent
|
A player enters a zone ( not implemented )
|
| bz_eZoneExitEvent
|
A player exits a zone ( not implemented ) |
| bz_ePlayerJoinEvent
|
A user joins the server ( player or observer ) |
| bz_ePlayerPartEvent
|
A user leaves the server ( player or observer ) |
| bz_eChatMessageEvent
|
A chat message is sent
|
| bz_eUnknownSlashCommand
|
A "/" command was issued but not handled |
| bz_eGetPlayerSpawnPosEvent
|
The server needs a spawn position for a player |
| bz_eGetAutoTeamEvent
|
The server is assigning a player to a team automatically |
| bz_eAllowPlayer |
The server is about to allow or disallow a player |
|
bz_eTickEvent |
The server has executed one of it's normal event loops
|
| bz_eGenerateWorldEvent
|
The server is generating or loading a world |
|
bz_eGetPlayerInfoEvent
|
The server needs the info bits about a player |
| bz_eAllowSpawn |
The server is about to allow a player to spawn |
| bz_eListServerUpdateEvent
|
The server is about to update the list server with new information |
eventHandler
is a pointer to a event handler class. Plugins should derive their own versions
of the event handler class from bz_EventHandler and pass this pointer into the
function. When the event happens the process function of the class will be
called so that the plugin can perform any actions it desires.
When the plugin's unload function is called, the plugin must remove any events
it has loaded by calling:
bool bz_removeEvent (
bz_teEventType eventType, bz_EventHandler* eventHandler );
Failure to do so may cause crashes if the plugin is manually unloaded at run
time.
The event handler is a pure virtual class. It does not perform any logic or
actions, but simply provides a framework for a plugin to use. You need to
derive your own version of an event handler before you can use it, providing
your own code in the "process" method.
virtual void process ( bz_EventData *eventData );
When the process method is called, the eventData will be a pointer to a data
class. There are a number of different data classes all derived from
bz_EventData. The eventType member of the base class will tell you what type
the data is. This allows for the same handler to be used for more then one type
of event.
The event data for the various event types are as follows, along with their
associated data items. Some events may share event data types.
| bz_eCaptureEvent
provides the following data
|
bz_CTFCaptureEventData
{
bz_eTeamType teamCapped; // the team that had there flag
captured
bz_eTeamType teamCapping; // the team that did the capturing
int playerCapping; // the player ID who did the capture
float pos[3]; // the last known position of the player
float rot; // the last known angle of the player
double time; // the time in seconds of the capture
}
|
| Handle this event when you want to do something when ever someone captures a
team flag. It is useful for events like clearing bases, tracking scores, or
playing sounds.
|
|
| bz_ePlayerDieEvent
provides the following data |
bz_PlayerDieEventData
{
int playerID; // the ID of the player who died
bz_eTeamType team; // the team of the player who died
int killerID; // the ID of the player doing the killing
bz_eTeamType killerTeam; // the team that the killer was on
bzApiString flagKilledWith; // the flag the killer had when killing
float pos[3]; // the last known position of the victim
float rot; // the last known rotation of the victim
double time; // the time of the death
}
|
| This event is called whenever a player is killed. |
|
| bz_ePlayerSpawnEvent
provides the following data |
bz_PlayerSpawnEventData
{
int playerID // the ID of the player that has spawned;
bz_eTeamType team; // the team the spawning player is a member of
float pos[3]; // the position of the spawn
float rot; // the rotation of the spawn
double time; // the time of the spawn
}
|
| Track this event when you wish to know if someone has spawned, and where they
have spawned at. This event does not let you set the spawn position, it is only
called AFTER the spawn has been computed and sent to the players. |
|
| bz_ePlayerJoinEvent
AND
bz_ePlayerPartEvent
both provide the following data |
bz_PlayerJoinPartEventData
{
int playerID; // the ID of the user that has joined or
parted
bz_eTeamType team; // the team ID of the user
bzApiString callsign; // the callsign used by the user
bzApiString reason; // if a part event, the reason for the part
double time; // the time of the event
}
|
| These events are called when ever a user joins or leaves the server. These
events are called for both players and observers.
|
|
| bz_eChatMessageEvent
provides the following data |
bz_ChatEventData
{
int from; // the player ID of who the message is from
int to; // the player ID of who the message is for
bz_eTeamType team; // The team the message is to, if a team message
bzApiString message; // the message itself
double time; // the time of the message
}
|
| This event is called whenever the server is asked to deliver a chat message.
This includes private messages, team messages, and general chat. ANYTHING that
is not a / command goes in here. The plugin CAN change the chat message before
it is sent. This can allow for a plugin to filter chat text or insert
additional text. If the plugin clears the message text, then the chat message
will not be sent. The text sent to this plugin may have been filtered by
another plugin first. If the chat is to all players to will be set to the
define BZ_ALLUSERS and the team field will be set to eNoTeam, If the chat is to
the admin channel or a team then the to field will be set to BZ_NULLUSER and
the team will be set to the appropriate team ( admin channel is a fake team ) |
|
| bz_eUnknownSlashCommand
provides the following data |
bz_UnknownSlashCommandEventData
{
int from; // the ID of the player who sent the command
bool handled; // flag that tells if the command was handled.
// if the plugin handles this command it must
// set this value to true before it returns
bzApiString message; // the command itself
double time; // the time the command was issued
}
|
| This event is called when a user attempts to use a / command that does not
exist. It is not very useful for anything other then error reporting. If you
wish to install your own custom / command then it's recommended that you use
the customSlashCommand functions. |
|
| bz_eGetPlayerSpawnPosEvent
provides the following data |
bz_GetPlayerSpawnPosEventData
{
int playerID; // the player ID of who needs to be spawned
bool handled; // if the action has been/will be handled
float pos[3]; // the proposed spawn position
float rot; // the proposed spawn rotation
double time; // the time of the request
}
|
| This event is called when ever a player spawn position is needed. The standard
spawn position will be set in the pos and rot fields. The plugin may modify or
set new spawn data if it wishes to. This can allow a plugin to do its own spawn
calculations. The position may have been modified by another plugin first if
multiple plugins are handaling the event. If so the "handled" field should be
true. If your plugin modifies the spawn data it too should set the "handled"
bit to true.
|
|
| bz_eAllowPlayer
provides the following data |
bz_AllowPlayerEventData
{
int playerID; // the player ID of the joining player
bzApiString callsign; // the callsign of the player
bzApiString ipAddress; // the IP address the player is connecting from
bzApiString reason; // a reason string with the reason the player is to be
disallowed to join
bool allow; // flag to allow or disallow the player.
double time; // the time of the request
}
|
| This event is called every time a user joins a server. The server will do its
normal ban/disallow logic then pass the value to the plugin in the allow field.
The plugin can then chose to allow or disalow the player as it sees fit. If the
player is to be disallowed, then please provide a reason.
|
|
| bz_TickEvent
provides the following data |
bz_TickEventData
{
double time; // time of the event.
}
|
| This event is not called due to any user or player interaction. This event is
called automatically by bzfs every time it has completed one of its normal
execution loops. This event is useful when plugins need to perform update
actions, periodic maintenance, or other actions that are not directly tied to a
user event, like checking to see if it is time to start a match. A plugin can
set the maximum allowable time between calls to this event using the function
bz_setMaxWaitTime described below.
|
|
| bz_GenerateWorldEvent
provides the following data |
bz_GenerateWorldEventData
{
bool handled; // flag to set to true if the plugin has
generated the world
bool ctf; // true if the world is a CTF world
double time; // the time of the request
}
|
| This event is called by bzfs when it begins to build or load the world. The
event is called BEFORE any map file is loaded. If the plugin wishes to define
the world, it must call any world creation functions during this event, and
then set the handled flag to true. If the plugin generates the world, then bzfs
will NOT load the map file, and will NOT generate a random world. Calls to any
world creation functions outside this event will fail. |
|
|
