This wiki is archived and useful information is being migrated to the main bzflag.org website

Difference between revisions of "Functions (API)"

From BZFlagWiki
Jump to: navigation, search
(Added bz_getPlayerFlagID() to the documentation)
m (Added link to bz_getPausedTime())
Line 115: Line 115:
 
  BZF_API float [[bz_getPlayerPacketloss]] ( int playerId );
 
  BZF_API float [[bz_getPlayerPacketloss]] ( int playerId );
 
  BZF_API int [[bz_getIdleTime]] ( int playerId );
 
  BZF_API int [[bz_getIdleTime]] ( int playerId );
 +
BZF_API int [[bz_getPausedTime]] ( int playerId );
  
 
=== Permission Group Management ===
 
=== Permission Group Management ===

Revision as of 05:08, 30 January 2014

Plywood hammer100x101.gif There is still documentation to be done here!! If you feel up to the task, please have a go at it. Specifically what needs to be added is:

Fill in articles for all API Functions
Finish updating to 2.3.x
Verify future API functions.


BZFS API Documentation This page contains part of the BZFS API documentation for use by Plug-ins on the BZFS server.


Overview

The BZFS API provides a number of functions to plug-ins for use in querying the current game state. Functions are used both to get information about the game, and to trigger in game actions, such as activating a world weapon.

Function Groups

Functions are broken into a series of groups based on the type of action or information they deal with.

Event Registration

2.0.x

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

2.3+

BZF_API bool Register ( bz_eEventType eventType );
virtual void Cleanup() {Flush();}

Non-Player Connections

2.3+

BZF_API bool bz_registerNonPlayerConnectionHandler ( int connectionID, bz_NonPlayerConnectionHandler* handler );
BZF_API bool bz_removeNonPlayerConnectionHandler ( int connectionID, bz_NonPlayerConnectionHandler* handler );
BZF_API bool bz_sendNonPlayerData ( int connectionID, const void *data, unsigned int size );
BZF_API bool bz_disconectNonPlayerConnection ( int connectionID );
BZF_API unsigned int bz_getNonPlayerConnectionOutboundPacketCount ( int connectionID );
BZF_API const char* bz_getNonPlayerConnectionIP ( int connectionID );
BZF_API const char* bz_getNonPlayerConnectionHost ( int connectionID );

Player Information

Player Information

2.3+

BZF_API bool bz_hasPerm ( int playerID, const char* perm );
BZF_API bool bz_getAdmin ( int playerID );
BZF_API bz_eTeamType bz_getPlayerTeam ( int playerID );
BZF_API const char* bz_getPlayerCallsign ( int playerID );
BZF_API const char* bz_getPlayerIPAddress ( int playerID );
BZF_API const char* bz_getPlayerFlag ( int playerID );

?

BZF_API const char* bz_getPlayerReferrer ( int playerID );
BZF_API const char* bz_getPlayerCustomData (int playerID, const char* key );

Player State Information

2.3+

BZF_API bool bz_isPlayerPaused ( int playerID );
BZF_API bool bz_canPlayerSpawn( int playerID );
BZF_API bool bz_getPlayerCurrentState ( int playerID, bz_PlayerUpdateState &state );

?

BZF_API bool bz_getPlayerPosition ( int playerID, float pos[3], bool extrapolate );
BZF_API bool bz_getPlayerRotation ( int playerID, float *rot, bool extrapolate );
BZF_API bool bz_getPlayerVelocity ( int playerID, float vel[3] );
BZF_API bool bz_getPlayerAngVel ( int playerID, float *angvel );
BZF_API bool bz_getPlayerPhysicsDriver ( int playerID, int* phydrv );

Player Lists and Records

2.3+

BZF_API bz_BasePlayerRecord *bz_getPlayerByIndex ( int index );
BZF_API bool bz_updatePlayerData ( bz_BasePlayerRecord *playerRecord );
BZF_API bool bz_freePlayerRecord ( bz_BasePlayerRecord *playerRecord );
BZF_API bz_APIIntList *bz_newIntList ( void );
BZF_API bz_APIIntList *bz_getPlayerIndexList ( void );
BZF_API bool bz_getPlayerIndexList ( bz_APIIntList *playerList );
BZF_API void bz_deleteIntList ( bz_APIIntList *l);

Unknown

BZF_API bz_BasePlayerRecord *bz_getPlayerByBZID ( int BZID );
BZF_API bz_BasePlayerRecord *bz_getPlayerByCallsign ( const char* name );

Player Management

2.3+

BZF_API bool bz_grantPerm ( int playerID, const char* perm );
BZF_API bool bz_revokePerm ( int playerID, const char* perm );
BZF_API bool bz_validAdminPassword ( const char* passwd );
BZF_API bool bz_setPlayerOperator ( int playerId );

?

BZF_API bool bz_setPlayerSpawnable( int playerID, bool spawn );
BZF_API bool bz_setPlayerLimboMessage( int playerID, const char* text );
BZF_API bool bz_setPlayerCustomData (int playerID, const char* key, const char* data );

Team Management

2.3+

BZF_API unsigned int bz_getTeamPlayerLimit ( bz_eTeamType team );
BZF_API int bz_getTeamCount (bz_eTeamType team );
BZF_API int bz_getTeamScore (bz_eTeamType team );
BZF_API int bz_getTeamWins (bz_eTeamType team );
BZF_API int bz_getTeamLosses (bz_eTeamType team );
BZF_API void bz_setTeamWins (bz_eTeamType team, int wins );
BZF_API void bz_setTeamLosses (bz_eTeamType team, int losses );
BZF_API void bz_resetTeamScore (bz_eTeamType team );
BZF_API void bz_resetTeamScores ( void );

?

BZF_API void bz_changeTeam( int player, bz_eTeamType team );

Score Management

2.3+

BZF_API bool bz_setPlayerWins ( int playerId, int wins );
BZF_API bool bz_setPlayerLosses ( int playerId, int losses );
BZF_API bool bz_setPlayerTKs ( int playerId, int tks );
BZF_API bool bz_resetPlayerScore ( int playerId );
BZF_API int bz_getPlayerWins ( int playerId );
BZF_API int bz_getPlayerLosses ( int playerId );
BZF_API int bz_getPlayerTKs ( int playerId );
BZF_API float bz_getPlayerRank ( int playerId );

Latency Information

2.3+

BZF_API int bz_getPlayerLag ( int playerId );
BZF_API int bz_getPlayerJitter ( int playerId );
BZF_API float bz_getPlayerPacketloss ( int playerId );
BZF_API int bz_getIdleTime ( int playerId );
BZF_API int bz_getPausedTime ( int playerId );

Permission Group Management

2.3+

BZF_API bz_APIStringList* bz_getGroupList ( void );
BZF_API bz_APIStringList* bz_getGroupPerms ( const char* group );
BZF_API bool bz_groupAllowPerm ( const char* group, const char* perm );

Chat Messages

2.3+

BZF_API bool bz_sendTextMessage (int from, int to, const char* message);
BZF_API bool bz_sendTextMessage (int from, bz_eTeamType to, const char* message);
BZF_API bool bz_sendTextMessagef (int from, int to, const char* fmt, ...);
BZF_API bool bz_sendTextMessagef (int from, bz_eTeamType to, const char* fmt, ...);

?

BZF_API bool bz_sendFetchResMessage ( int playerID,  const char* URL );
BZF_API bool bz_sendJoinServer ( int playerID, const char* address, int port, int team, const char* referrer, const char* message );
BZF_API bool bz_sendLuaData ( int dstPlayerID, int dstScriptID, int statusBits, const char* data, int len,
                              int srcPlayerID = 0, int srcScriptID = 0 );

Server Management

2.3+

BZF_API bool bz_restart ( void );
BZF_API void bz_shutdown ();
BZF_API void bz_superkill ();
BZF_API void bz_gameOver ( int playerID, bz_eTeamType = eNoTeam );
BZF_API void bz_reloadLocalBans ();
BZF_API void bz_reloadMasterBans ();
BZF_API void bz_reloadGroups ();
BZF_API void bz_reloadUsers ();
BZF_API void bz_reloadHelp ();
BZF_API int bz_getPlayerCount ( void );
BZF_API bool bz_getShotMismatch ( void );
BZF_API void bz_setShotMismatch ( bool value );

?

BZF_API bool bz_anyPlayers ( void );

Rabbit Hunt

?

BZF_API void bz_newRabbit ( int player, bool swap );
BZF_API void bz_removeRabbit ( int player );

Map Management

2.3+

BZF_API void bz_setClientWorldDownloadURL ( const char* URL );
BZF_API const bz_ApiString bz_getClientWorldDownloadURL ( void );
BZF_API bool bz_saveWorldCacheFile ( const char* file );

Flag Management

2.3+

BZF_API bool bz_givePlayerFlag ( int playerID, const char* flagType, bool force );
BZF_API bool bz_removePlayerFlag ( int playerID );
BZF_API void bz_resetFlags ( bool onlyUnused, bool keepTeamFlags = false );
BZF_API unsigned int bz_getNumFlags ( void );
BZF_API const bz_ApiString bz_getName ( int flag );
BZF_API bool bz_resetFlag ( int flag );
BZF_API int bz_flagPlayer ( int flag );
BZF_API int bz_getPlayerFlagID ( int playerID );
BZF_API bool bz_getFlagPosition ( int flag, float* pos );
BZF_API bool bz_moveFlag ( int flag, float pos[3] );
BZF_API bool bz_RegisterCustomFlag ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

Shot Type Control

?

BZF_API bool bz_setPlayerShotType ( int playerId, bz_eShotType shotType );

World Weapon Management

2.3+

BZF_API bool bz_fireWorldWep ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API int bz_fireWorldGM ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt, bz_eTeamType shotTeam = eRogueTeam );

Server Time

2.3+

BZF_API double bz_getCurrentTime ( void );
BZF_API void bz_getLocaltime ( bz_Time *ts );
BZF_API void bz_getUTCtime ( bz_Time *ts );

?

BZF_API float bz_getMaxWaitTime ( void );
BZF_API void bz_setMaxWaitTime ( float maxTime );

Global Database Management (BZDB)

2.3+

BZF_API double bz_getBZDBDouble ( const char* variable );
BZF_API bz_ApiString bz_getBZDBString ( const char* variable );
BZF_API bool bz_getBZDBBool ( const char* variable );
BZF_API int bz_getBZDBInt ( const char* variable );
BZF_API int bz_getBZDBItemPerms ( const char* variable );
BZF_API bool bz_getBZDBItemPesistent ( const char* variable );
BZF_API bool bz_BZDBItemExists ( const char* variable );
BZF_API bool bz_setBZDBDouble ( const char* variable, double val, int perms = 0, bool persistent = false );
BZF_API bool bz_setBZDBString ( const char* variable, const char *val, int perms = 0, bool persistent = false  );
BZF_API bool bz_setBZDBBool ( const char* variable, bool val, int perms = 0, bool persistent = false  );
BZF_API bool bz_setBZDBInt ( const char* variable, int val, int perms = 0, bool persistent = false  );
BZF_API int bz_getBZDBVarList ( bz_APIStringList	*varList );
BZF_API void bz_resetBZDBVar ( const char* variable );
BZF_API void bz_resetALLBZDBVars ( void );

Logging

2.3+

BZF_API void bz_debugMessage ( int level, const char* message );
BZF_API void bz_debugMessagef ( int level, const char* fmt, ... )
BZF_API int bz_getDebugLevel ( void );

Server Administration

2.3+

BZF_API bool bz_kickUser ( int playerIndex, const char* reason, bool notify );
BZF_API bool bz_IPBanUser ( int bannedByIndex, const char* ip, int duration, const char* reason );
BZF_API bool bz_HostBanUser ( int bannedByIndex, const char* hostmask, int duration, const char* reason );
BZF_API bool bz_IPUnbanUser ( const char* ip );
BZF_API bool bz_IDUnbanUser ( const char* bzID );
BZF_API bool bz_HostUnbanUser ( const char* hostmask );

BZF_API int bz_getLagWarn ( void );
BZF_API bool bz_setLagWarn ( int lagwarn );
BZF_API bool bz_pollActive ( void );
BZF_API bool bz_pollVeto ( void );

?

BZF_API bool bz_IDBanUser ( int bannedByIndex, const char* bzID , int duration, const char *reason );

Reporting

2.3+

BZF_API bz_APIStringList* bz_getReports ( void );

?

BZF_API unsigned int bz_getReportCount ( void );
BZF_API const char* bz_getReportSource ( unsigned int id );
BZF_API const char* bz_getReportBody ( unsigned int id );
BZF_API const char* bz_getReportTime ( unsigned int id );
BZF_API bool bz_clearReport ( unsigned int id );
BZF_API bool bz_clearAllReports ( void );
BZF_API bool bz_fileReport ( const char* message, const char* from );

Timed Game Management

2.3+

BZF_API bool bz_setTimeLimit ( float timeLimit );
BZF_API float bz_getTimeLimit ( void );
BZF_API bool bz_isTimeManualStart ( void );
BZF_API bool bz_isCountDownActive ( void );
BZF_API bool bz_isCountDownInProgress ( void );
BZF_API bool bz_isCountDownPaused ( void );
BZF_API void bz_pauseCountdown ( const char *pausedBy );
BZF_API void bz_resumeCountdown ( const char *resumedBy );
BZF_API void bz_startCountdown ( int delay, float limit, const char *byWho );

Custom Text Commands

2.3+

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

Plug-in Management

2.3+

BZF_API int bz_getLoadedPlugins ( bz_APIStringList * list );
BZF_API bool bz_loadPlugin ( const char* path, const char* params );
BZF_API bool bz_unloadPlugin ( const char* path );
BZF_API const char* bz_pluginBinPath ( void );
BZF_API bool bz_registerCustomPluginHandler ( const char* extension, bz_APIPluginHandler * handler );
BZF_API bool bz_removeCustomPluginHandler ( const char* extension, bz_APIPluginHandler * handler );

Public Server Information

2.3+

BZF_API bool bz_getPublic ( void );
BZF_API bz_ApiString bz_getPublicAddr ( void );
BZF_API bz_ApiString bz_getPublicDescription ( void );
BZF_API int bz_getPublicPort ( void );
BZF_API void bz_updateListServer ( void );

HTTP Transfer

2.3+

BZF_API bool bz_addURLJob ( const char* URL, bz_BaseURLHandler* handler = NULL, const char* postData = NULL );
BZF_API bool bz_removeURLJob ( const char* URL );

?

BZF_API bool bz_stopAllURLJobs ( void );

Callback Functions

?

BZF_API bool bz_registerCallBack ( const char* name, bz_GenericCallback *callback );
BZF_API bool bz_registerCallBack ( const char* name, bz_GenericCallbackFunc callback );
BZF_API bool bz_removeCallBack ( const char* name, bz_GenericCallback *callback );
BZF_API bool bz_removeCallBack ( const char* name, bz_GenericCallbackFunc callback );
BZF_API bool bz_callCallback ( const char* name, void *param );
BZF_API bool bz_callbackExists ( const char* name );

Inter-Plug-in Communications

2.3+

BZF_API bool bz_clipFieldExists ( const char *name );
BZF_API const char* bz_getclipFieldString ( const char *name );
BZF_API float bz_getclipFieldFloat ( const char *name );
BZF_API int bz_getclipFieldInt ( const char *name );
BZF_API bool bz_setclipFieldString ( const char *name, const char* data );
BZF_API bool bz_setclipFieldFloat ( const char *name, float data );
BZF_API bool bz_setclipFieldInt ( const char *name, int data );
BZF_API bool bz_addClipFieldNotifier ( const char *name, [[bz_ClipFiledNotifier *cb );
BZF_API bool bz_removeClipFieldNotifier ( const char *name, [[bz_ClipFiledNotifier *cb );

Game Recording

2.3+

BZF_API bool bz_saveRecBuf ( const char * _filename, int seconds);
BZF_API bool bz_startRecBuf ( void );
BZF_API bool bz_stopRecBuf ( void );

Map Management

Map Information

?

BZF_API void bz_getWorldSize ( float *size, float *wallHeight );
BZF_API unsigned int bz_getWorldObjectCount ( void );
BZF_API bz_APIWorldObjectList* bz_getWorldObjectList ( void );
BZF_API void bz_releaseWorldObjectList ( bz_APIWorldObjectList *list );
BZF_API unsigned int bz_findWorldObject ( const char *name );
BZF_API bz_APIBaseWorldObject* bz_getWorldObjectByID ( unsigned int id );
BZF_API bool bz_getTeleLinkIDs ( const char* teleName, int* frontLink, int* backLink );
BZF_API const char* bz_getLinkTeleName ( int linkIndex );
BZF_API int bz_getPhyDrvID ( const char* phyDrvName );
BZF_API const char* bz_getPhyDrvName ( unsigned int phyDrvID );
BZF_API bool bz_SetWorldObjectTangibility ( int id, const bz_SolidObjectPassableAtributes &atribs );
BZF_API bool bz_GetWorldObjectTangibility ( int id, bz_SolidObjectPassableAtributes &atribs );
BZF_API void bz_ResetWorldObjectTangibilities ( void );

Map Collisions

?

bz_eAPIColType bz_cylinderInMapObject ( float pos[3], float height, float radius, bz_APIBaseWorldObject **object );
bz_eAPIColType bz_boxInMapObject ( float pos[3], float size[3], float angle, bz_APIBaseWorldObject **object );

Custom Map Objects

2.3+

BZF_API bool bz_registerCustomMapObject ( const char* object, bz_CustomMapObjectHandler *handler );
BZF_API bool bz_removeCustomMapObject ( const char* object );

Utility

2.3+

BZF_API const char *bz_MD5 ( const char* str );
BZF_API const char *bz_MD5 ( const void* data, size_t size );
BZF_API const char *bz_getServerVersion ( void );
BZF_API const char *bz_getProtocolVersion ( void );

Misc

2.3+

BZF_API bool bz_getStandardSpawn ( int playerID, float pos[3], float *rot );
BZF_API bool bz_killPlayer ( int playerID, bool spawnOnBase);
BZF_API bool bz_killPlayer ( int playerID, bool spawnOnBase, int killerID = -1, const char* flagID = NULL );
BZF_API bool bz_sendPlayCustomLocalSound ( int playerID, const char* soundName );
BZF_API bz_ApiString bz_filterPath ( const char* path );
BZF_API const char *bz_format(const char* fmt, ...)_ATTRIBUTE12;
BZF_API const char *bz_toupper(const char* val );
BZF_API const char *bz_tolower(const char* val );
BZF_API const char *bz_urlEncode(const char* val );
BZF_API bz_eGameType bz_getGameType( void );
BZF_API bz_eTeamType bz_checkBaseAtPoint ( float pos[3] );
BZF_API int bz_APIVersion ( void );

?

BZF_API bool bz_allowJumping ( void );

Server Side Players (Development)

? (In API for 2.3+, but will crash a server)

BZF_API int bz_addServerSidePlayer ( bz_ServerSidePlayerHandler *handler );
BZF_API bool bz_removeServerSidePlayer ( int playerID, bz_ServerSidePlayerHandler *handler );

See also

BZFS API

plug-ins