|
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:
Player Data Functions
BZF_API bool bz_getPlayerByIndex ( int index, bz_PlayerRecord *playerRecord
);
This function will take a player index, and will return a new player data object
in the playerRecord paramater. WARNING: this function CAN and WILL
return NULL in certain situations. Always check for NULL before
dereferencing the result of this function, otherwise your plugin may crash the
server. The player data class contains the following data:
bz_PlayerRecord
{
int playerID; // id of the player
bzApiString callsign; // callsign the player is using
bzApiString email; // email address of the player
bz_eTeamType team; // team the player is on
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
bzApiStrList 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
bzApiStrList groups; // a list of all the groups the user is a member of
int wins; // number of times this player has killed another
int losses; // number of times this player has died
int teamKills; // number of times the user has killed a teammate
}
|
| |
|
bz_PlayerRecord
also contains the folowing methods, for ease of use. They just call the
existing player functuions described below
void update ( void );
Calls bz_updatePlayerData on this player.
bool hasPerm ( const char* perm );
Calls bz_hasPerm on this player.
bool grantPerm ( const char* perm );
Calls bz_grantPerm on this player.
bool revokePerm ( const char* perm );
Calls bz_revokePerm on this player.
BZF_API bool bz_updatePlayerData ( bz_PlayerRecord *playerRecord );
Updates a playerRecord to its 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_freePlayerRecord ( bz_PlayerRecord *playerRecord );
This command will free the memory used by a Player Record Object. It must be
called when a plug-in is done using the player data returned from bz_getPlayerByIndex
The following score functions were removed until they can work
properly on all clients.
BZF_API bool bz_setPlayerWins (int
playerId, int wins);
This command will set the number of wins (kills) in the score for the specified player, and update all client scores.
BZF_API bool bz_setPlayerLosses (int playerId, int losses);
This command will set the number of losses(deaths) in the score for the
specified player, and update all client scores.
BZF_API bool bz_setPlayerTKs(int playerId, int tks);
This command will set the number of TKs (teamkills) in the score for the
specified player, and update all client scores.
BZF_API bool bz_resetPlayerScore(int playerId);
This command will reset to zero the score and TKs of the specified player and
update all clients.
Permission functions
The permission functions all take permsision names as input. These names are
the same as the server uses in its users and groups files. All the standard
permission names have been defined in the bzfsAPI.h file using the bz_perm_XXXXXXXX
set of defines. Groups can have custom permissions, so if you want to
use a non standard permission in your plugin, you can also use that name in the
"hasPerm" function. Custom permissions can only be read via the API, they can
not be set. So the user will have to know to enter the permission name into
his/her groups file.
BZF_API bool bz_hasPerm ( int playerID, const char* perm );
This function will return true if the user has the permission named in the perm
paramater
BZF_API bool bz_grantPerm ( int playerID, const char* perm );
This function will give the user the specified permission, and return true if
the operation was successful.
BZF_API bool bz_revokePerm ( int playerID, const char* perm );
This function will remove the specified permision from the user, and return
true if the operation was successful.
Group Functions
BZF_API bzAPIStringList* bz_getGroupList ( void );
This function will return a new string list that contains the all known group
names in the bzfs group database. Be sure to use bz_deleteStringList
to free the list when you are done with the list.
BZF_API bzAPIStringList* bz_getGroupPerms ( const char* group);
Returns a new string list that contains the permision names that the specified
group has rights to. Be sure to use bz_deleteStringList to
free the list when you are done with the list.
BZF_API bool bz_groupAllowPerm ( const char* group, const char* perm);
Returns true if the specified group will allow the specified permision.
Message Functions
BZF_API bool bz_sendTextMessage (int from, int to, const char* message);
Sends a text message to the specified user. BZ_SERVER should
be used for messages from the server. If the message is sent to BZ_ALL_USERS
it will send the message to all connected users. Likewise if it is set to BZ_ADMIN_CHANNEL
it will be sent to all users with the ADMINMESSAGERECEIVE permission.
BZF_API bool bz_sentFetchResMessage ( int playerID, const char* URL );
Sends an update message to the specified player telling them they must have the
file specified in the URL. At present this is only used for sounds files.
World Weapons Functions
BZF_API bool bz_fireWorldWep ( bzApiString flagType, float lifetime, int
fromPlayer, float *pos, float tilt, float direction, int shotID, float dt )
Adds a shot of the specified type and with the specified paramaters to the
world. BZ_SERVER should be used as the fromPlayer for normal
world weapons.
Time Functions
BZF_API double bz_getCurrentTime ( void );
Returns the current server time in seconds ( time server has been alive ).
BZF_API float bz_getMaxWaitTime ( void );
Returns the maximum amount of time in seconds between bz_eTickEvent
events
BZF_API void bz_setMaxWaitTime ( float time );
Sets the maximum amount of time in seconds between bz_eTickEvent
events. If another plugin or the base system has a lower maxium the lowest max
will be used.
BZF_API void bz_getLocaltime ( bz_localTime *ts );
Returns the real world time on the OS of the server into the passed in bz_localTime
structure, witch contains
typedef struct
{
int year;
int month;
int day;
int hour;
int minute;
int second;
bool daylightSavings;
}bz_localTime;
|
|
BZDB Functions
BZF_API double bz_getBZDBDouble ( const char* variable );
Queries the BZDB database for the specified value and returns it as a double
BZF_API bzApiString bz_getBZDBString( const char* variable );
Queries the BZDB database for the specified value and returns it as a string
BZF_API bool bz_getBZDBBool( const char* variable );
Queries the BZDB database for the specified value and returns it as a boolean
(true if value is non zero)
BZF_API int bz_getBZDBInt( const char* variable );
Queries the BZDB database for the specified value and returns it as an integer
BZF_API bool bz_setBZDBDouble ( const char* variable, double val );
Sets the BZDB database item specified to the for the specified floating point
value
BZF_API bool bz_setBZDBString( const char* variable, const char *val );
Sets the BZDB database item specified to the for the specified string value
BZF_API bool bz_setBZDBBool( const char* variable, bool val );
Sets the BZDB database item specified to the for the specified boolean value
BZF_API bool bz_setBZDBInt( const char* variable, int val );
Sets the BZDB database item specified to the for the specified integer value
Logging Functions
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 int bz_getDebugLevel ( void );
Returns BZFS' current debug level. You can use this for more complicated debug
calculations or output.
Player Admin Functions
BZF_API bool bz_kickUser ( int playerIndex, const char* reason, bool notify
);
Removes the specified user from the server. If notify is true, the user and
adminisrators will be notified using the reason.
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_killPlayer ( int playerID, bool spawnOnBase );
Kills the specified player. If spawnOnBase is true, then the user will respawn
back at his CTF base.
Spawn Functions
BZF_API bool bz_getStandardSpawn ( int playeID, float pos[3], float *rot );
Returns a normaly calculated spawn position for the specified user.
Flag Functions
BZF_API bool bz_removePlayerFlag ( int playeID );
Removes (zaps) the flag caried by the specified player
BZF_API void bz_resetFlags ( bool onlyUnused );
Removes (zaps) all flags on the map, exactly the same as the /flag reset
command
Server Info Functions
BZF_API bool bz_getPublic( void );
Returns true if the server is public
BZF_API bzApiString bz_getPublicAddr( void );
Returns the public address the server is using, will return an empty string if
the server is not public
BZF_API bzApiString bz_getPublicDescription( void );
Returns the public description the server is using, will return an empty string
if the server is not public
BZF_API void bz_updateListServer ( void );
Forces the server to do a list server update.
Server Game functions
BZ_API void bz_shutdown();
This command will terminate BZFS.
BZ_API void bz_superkill();
This command will perform a superkill; disconnecting all players.
BZ_API void bz_gameOver(int playerIndex, int teamIndex = -1);
Terminates current game and announces a winner. If teamIndex is -1,
the player is announced as the winner, otherwise the team is.
Team Score Functions
BZF_API int bz_getTeamCount (bz_eTeamType team);
Returns the player count of the specified team
BZF_API int bz_getTeamScore (bz_eTeamType team );
Returns the team score for the specified team
BZF_API int bz_getTeamWins (bz_eTeamType team );
Returns the team wins for the speficied team
BZF_API int bz_getTeamLosses (bz_eTeamType team );
Returns the team losses for the specified team
BZF_API void bz_setTeamWins (bz_eTeamType team, int wins );
Sets the team wins for the speficied team
BZF_API void bz_setTeamLosses (bz_eTeamType team, int losses );
Sets the team losses for the specified team
BZF_API void bz_resetTeamScore (bz_eTeamType team );
Resets to Zero the score for the specified team
Recording Functions
BZF_API bool bz_saveRecBuf( const char * _filename, int seconds);
If a record buffer it active this saves the last 'seconds' seconds of it into
the file '_filename'. If _filename contains non-alphanumeric characters other
than '.' these will be replaced by '_'. If seconds is not given the whole
buffer is saved.
Text Utility Functions
These funtions don't do anything in bzfs, they are just here to help out a
plugin by leting them use some of BZFlags OS independent utilitys.
BZF_API const char *bz_format(const char* fmt, ...);
Just like sprintf, but returs the formated string.
BZF_API const char *bz_toupper(const char* val );;
Returns the input string all in upper case characters.
BZF_API const char *bz_tolower(const char* val );;
Returns the input string all in lower case characters.
World Info Functions
These funtions are used to give infomation about the world ( map ).
BZF_API bz_eTeamType bz_checkBaseAtPoint ( float pos[3] );
This function will return the team that owns the base that is at the requested point. If there is no base at that point then the "NoTeam" team will be returned. This is usefull for knowing where people are at a caputre event.
Custom Slash Command Functions
A plug-in can register a special handler for a custom / command. This allows a
plug-in to handle commands more easily than hooking into the
UnknownSlashCommand Event.
Similar to other events, custom slash commands provide a pointer to a handler
class that the plugin overrides using the function.
BZF_API bool bz_registerCustomSlashCommand ( const char* command,
bz_CustomSlashCommandHandler *handler );
This command will register a cutom slash command with the name provided in the
command paramater. You do NOT need to provide the "/" character in the command
name. 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,
bzAPIStringList *params ) = 0;
};
|
|
When a player issues the command, the handler will have its handle method called
and then it can then do whatever it needs to. The Message parameter to the
handle function will contain all the text the user has entered, except the
/command name itself. The Params item will contain a list of the text broken
into a space delimited list. This is useful for commands that take paramaters.
BZF_API bool bz_removeCustomSlashCommand ( const char* command );
This command will remove a custom slash command from BZFS. Only one custom
slash command per name can be installed at a time. It is a good idea to make
your command name unique.
|
