Editing Functions (API)

{{DoDoc|
Fill in articles for all API Functions<br>
Finish updating to 2.3.x<br>
Verify future API functions.
}}

{{BZFS_API_Doc}}


== 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]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
 BZF_API bool [[bz_removeEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
2.3+
 BZF_API bool [[Register]] ( [[Event(API)|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 [[bz_BasePlayerRecord]] *[[bz_getPlayerBySlotOrCallsign]] ( const char* name );
 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_isPlayerSpawnable]] ( int playerID );
?
 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_incrementTeamWins]] (bz_eTeamType team, int increment);
 BZF_API void [[bz_incrementTeamLosses]] (bz_eTeamType team, int increment);
 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 bool [[bz_incrementPlayerWins]] (int playerId, int increment)
 BZF_API bool [[bz_incrementPlayerLosses]] (int playerId, int increment);
 BZF_API bool [[bz_incrementPlayerTKs]] (int playerId, int increment);
 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_isAutoTeamEnabled]] ( void );
?
 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_getFlagName|bz_getName]] ( int flag );
 BZF_API bool [[bz_resetFlag]] ( int flag );
 BZF_API int [[bz_flagPlayer]] ( int flag );
 BZF_API const char* [[bz_getPlayerFlag]] ( int playerID );
 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 );

=== Shot Management ===
2.4.5+
 BZF_API uint32_t [[bz_getShotMetaData]] (int fromPlayer, int shotID, const char* name);
 BZF_API void [[bz_setShotMetaData]] (int fromPlayer, int shotID , const char* name, uint32_t value);
 BZF_API bool [[bz_shotHasMetaData]] (int fromPlayer, int shotID , const char* name);
 BZF_API uint32_t [[bz_getShotGUID]] (int fromPlayer, int shotID);

=== 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 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 );
 BZF_API void [[bz_cancelCountdown]] ( const char *canceledBy );

=== 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]]

[[Category:BZFS_API_Functions]]