<commit_before>//*****************************************************************************
//***                             bzAPI.txt                                 ***
//***                    Plug-in development for BZFlag                     ***
//*****************************************************************************


* This document:

This document is a description of the bzflag plug-in system and it's associated
API. It will atempt to explain how to make a plug-in, what you can do in a
plug-in and what the basic API features are.

* What is a plug-in

A plug-in is a compiled code module that is loadable at runtime by the BZFlag
game server (bzfs) that can change the way that the server runs. Since plug-ins
are compiled Plug-ins need to be built on the platform they are to be run with.
This means that a plug-in built for windows will not work on linux, and vice/
versa. Plug-ins are writen in C++ as Dynamic Librarys, ether as a DLL on windows
or a .so file on linux/OS X.

* What can a plug-in do.

Plugins can install event handlers for a number of events in bzfs. Events are
actions that happen in the game, such as the capture of a team flag, or the death
of a player. Plug-ins can then call API functions that can change the gamestate
in response to the event, such as sending a text message, activating a world
weapon, or kicking a player. All plug-in actions are event driven. A plugin is
allways called first by the server in response to an action.

* What do I need to make a plug-in, and what do I need to know.

To make a plug-in you will need to know at least C and should be familar with
the C++ language. Many of the API calls and structures will use C++, but they 
can be called in a C "style" if you wish. Since plug-ins are compiled code you
will need a compiler for your OS and the knowledge of how to use it. The sample
plugin has makefiles and Windows VC projects that you can use as a basis. 
If you are on windows, there is a free version of visual studio that you cean
use to build plugins. You can download it for free from 
http://lab.msdn.microsoft.com/express/visualc/default.aspx . You will allso 
need access to some of the source files from the bzflag source distribution.
If you are on windows, the required header and library files are included with
the installer in the API folder. Other OSs can get the full source tree from
www.bzflag.org


//****************** plug-in entry points  ************************************

There are 3 primary entry points into the plug-in. These are the 3 core
functions that the plugin must implement. The first 2 are the main functions
used by the plugin, these are defined as such;

BZF_PLUGIN_CALL int bz_Load ( const char* command );
BZF_PLUGIN_CALL int bz_Unload ( void );

bz_Load is called when the plug-in is first initialized. This is when the plug-in
should register any event handlers that it wishes to use and initialize any "one
time" startup data.

bz_Unload is called when a plug-in is no longer needed and will be shut down. This
is most commonly called when bzfs is quiting. A plug-in should do any clean up
in this callback.

Both functions should be proceded with the BZF_PLUGIN_CALL macro. This 
macro will tell your compiler to export these functions so bzfs can call them.

The last function is defined as;
BZF_PLUGIN_CALL int bz_GetVersion ( void );

bz_GetVersion is called buy bzfs before any other functions are called.
The function should return the version of the API that it is writen for.
This is to prevent bzfs from atempting to load incompatable plugins.

There is a C++ MACRO defined to ease the implementation of this function.
All a plugin must do is put the macro;
BZ_GET_PLUGIN_VERSION
somewhere in it's sources, and then export the function. This will automaticly
return the API version of the current API you are using. See the sample plugins
for exmaples.

These will be the only 3 functions called by bzfs for non event actions.


//****************** general plugin execution *****************************

The basic idea behind a plugin flow is as follows;

Plugin is loaded.
Plugin regisers event handlers for any events it cares to know about.
BZFS runs.
BZFS calls installed event handlers as the event condtions happen.
Code in plugin handalers modify the data used but the event, or 
   perform new actions based on the event using other API functions.
BZFS returns from the event call and uses any modified data.
BZFS runs till it's final termius as normal repeating any event calls
  as they happen.
Plugin is unloaded when bzfs is quit, or plugin is manual unloaded using
 /unloadplugin command
Plugin unregisters any event handalers it had installed.


This allows for a plugin to do many difrent things depending on what events
it hooks itself into. Plugins can hook into any number of events they wish
and are allowed to do anything the develper wishes to do. A plugin does not
have access to 100% of the internals of BZFS. It must access it by using
the BZFSAPI set of functions as described below. Most of these API functions
will directly map to internal bzfs functions. In fact there are many cases
where internal features of bzfs use the same API functions that plugins can
use. Plugins may also link in any external library and call any external functions
or code that they wish.

As allways open source projects are evolving. If you do not see an API function
that you need, please let us know and we can try to add it for you, or code it
in yourself, and submit it as a patch.


//****************** BZFSAPI data types			*****************************
Due to how windows handles memory access between an application and dynamicly
loaded DLLs, there are a few custom data types that are used in the API. These
are used for common STL style contatiners, for strings and lists.

Any text passed back from the API or events will come in the form of a 
bzApiString. This is a class defined in the API that behaves much like a std::string.
The c_str() method can be used to get the text out as a normal const char*.
The class also supports many assignment functions for seting it's contents.

A few API functions require lists of integers, strings, or floats. For these functions
The plugin will need to use the bzAPIIntList, bzAPIFloatList, or bzAPIStringList classes.
These classes are similar to the std::vector. When a plugin needs to allocate one
of these lists, it must use the approriate allocator fucntion, to tell the API
to make a new list for the plugin to use. These functions are bz_newIntList, bz_newFloatList, 
and bz_newStringList. These will return a pointer to a new list for the plugin to use.
When the plugin is finshes with the list, it needs to remove the list with a call
to bz_deleteIntList, bz_deleteFloatList, or bz_deleteStringList as aproprate.

Sadly these are a litte clunky but are requred to let bzfs allocate any memory it may free
on windows. Hopefully future releases of windows will remove this limitation.

//****************** registering event handlers  *****************************

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, int team,
                        bz_EventHandler* eventHandler );

where eventType is one of the following enumerations;

	bz_eCaptureEvent				// 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 posttion for a player.
	bz_eGetAutoTeamEvent,			// The server is asigning a player to a team automaticly.
	bz_eAllowPlayer,				// The server is about to allow or disalow 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.

team is an integer that defines a team filter for the event. The value of; BZ_ALL_USERS indicates
that the event will be called every time it happens, regardless of team.

eventHandler is a pointer to a event handler class. Plug-ins 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 plug-ins unload function is called. The plug-in must remove any events it has loaded
by calling

bool bz_removeEvent ( bz_teEventType eventType, int team,
                        bz_EventHandler* eventHandler );

Failure to do so may cause crashes if the plug-in is manualy unloaded at run time.


Event Handlers;

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 event types are as follows, along with there associated data items.
Some events may share event data types

bz_eCaptureEvent provides the folowing data;
bz_CTFCaptureEventData
{
	int 	teamCaped;		// the team that had there flag captured
	int		teamCaping;		// the team that did the capturing
	int		playerCaping;	// 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 event
}
Handle this event when you want to do something when ever somone caputures a team flag.
Usefull for events like clearing bases, tracking scores, or playing sounds.

bz_ePlayerDieEvent provides the folowing data;
bz_PlayerDieEventData
{
	int			playerID;			// the ID of the player who died
	int			teamID;				// the team of the player who died
	int			killerID;			// the ID of the player doing the killing
	int			killerTeamID;		// the team of the killer
	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 even is called when ever a player is killed.

bz_ePlayerSpawnEvent provides the folowing data;
bz_PlayerSpawnEventData
{
	int playerID					// the ID of the player that has spawned;
	int teamID;						// the Team the player just spawned to
	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 somone has spawned, and where they have spawned at.
This event does not let you set the spaw position, it is only called AFTER the spawn has been 
computed and sent to the playes.

bz_ePlayerJoinEvent AND bz_ePlayerPartEvent both provide the folowing data;
bz_PlayerJoinPartEventData()
{
	int playerID;					// the ID of the user that has joined or parted
	int teamID;						// 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 folowing 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
	bzApiString message;			// the message
	double time;					// the time of the message
}
This event is called when ever 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 aditional 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.

bz_eUnknownSlashCommand provides the folowing data;
bz_UnknownSlashCommandEventData
{
	int from;						// the player ID of who the message is from
	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 message
	double time;					// the time of the message
}
This event is called when a user atempts to use a / comand that does not exist.
It is not very usefull for anything other then error reporting. If you wish to
install your own custom / command then use the customSlashCommand functions.

bz_eGetPlayerSpawnPosEvent provides the folowing data;
bz_GetPlayerSpawnPosEventData(
{
	int playeID;					// the player ID of who needs to be spawned
	int teamID;						// the players team
	bool handled;					// flag that tells the plugin if the command
									// has allready been handled.
									// if the plugin handles this command
									// it must set this value to true on return
	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 it's 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 modifys the spawn data it too should set the "handled" bit to true.

bz_eAllowPlayer provides the folowing data;
bz_AllowPlayerEventData
{	
	int playerID;				// the player ID of the joining player
	bzApiString callsign;		// the callsign of the player
	bzApiString ipAddress;		// the address of the player
	bzApiString reason;			// a reason string with the reason the player is to be disalowed 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 it's 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 folowing 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
automaticly by bzfs every time it has completed one of it's normal execution loops.
This event is usefull when plugins need to perform update actions, periodic mentance,
or other actions that are not direclty 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 folowing 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.


//****************** calling bzfs functions  *****************************

Once you have your event in place, you need to do something with all this
data. To handle this the API provides a number of functions that can be
called directly. These functions will perform actions and return data about
the current game state.

The functions are as follows;

BZF_API bool bz_getPlayerByIndex ( int index, bz_PlayerRecord *playerRecord );
This function will take a player index, and fill out the passed in player data
class.

The player data class contains the following data;

bz_PlayerRecord
{
	int playerID;							// id of the player
	bzApiString callsign;					// callsign the player is using
	int team;								// team 

	float pos[3];							// last known position
	float rot;								// last known heading

	bzApiString ipAddress;					// the network address for this connection
	
	bzApiString currentFlag;				// the flag the user presently has
	std::vector<bzApiString> flagHistory;	// a list of all flags the user has had

	bool spawned;							// true if the user is in game as a tank
	bool verified;							// true if the user has been authenticated
											// ether global or local
	bool globalUser;						// true if the user was verified from the
											// global login system
	bool admin;								// true if the user is an admin
	std::vector<bzApiString> groups;		// a list of all the groups the user is a member of.
}

bz_PlayerRecord also contains an update() method. This is used to update the data for the player
that may change, like groups, last known state, etc...

BZF_API bool bz_updatePlayerData ( bz_PlayerRecord *playerRecord );
Updates a playerRecord to it's current data. This is the same as calling
update on the bz_PlayerRecord class.

BZF_API bool bz_getPlayerIndexList ( std::vector<int> *playerList )
fills out the supplied list with a list of the IDs of all known users

BZF_API bool bz_sendTextMessage (int from, int to, const char* message);
Sends a text message to the specifid user. BZ_SERVER should be used for
messages from the server. BZ_ALL_USERS for a to user will send the message
to all connected users.

BZF_API bool bz_fireWorldWep ( bzApiString flagType, float lifetime, 
								int fromPlayer, float *pos, float tilt,
								float direction, int shotID , float dt )
Adds a shot to the world of the specified type with the specified paramaters.
BZ_SERVER should be used as the fromPlayer for normal world weapons.

BZF_API double bz_getCurrentTime ( void );
Returns the current server time in seconds ( time server has been alive ).

BZF_API double bz_getBZDBDouble ( const char* variable );
Querys the BZDB database for the specified value and returns it as a double;

BZF_API void bz_debugMessage ( int debugLevel, const char* message );
Outputs the specified message if the current debug level is at least the
specified level.

BZF_API bool bz_kickUser ( int playerIndex, const char* reason, bool notify )
Removes the specified user from the server.

BZF_API bool bz_IPBanUser ( int playerIndex, const char* ip, int time, const char* reason )
Adds an entry to the main banlist with the specified data.

BZF_API bool bz_getStandardSpawn ( int playeID, float pos[3], float *rot );
Returns a normal spawn position for the specified user.

BZF_API bool bz_killPlayer ( int playeID, bool spawnOnBase );
Kills the specified player. If spawnOnBase is true, then the user will
respawn back at his CTF base.

//****************** custom slash commands *****************************
A plug-in can register a special handler for a custom / command. This allows
a plug-in to handle commands easyer then hooking into the UnknownSlashCommand
Event.

Similar to other events, custom slash commands provide a pointer to a handler
class that the plugin overides using the function.

BZF_API bool bz_registerCustomSlashCommand ( const char* command, bz_CustomSlashCommandHandler *handler );


the handler pointer is to a class that has been derived from bz_CustomSlashCommandHandler

class bz_CustomSlashCommandHandler
{
public:
	virtual ~bz_CustomSlashCommandHandler(){};
	virtual bool handle ( int playerID, bzApiString command, bzApiString message ) = 0;
};

When a player issues the command, the handler will have it's handle method called.
And it can then do what ever it needs.

when a command is no longer needed it can be removed with.
BZF_API bool bz_removeCustomSlashCommand ( const char* command );

Only one custom slash command can be installed at a time.


//****************** examples *****************************

    get some..

<commit_msg>add instructions on how to make a new plugin from the template<commit_after>//*****************************************************************************
//***                             bzAPI.txt                                 ***
//***                    Plug-in development for BZFlag                     ***
//*****************************************************************************


* This document:

This document is a description of the bzflag plug-in system and it's associated
API. It will atempt to explain how to make a plug-in, what you can do in a
plug-in and what the basic API features are.

* What is a plug-in

A plug-in is a compiled code module that is loadable at runtime by the BZFlag
game server (bzfs) that can change the way that the server runs. Since plug-ins
are compiled Plug-ins need to be built on the platform they are to be run with.
This means that a plug-in built for windows will not work on linux, and vice/
versa. Plug-ins are writen in C++ as Dynamic Librarys, ether as a DLL on windows
or a .so file on linux/OS X.

* What can a plug-in do.

Plugins can install event handlers for a number of events in bzfs. Events are
actions that happen in the game, such as the capture of a team flag, or the death
of a player. Plug-ins can then call API functions that can change the gamestate
in response to the event, such as sending a text message, activating a world
weapon, or kicking a player. All plug-in actions are event driven. A plugin is
allways called first by the server in response to an action.

* What do I need to make a plug-in, and what do I need to know.

To make a plug-in you will need to know at least C and should be familar with
the C++ language. Many of the API calls and structures will use C++, but they 
can be called in a C "style" if you wish. Since plug-ins are compiled code you
will need a compiler for your OS and the knowledge of how to use it. The sample
plugin has makefiles and Windows VC projects that you can use as a basis. 
If you are on windows, there is a free version of visual studio that you cean
use to build plugins. You can download it for free from 
http://lab.msdn.microsoft.com/express/visualc/default.aspx . You will allso 
need access to some of the source files from the bzflag source distribution.
If you are on windows, the required header and library files are included with
the installer in the API folder. Other OSs can get the full source tree from
www.bzflag.org

* How do I start a new plugin project

If you are not familar with making projects and using makefiles, the bzflag source
tree provides a template plugin in /plugins/SAMPLE_PLUGIN/. This is an empty plugin
project for most OSs. All you have to do is replace the term SAMPLE_PLUGIN with 
your plugin name. Do this to every file name that contains the term SAMPLE_PLUGIN.
Also open each file ( even the .sln and .vcprog, don't double click them yet)
in a text editor ( notepad ) and do a search and replace.
Replace SAMPLE_PLUGIN with your plugin name. The project will then be ready to build.


//****************** plug-in entry points  ************************************

There are 3 primary entry points into the plug-in. These are the 3 core
functions that the plugin must implement. The first 2 are the main functions
used by the plugin, these are defined as such;

BZF_PLUGIN_CALL int bz_Load ( const char* command );
BZF_PLUGIN_CALL int bz_Unload ( void );

bz_Load is called when the plug-in is first initialized. This is when the plug-in
should register any event handlers that it wishes to use and initialize any "one
time" startup data.

bz_Unload is called when a plug-in is no longer needed and will be shut down. This
is most commonly called when bzfs is quiting. A plug-in should do any clean up
in this callback.

Both functions should be proceded with the BZF_PLUGIN_CALL macro. This 
macro will tell your compiler to export these functions so bzfs can call them.

The last function is defined as;
BZF_PLUGIN_CALL int bz_GetVersion ( void );

bz_GetVersion is called buy bzfs before any other functions are called.
The function should return the version of the API that it is writen for.
This is to prevent bzfs from atempting to load incompatable plugins.

There is a C++ MACRO defined to ease the implementation of this function.
All a plugin must do is put the macro;
BZ_GET_PLUGIN_VERSION
somewhere in it's sources, and then export the function. This will automaticly
return the API version of the current API you are using. See the sample plugins
for exmaples.

These will be the only 3 functions called by bzfs for non event actions.


//****************** general plugin execution *****************************

The basic idea behind a plugin flow is as follows;

Plugin is loaded.
Plugin regisers event handlers for any events it cares to know about.
BZFS runs.
BZFS calls installed event handlers as the event condtions happen.
Code in plugin handalers modify the data used but the event, or 
   perform new actions based on the event using other API functions.
BZFS returns from the event call and uses any modified data.
BZFS runs till it's final termius as normal repeating any event calls
  as they happen.
Plugin is unloaded when bzfs is quit, or plugin is manual unloaded using
 /unloadplugin command
Plugin unregisters any event handalers it had installed.


This allows for a plugin to do many difrent things depending on what events
it hooks itself into. Plugins can hook into any number of events they wish
and are allowed to do anything the develper wishes to do. A plugin does not
have access to 100% of the internals of BZFS. It must access it by using
the BZFSAPI set of functions as described below. Most of these API functions
will directly map to internal bzfs functions. In fact there are many cases
where internal features of bzfs use the same API functions that plugins can
use. Plugins may also link in any external library and call any external functions
or code that they wish.

As allways open source projects are evolving. If you do not see an API function
that you need, please let us know and we can try to add it for you, or code it
in yourself, and submit it as a patch.


//****************** BZFSAPI data types			*****************************
Due to how windows handles memory access between an application and dynamicly
loaded DLLs, there are a few custom data types that are used in the API. These
are used for common STL style contatiners, for strings and lists.

Any text passed back from the API or events will come in the form of a 
bzApiString. This is a class defined in the API that behaves much like a std::string.
The c_str() method can be used to get the text out as a normal const char*.
The class also supports many assignment functions for seting it's contents.

A few API functions require lists of integers, strings, or floats. For these functions
The plugin will need to use the bzAPIIntList, bzAPIFloatList, or bzAPIStringList classes.
These classes are similar to the std::vector. When a plugin needs to allocate one
of these lists, it must use the approriate allocator fucntion, to tell the API
to make a new list for the plugin to use. These functions are bz_newIntList, bz_newFloatList, 
and bz_newStringList. These will return a pointer to a new list for the plugin to use.
When the plugin is finshes with the list, it needs to remove the list with a call
to bz_deleteIntList, bz_deleteFloatList, or bz_deleteStringList as aproprate.

Sadly these are a litte clunky but are requred to let bzfs allocate any memory it may free
on windows. Hopefully future releases of windows will remove this limitation.

//****************** registering event handlers  *****************************

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, int team,
                        bz_EventHandler* eventHandler );

where eventType is one of the following enumerations;

	bz_eCaptureEvent				// 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 posttion for a player.
	bz_eGetAutoTeamEvent,			// The server is asigning a player to a team automaticly.
	bz_eAllowPlayer,				// The server is about to allow or disalow 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.

team is an integer that defines a team filter for the event. The value of; BZ_ALL_USERS indicates
that the event will be called every time it happens, regardless of team.

eventHandler is a pointer to a event handler class. Plug-ins 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 plug-ins unload function is called. The plug-in must remove any events it has loaded
by calling

bool bz_removeEvent ( bz_teEventType eventType, int team,
                        bz_EventHandler* eventHandler );

Failure to do so may cause crashes if the plug-in is manualy unloaded at run time.


Event Handlers;

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 event types are as follows, along with there associated data items.
Some events may share event data types

bz_eCaptureEvent provides the folowing data;
bz_CTFCaptureEventData
{
	int 	teamCaped;		// the team that had there flag captured
	int		teamCaping;		// the team that did the capturing
	int		playerCaping;	// 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 event
}
Handle this event when you want to do something when ever somone caputures a team flag.
Usefull for events like clearing bases, tracking scores, or playing sounds.

bz_ePlayerDieEvent provides the folowing data;
bz_PlayerDieEventData
{
	int			playerID;			// the ID of the player who died
	int			teamID;				// the team of the player who died
	int			killerID;			// the ID of the player doing the killing
	int			killerTeamID;		// the team of the killer
	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 even is called when ever a player is killed.

bz_ePlayerSpawnEvent provides the folowing data;
bz_PlayerSpawnEventData
{
	int playerID					// the ID of the player that has spawned;
	int teamID;						// the Team the player just spawned to
	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 somone has spawned, and where they have spawned at.
This event does not let you set the spaw position, it is only called AFTER the spawn has been 
computed and sent to the playes.

bz_ePlayerJoinEvent AND bz_ePlayerPartEvent both provide the folowing data;
bz_PlayerJoinPartEventData()
{
	int playerID;					// the ID of the user that has joined or parted
	int teamID;						// 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 folowing 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
	bzApiString message;			// the message
	double time;					// the time of the message
}
This event is called when ever 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 aditional 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.

bz_eUnknownSlashCommand provides the folowing data;
bz_UnknownSlashCommandEventData
{
	int from;						// the player ID of who the message is from
	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 message
	double time;					// the time of the message
}
This event is called when a user atempts to use a / comand that does not exist.
It is not very usefull for anything other then error reporting. If you wish to
install your own custom / command then use the customSlashCommand functions.

bz_eGetPlayerSpawnPosEvent provides the folowing data;
bz_GetPlayerSpawnPosEventData(
{
	int playeID;					// the player ID of who needs to be spawned
	int teamID;						// the players team
	bool handled;					// flag that tells the plugin if the command
									// has allready been handled.
									// if the plugin handles this command
									// it must set this value to true on return
	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 it's 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 modifys the spawn data it too should set the "handled" bit to true.

bz_eAllowPlayer provides the folowing data;
bz_AllowPlayerEventData
{	
	int playerID;				// the player ID of the joining player
	bzApiString callsign;		// the callsign of the player
	bzApiString ipAddress;		// the address of the player
	bzApiString reason;			// a reason string with the reason the player is to be disalowed 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 it's 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 folowing 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
automaticly by bzfs every time it has completed one of it's normal execution loops.
This event is usefull when plugins need to perform update actions, periodic mentance,
or other actions that are not direclty 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 folowing 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.


//****************** calling bzfs functions  *****************************

Once you have your event in place, you need to do something with all this
data. To handle this the API provides a number of functions that can be
called directly. These functions will perform actions and return data about
the current game state.

The functions are as follows;

BZF_API bool bz_getPlayerByIndex ( int index, bz_PlayerRecord *playerRecord );
This function will take a player index, and fill out the passed in player data
class.

The player data class contains the following data;

bz_PlayerRecord
{
	int playerID;							// id of the player
	bzApiString callsign;					// callsign the player is using
	int team;								// team 

	float pos[3];							// last known position
	float rot;								// last known heading

	bzApiString ipAddress;					// the network address for this connection
	
	bzApiString currentFlag;				// the flag the user presently has
	std::vector<bzApiString> flagHistory;	// a list of all flags the user has had

	bool spawned;							// true if the user is in game as a tank
	bool verified;							// true if the user has been authenticated
											// ether global or local
	bool globalUser;						// true if the user was verified from the
											// global login system
	bool admin;								// true if the user is an admin
	std::vector<bzApiString> groups;		// a list of all the groups the user is a member of.
}

bz_PlayerRecord also contains an update() method. This is used to update the data for the player
that may change, like groups, last known state, etc...

BZF_API bool bz_updatePlayerData ( bz_PlayerRecord *playerRecord );
Updates a playerRecord to it's current data. This is the same as calling
update on the bz_PlayerRecord class.

BZF_API bool bz_getPlayerIndexList ( std::vector<int> *playerList )
fills out the supplied list with a list of the IDs of all known users

BZF_API bool bz_sendTextMessage (int from, int to, const char* message);
Sends a text message to the specifid user. BZ_SERVER should be used for
messages from the server. BZ_ALL_USERS for a to user will send the message
to all connected users.

BZF_API bool bz_fireWorldWep ( bzApiString flagType, float lifetime, 
								int fromPlayer, float *pos, float tilt,
								float direction, int shotID , float dt )
Adds a shot to the world of the specified type with the specified paramaters.
BZ_SERVER should be used as the fromPlayer for normal world weapons.

BZF_API double bz_getCurrentTime ( void );
Returns the current server time in seconds ( time server has been alive ).

BZF_API double bz_getBZDBDouble ( const char* variable );
Querys the BZDB database for the specified value and returns it as a double;

BZF_API void bz_debugMessage ( int debugLevel, const char* message );
Outputs the specified message if the current debug level is at least the
specified level.

BZF_API bool bz_kickUser ( int playerIndex, const char* reason, bool notify )
Removes the specified user from the server.

BZF_API bool bz_IPBanUser ( int playerIndex, const char* ip, int time, const char* reason )
Adds an entry to the main banlist with the specified data.

BZF_API bool bz_getStandardSpawn ( int playeID, float pos[3], float *rot );
Returns a normal spawn position for the specified user.

BZF_API bool bz_killPlayer ( int playeID, bool spawnOnBase );
Kills the specified player. If spawnOnBase is true, then the user will
respawn back at his CTF base.

//****************** custom slash commands *****************************
A plug-in can register a special handler for a custom / command. This allows
a plug-in to handle commands easyer then hooking into the UnknownSlashCommand
Event.

Similar to other events, custom slash commands provide a pointer to a handler
class that the plugin overides using the function.

BZF_API bool bz_registerCustomSlashCommand ( const char* command, bz_CustomSlashCommandHandler *handler );


the handler pointer is to a class that has been derived from bz_CustomSlashCommandHandler

class bz_CustomSlashCommandHandler
{
public:
	virtual ~bz_CustomSlashCommandHandler(){};
	virtual bool handle ( int playerID, bzApiString command, bzApiString message ) = 0;
};

When a player issues the command, the handler will have it's handle method called.
And it can then do what ever it needs.

when a command is no longer needed it can be removed with.
BZF_API bool bz_removeCustomSlashCommand ( const char* command );

Only one custom slash command can be installed at a time.


//****************** examples *****************************

    get some..


{'fraction_non_alphanumeric': 0.059403669724770645, 'fraction_numerical': 0.0006422018348623853, 'mean_word_length': 3.6517657100181373, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2082376', 'n_tokens_mistral': 12374, 'n_tokens_neox': 11528, 'n_words': 6735}