BZFlagWiki - User contributions [en]

BZFlag Source

2011-12-03T11:10:43Z

Sigonasr2: /* Releases and Distribution */ Change link to point to the source files in general instead of version 1.7c.

The BZFlag source code is predominantly written in C/C++and is used by developers to implement the game client, server, and services.

==Overview==
The source code to [http://www.bzflag.org BZFlag] is released as a collective work under the [http://en.wikipedia.org/wiki/LGPL GNU Lesser General Public License] and is freely available to anyone.

BZFlag is primarily written in the [http://en.wikipedia.org/wiki/C%2B%2B C++] language, but does contain some modules written in [http://en.wikipedia.org/wiki/Perl Perl], [http://en.wikipedia.org/wiki/Php PHP], and [http://en.wikipedia.org/wiki/Python_%28programming_language%29 Python].

Developers use the source code to modify and extend the features of the game. It is also used by a number of players to [[:Category:Compiling|compile]] the software into its playable form.

==Organization==
The BZFlag source code is organized into a number of projects or sub sections, to try and keep the software somewhat modular.

There are three primary projects that make up the sofware.
*[[:Category:client|BZFlag]]: The main game client.
*[[BZFS]] : The game server.
*[[BZAdmin]] : A command line administration tool for server owners.
These three projects build the three applications that make up the software.

A number of other smaller projects are used for common code that is shared between the three main projects.
These are:
*3D : Utilities for drawing the Three Dimensional view in the client
*common : Shared general code
*date : version and build date stamps
*game : shared game logic
*geometry : 3D geometry and [http://en.wikipedia.org/wiki/OpenGL OpenGL] code for the Three Dimensional view in the client
*mediafile : external file loaders for images and sounds
*net : networking code
*obstacle : collision detection
*ogl : common [http://en.wikipedia.org/wiki/OpenGL OpenGL] utilities
*platform : OS specific implementations of low level features ( input, window management, etc.. )
*scene : render culling and scene management

BZFlag also includes it's own copies of a few third party libs. These include:
*c-ares : an asynchronous DNS resolver
*regex : a text parsing library
*zlib : a compression library.

==Releases and Distribution==
The source code is available in a number of ways.

The simplest way is to download one of the source code archives that is released with each major release of the software. These are available at the [http://sourceforge.net/projects/bzflag/files/bzflag%20source/ BZFlag SourceForge Downloads Page]. There is an archive of the source code used to build every version of the game. The source archives are provided in Unix line ending format ( .tar.gz and .tar.bz ) as well as Windows line ending format ( .zip ). The archives contain instructions on how to compile the software directly. Additional software such as a C++ compiler will be needed.

The source code for BZFlag is always changing and being developed. The developers keep the current code for the project in a SVN repository located at SourceForge. Please see the [[BZFlag SVN]] page for information on how to access the SVN system.

==License==
The BZFlag source code is licensed under the [http://en.wikipedia.org/wiki/LGPL GNU Lesser General Public License] or LGPL license. This means that anyone is free to use and redistribute the software and it's source code, as long as they follow the license. In order to release a version of the software, or a modified version of the software, a user must also release the source code to the software, as well as any changes they have made to the LGPL source code. This is so that others may benefit from the modifications as well.

==Patches==
A number of users have submitted changes to the source code as [http://en.wikipedia.org/wiki/Patch_%28computing%29 patches]. These patches are source code modifications that can ether fix a bug or add a feature. The development team will periodically review all patches submitted to the [http://sourceforge.net/tracker/?group_id=3248&atid=303248 SourceForge Patch Tracker] and apply desired patches to the mainline source code.

==History==
The BZFlag source code has been open source and hosted by SourceForge since March 2000. Before this the source code was the proprietary property of [[Chris Schoeneman]] who began developing the game in 1992 at the Cornell Program of Computer Graphics for the SGI line of graphic workstations.

BZFlag is in no way related to the commercial game [http://en.wikipedia.org/wiki/Battlezone "BATTLEZONE"] by [http://en.wikipedia.org/wiki/Atari Atari, Inc], it was simply inspired by it. They do not share any code or intellectual property.

==See also==
[[BZFlag SVN]]

==External Links==
[http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License]

[http://bzflag.svn.sourceforge.net/viewvc/bzflag/ BZFlag Source Code Subversion Repository]

[[Category:Development]]
[[Category:Compiling]]

Zone

2011-11-29T19:04:47Z

Sigonasr2: Fix what seems to be a legacy parameters tag.

A Zone is a rectangular [[BZW]] map structure for spawn or flag zones. The zone lets you create a specific area for a certain flag or a certain team to spawn.

==Code==
The code for a zone is as follows:
zone
name example_zone
position 0.0 0.0 0.0
size 1.0 1.0 1.0
rotation 0.0
# Add two GM, one OO
zoneflag GM 2
zoneflag OO
# cause laser, shockwave
# good and bad flags to spawn in the zone
flag L
flag SW
flag good
flag bad
team 0 1 2 3 4
safety 1 2 3 4
end
Valid parameters for the zone are:
* '''position''' Defines the position of the zone in the word (x/y/z)
* '''size''' Defines the size of the zone (rectangular prism)
* '''rotation''' Defines a rotation around the Z axis for the box, in degrees.
* '''zoneflag''' Generates the flag listed inside this zone (adding "flag n" for the quantity). The flag will be generated specifically for the zone, regardless of BZFS options. One flag per call. Remember to use the -fb option in the option object.
* '''flag''' Listed flag will spawn in the zone. The flags must be be specified for the server via BZFS options. One flag per call.
* '''team''' Team players will spawn (0 - Rogue, 1 - Red, 2 - Green, 3 - Blue, 4 - Purple).
* '''safety''' Team flags listed here will fly to the closest safety zone when dropped (1 - Red, 2 - Green, 3 - Blue, 4 - Purple).

==Function==
Zones are used to define spawn positions in within the XY volume of the Zone. The Z value for the spawn position will be the lower bounds of the volume in Z. Normal spawn rules still apply for spawns generated by zones and may disqualify a spawn from happening in a zone (Z clearance, shots, players, etc..). When multiple zones of the same type are defined, a random one is used for each spawn, if possible.

==Appearance==
Zones have no appearance in a map other than what they define (ex: flags or tank spawns).

==History==
Zones were added to BZFlag in version 2.0.0.

==Editor Support==
The zone object is not supported by any known editors.
==Notes==
Working with flag zones make sure you have enough clearance for flags, default flag height is 10 world units. A dropped flag will stay in a short tunnel if _flagHeight is less than 1.

If the zone is not on the ground, be sure to set -fb or -sb, or your spawns will always be on the ground.
[[Category:Map Making]]
[[Category:Map_Objects]]

Bz moveFlag

2011-11-18T20:37:18Z

Sigonasr2: Removed reset argument from bz_moveFlag()

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API bool bz_moveFlag( int flag, float pos[3] );
==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|flag
|int
|the flag to move
|-
|pos
|float [3]
|the position to move the flag to.
|}

==Description==
This API function moves the specified flag. If the flag is carried, it will be drooped. If reset is true, the flag is also "zapped" to the new location ( ring graphical effect).

==Notes==
Prior to BZFlag Version 3.0 this function did not have the '''reset''' paramater, and always behaved as if it was true.

Functions (API)

2011-11-18T20:36:26Z

Sigonasr2: /* Flag Management */ Removed reset argument from bz_moveFlag()

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
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 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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

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

Functions (API)

2011-11-18T13:55:24Z

Sigonasr2: /* Flag Management */ As of 2.4.0, it seems the name "reverted" to bz_getName() at some point. We'll stick with that for now.

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
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 bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

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

Bz getFlagName

2011-11-18T13:55:05Z

Sigonasr2: Rename function to bz_getName() for now.

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API const [[bz_ApiString]] bz_getName( int flag );
==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|flag
|int
|the flag to return
|}

==Description==
This API function returns the flag code for the specified flag.

Functions (API)

2011-11-18T13:38:50Z

Sigonasr2: /* Server Time */ bz_getMaxWaitTime() and bz_setMaxWaitTime() are not in the API. Seemed to have slipped by when I was looking through them.

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

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

Mesh

2011-10-20T19:31:06Z

Sigonasr2: Added information about inside points from http://my.bzflag.org/bb/viewtopic.php?p=139382#p139382. Note to Admins: File Uploader does not work due to the upload directory not being writable. Image should be uploaded once this issue is fixed.

A mesh is a [[BZW]] map object that defines an arbitrary three dimensional shape. A mesh is defined as a series of faces containing 3 or more points(vertices) in three dimensional space.

==Code==
The code for a mesh object is as follows, this is only an example
{|
|
mesh
name example_mesh
#
# Material properties and physics applied to a mesh apply to all faces
# that follow the setting. Mesh faces will alter their own
# properties without affecting the state of the mesh properties.
#
inside 5.5 4.5 1.2 # add an inside point (repeatable)
outside 0 0 1000 # add an outside point (repeatable)
vertex 100 200 300 # add a vertex (repeatable)
normal 1.0 0 0 # add a normal (repeatable)
texcoord 0.1 0.75 # add a texture coordinate (repeatable)
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
phydrv example_phydrv # assign a physics driver
smoothbounce # ricochets use normals
noclusters # render each mesh face individually
# (this can be useful for occluders)
face # start a face (repeatable)
# faces must be convex polygons
vertices 1 4 0 3 5 # list of vertices (requires at least three)
normals 2 6 0 4 7 # list of normals (optional)
texcoords 0 3 2 4 9 # list of texture coordinates (optional)
phydrv example_phydrv # assign a physics driver
smoothbounce
noclusters
drivethrough
shootthrough
passable
matref
endface # end the face
#
# The drawInfo element can be added to increase the rendering speed
# of the mesh object. If the client is capable of using this data,
# then it is used to draw the mesh instead of the face information.
#
end # mesh
|}

Valid parameters for a mesh are
<properties>
name=The name of the mesh
vertex= this is a 'corner' of your mesh - a point where faces connect. (at least 3 are required)
normal= a unit vector describing the direction light will reflect off the object
texcoord= this is used for mapping textures onto the mesh. This will link a point of the 2-Dimensional texture to a vertex on the 3-Dimensional object. (0,0) refers to the lower left corner of the texture, (1,1) refers to the top right. Textures are defined in the [[material]] object.
inside= an arbitrary vertex placed on the inside of the mesh object. This keeps tanks from driving or spawning inside the object.
phydrv=Assign a physics driver as defined in the [[physics]] object.
smoothbounce=shot will ricochet from the face in the same direction as the defined normal.
noclusters=Render each face individually.
shift=places the mesh using <x y z> coordinates
scale=resizes the mesh along the x, y, or z axis
shear=repeatable
spin=spins the mesh <angle> number of degrees, <n> number of rotations along one or more of the x, y, or z axis
drivethrough=Tanks can drive through this mesh.
shootthrough=Tanks can shoot through this mesh.
passable=Tanks can both shoot and drive through this mesh
matref=Assign a [[material]] to all below faces.
face=Start a face (required), see below:
</properties>
Valid parameters within the face sub-object:
<properties>
vertices=Numbered list of vertices for this face. (requires at least three)
normals=Numbered list of normals for this face.
texcoords=Numbered list of texture coordinates for this face.
phydrv=Assign a [[Physics|physics driver]] to this face only.
smoothbounce=use normals to determine shot ricochets for this face.
noclusters'''
drivethrough=Tanks can drive through this face.
shootthrough=Tanks can shoot through this face.
passable=Tanks can both shoot and drive through this face
matref=Assign a [[material]] to this face.
</properties>
Meshes have full support for [[Material]] (wherein custom textures can be defined) and [[Physics Drivers]].

==DrawInfo==
[[DrawInfo]] can be added to the mesh object to increase rendering efficiency, allowing the designer to specify which details will be seen from certain distances. It can also be used to rotate a mesh object, though tanks can not interact with the moving object.

==Appearance==
The shape of a mesh will vary greatly as by its very nature it can be defined to look like anything. Unless a material is defined and applied, the default "mesh.png" texture will be applied to all faces of the mesh.

==Simplified Examples==
{|
|Simple Cube
mesh
vertex -10 -10 0
vertex 10 -10 0
vertex 10 10 0
vertex -10 10 0
vertex -10 -10 10
vertex 10 -10 10
vertex 10 10 10
vertex -10 10 10
face #south
vertices 0 1 5 4
endface
face #east
vertices 1 2 6 5
endface
face #north
vertices 2 3 7 6
endface
face #west
vertices 3 0 4 7
endface
face #bottom
vertices 0 1 2 3
endface
face #top
vertices 4 5 6 7
endface
end #mesh
|Simple billboard with texcoords
mesh
vertex -10 0 0
vertex 10 0 0
vertex 10 0 10
vertex -10 0 10
texcoord 0 0
texcoord 1 0
texcoord 1 1
texcoord 0 1
matref myBillboard
face
vertices 0 1 2 3
texcoords 0 1 2 3
endface
face #backside
vertices 1 0 3 2
texcoords 1 0 3 2
endface
end #mesh
|Simple Jump-through floor
mesh
vertex 0 0 9
vertex 10 0 9
vertex 10 10 9
vertex 0 10 9
vertex 0 0 10
vertex 10 0 10
vertex 10 10 10
vertex 0 10 10
face #south
vertices 0 1 5 4
drivethrough
endface
face #east
vertices 1 2 6 5
drivethrough
endface
face #north
vertices 2 3 7 6
drivethrough
endface
face #west
vertices 3 0 4 7
drivethrough
endface
face #bottom
vertices 0 1 2 3
drivethrough
endface
face #top
vertices 4 5 6 7
endface
end #mesh
|}

==Inside Points==
An inside point allows the mapper to make a mesh solid. This means that regardless of what the player tries to do, they will not be able to go through the object, or end up spawning inside a mesh unintentionally. When you drive through a box, especially with the Oscillation Overthruster flag, you will be inside of a building and sealed to it. Without inside points, especially to larger meshes, you will just end up on the inside of it and be able to shoot and drive normally. This is sometimes intentional, but usually not wanted. Inside points remedy this.

In order to have successful inside point coverage, you need to make sure all faces of your mesh are in "line of sight" to the point you specify. This means that all faces have direct vision to that point, just as if that point was a point of light and all the faces were eyes. Only what can be seen through a straight line will be considered the inside for that face.

Illustration is better than words, here is an image drawn up by '''Spazzy McGee''' from the forums.

http://img205.imageshack.us/img205/2140/insides.jpg

(Original forum post http://my.bzflag.org/bb/viewtopic.php?p=139382#p139382)

==Editor Support==
The mesh object is supported by the [[BZWTools]] blender plugin, the Wings3D Exporter and hand coding.

==History==
The Mesh object was added with the [[BZFlag 2.0.0|v2.0.0]] release of BZFlag.

[[Category:Map Making]]
[[Category:Map_Objects]]

Functions (API)

2011-10-19T10:48:46Z

Sigonasr2: ToDo: "Verify Future API Functions"

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

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

Bz getPublicPort

2011-10-19T10:45:30Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getPublicPort
| returns = A number containing the port the server is communicating through.
| returntype = int
| description = Retrieves the port the server communicates with. Normally this is specified with the '''-p''' BZFS option, but defaults to 5154.
}}

===Example===
A simple greeting that tells the player what server and port they are on. This may be useful to remove the hassle of modifying greetings for a server that hosts many ports.
case bz_ePlayerJoinEvent: {
if (bz_getPublic()) {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"Welcome!");
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"You are playing on %s",bz_getPublicDescription().c_str());
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
" @ %s:%d",bz_getPublicAddr().c_str(),bz_getPublicPort());
}
}break;

Bz getPublicDescription

2011-10-19T10:44:23Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getPublicDescription
| returns = A string containing the public title / description of the server.
| returntype = [[bz_ApiString]]
| description = Retrieves the string with the title of the server, generally displayed on the list server when players are finding a game to join. This is what you would specify with the '''-publictitle''' BZFS option.
}}

===Example===
A simple greeting that tells the player what server and port they are on. This may be useful to remove the hassle of modifying greetings for a server that hosts many ports.
case bz_ePlayerJoinEvent: {
if (bz_getPublic()) {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"Welcome!");
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"You are playing on %s",bz_getPublicDescription().c_str());
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
" @ %s:%d",bz_getPublicAddr().c_str(),bz_getPublicPort());
}
}break;

Bz getPublicAddr

2011-10-19T10:43:30Z

Sigonasr2: Meh, forgot to update the description.

{{apicall
| name = bz_getPublicAddr
| returns = A string containing the public address of the server.
| returntype = [[bz_ApiString]]
| description = Returns the string that was specified with the BZFS option '''-publicaddr''' or the default address that is used when starting up a public server.
}}

===Example===
A simple greeting that tells the player what server and port they are on. This may be useful to remove the hassle of modifying greetings for a server that hosts many ports.
case bz_ePlayerJoinEvent: {
if (bz_getPublic()) {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"Welcome!");
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"You are playing on %s",bz_getPublicDescription().c_str());
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
" @ %s:%d",bz_getPublicAddr().c_str(),bz_getPublicPort());
}
}break;

Bz getPublicAddr

2011-10-19T10:41:59Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getPublicAddr
| returns = A string containing the public address of the server.
| returntype = [[bz_ApiString]]
| description = Pauses the countdown that is currently running.
}}

===Example===
A simple greeting that tells the player what server and port they are on. This may be useful to remove the hassle of modifying greetings for a server that hosts many ports.
case bz_ePlayerJoinEvent: {
if (bz_getPublic()) {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"Welcome!");
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"You are playing on %s",bz_getPublicDescription().c_str());
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
" @ %s:%d",bz_getPublicAddr().c_str(),bz_getPublicPort());
}
}break;

Bz getPublic

2011-10-19T10:34:50Z

Sigonasr2: Create API Function Page.

{{apicall
| name = bz_getPublic
| returns = Whether or not the server is public.
| returntype = bool
| description = Retrieves whether the server is successfully connecting and authenticating with the list server.
}}

Bz unloadPlugin

2011-10-19T10:32:48Z

Sigonasr2: Don't know for sure.

{{apicall
| name = bz_unloadPlugin
| returns = Whether or not the plugin unloaded successfully.
| returntype = bool
| description = Unloads a plugin that is currently loaded.
| param1 = path
| param1type = const char*
| param1desc = The exact path of the plugin file.
}}

===Example===
Load the '''FlagOnSpawn''' plugin which then gets unloaded the moment a player joins.
case bz_eWorldFinalized: {
bz_loadPlugin("/home/name/path/to/flagOnSpawn.so","WG:-1");
}break;
case bz_ePlayerJoinEvent: {
bz_unloadPlugin("/home/name/path/to/flagOnSpawn.so");
}break;

Bz loadPlugin

2011-10-19T10:32:34Z

Sigonasr2: Don't know for sure.

{{apicall
| name = bz_loadPlugin
| returns = Whether or not the plugin was loaded successfully.
| returntype = bool
| description = Attempts to load a plugin with the given path and filename along with any passed parameters.
| param1 = path
| param1type = const char*
| param1desc = The exact path to the file.
| param2 = params
| param2type = const char*
| param2desc = The command separated list of file parameters to pass on to the plugin.
}}

===Example===
Attempt to load the '''FlagOnSpawn''' plugin with the parameters to give any team a WG flag on spawn when the game starts.
case bz_eWorldFinalized: {
bz_loadPlugin("/home/name/path/to/flagOnSpawn.so","WG:-1");
}break;

Bz unloadPlugin

2011-10-19T10:25:39Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_unloadPlugin
| returns = Whether or not the plugin unloaded successfully.
| returntype = bool
| description = Unloads a plugin that is currently loaded.
| param1 = path
| param1type = const char*
| param1desc = The exact path of the plugin file. In addition, it may be locally referenced starting from the path returned by bz_pluginBinPath().
}}

===Example===
Load the '''FlagOnSpawn''' plugin which then gets unloaded the moment a player joins.
case bz_eWorldFinalized: {
bz_loadPlugin("/home/name/path/to/flagOnSpawn.so","WG:-1");
}break;
case bz_ePlayerJoinEvent: {
bz_unloadPlugin("/home/name/path/to/flagOnSpawn.so");
}break;

Bz loadPlugin

2011-10-19T10:23:38Z

Sigonasr2: Meant to use eWorldFinalized event. The eGameStartEvent isn't ready for loading plugins just yet.

{{apicall
| name = bz_loadPlugin
| returns = Whether or not the plugin was loaded successfully.
| returntype = bool
| description = Attempts to load a plugin with the given path and filename along with any passed parameters.
| param1 = path
| param1type = const char*
| param1desc = The exact path to the file. In addition, it may be locally referenced starting from the path returned by [[bz_pluginBinPath]]().
| param2 = params
| param2type = const char*
| param2desc = The command separated list of file parameters to pass on to the plugin.
}}

===Example===
Attempt to load the '''FlagOnSpawn''' plugin with the parameters to give any team a WG flag on spawn when the game starts.
case bz_eWorldFinalized: {
bz_loadPlugin("/home/name/path/to/flagOnSpawn.so","WG:-1");
}break;

Bz loadPlugin

2011-10-19T10:18:51Z

Sigonasr2: Update to modern template. Include Example.

{{apicall
| name = bz_loadPlugin
| returns = Whether or not the plugin was loaded successfully.
| returntype = bool
| description = Attempts to load a plugin with the given path and filename along with any passed parameters.
| param1 = path
| param1type = const char*
| param1desc = The exact path to the file. In addition, it may be locally referenced starting from the path returned by [[bz_pluginBinPath]]().
| param2 = params
| param2type = const char*
| param2desc = The command separated list of file parameters to pass on to the plugin.
}}

===Example===
Attempt to load the '''FlagOnSpawn''' plugin with the parameters to give any team a WG flag on spawn when the game starts.
case bz_eGameStartEvent: {
bz_loadPlugin("/home/name/path/to/flagOnSpawn.so","WG:-1");
}break;

Bz getLoadedPlugins

2011-10-19T10:03:40Z

Sigonasr2: Updated to the modern template. Added example.

{{apicall
| name = bz_getLoadedPlugins
| returns = The number of plugins that are currently loaded.
| returntype = int
| description = Retrieves the names of all loaded plugins and counts how many of them there are.
| param1 = list
| param1type = [[bz_APIStringList]]*
| param1desc = The pointer to a [[bz_APIStringList]] list for storing/appending the plugin names to.
}}

===Example===
Displays the list of plugins when a player joins the server, mimicking the output you would expect from the command '''/listplugins'''.
case bz_ePlayerJoinEvent: {
bz_APIStringList list;
int count=bz_getLoadedPlugins(&list);
for (int i=0;i<count;i++) {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"%d %s",i+1,list.get(i).c_str());
}
}break;

Functions (API)

2011-10-19T09:54:44Z

Sigonasr2: /* Plug-in Management */ Link to bz_APIStringList for the argument.

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x
}}

{{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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

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

Bz getPlayerRank

2011-10-19T09:51:00Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_getPlayerRank
| description = Returns the rank of the player given.
| param1 = playerId
| param1type = int
| param1desc = Player to lookup.
| returntype = float
| returns = Rank of the player.
}}

Bz getPlayerTKs

2011-10-19T09:50:41Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_getPlayerTKs
| description = Returns the amount of TKs for the player given.
| param1 = playerId
| param1type = int
| param1desc = Player to lookup.
| returntype = int
| returns = Amount of TKs the player has.
}}

Bz getPlayerLosses

2011-10-19T09:50:23Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_getPlayerLosses
| description = Returns the amount of losses for the player given.
| param1 = playerId
| param1type = int
| param1desc = Player to lookup.
| returntype = int
| returns = Amount of losses of the player.
}}

Bz getPlayerWins

2011-10-19T09:50:05Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_getPlayerWins
| description = Returns the amount of wins for the player given.
| param1 = playerId
| param1type = int
| param1desc = Player to lookup.
| returntype = int
| returns = Amount of wins of the player.
}}

Bz resetPlayerScore

2011-10-19T09:49:48Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_resetPlayerScore
| description = Resets the score of a player.
| param1 = playerID
| param1type = int
| param1desc = The player who is affected by the reset.
| returntype = bool
| return = Whether the player exists.
}}

Bz setPlayerWins

2011-10-19T09:49:15Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_setPlayerWins
| description = Sets the wins of a player.
| param1 = playerID
| param1type = int
| param1desc = The player who is affected by the win change.
| param2 = wins
| param2type = int
| param2desc = The wins to set for the player.
| returntype = bool
| return = Whether the player exists.
}}

Bz setPlayerTKs

2011-10-19T09:48:54Z

Sigonasr2: Removed version 2.99.x requirement.

{{apicall
| name = bz_setPlayerTKs
| description = Sets the tks of a player.
| param1 = playerID
| param1type = int
| param1desc = The player who is affected by the tk change.
| param2 = tks
| param2type = int
| param2desc = The tks to set for the player.
| returntype = bool
| return = Whether the player exists.
}}

Bz startCountdown

2011-10-19T09:43:37Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_startCountdown
| returns =
| returntype = void
| description = Begins the starting countdown process as if a player were to type '''/countdown'''.
| param1 = delay
| param1type = int
| param1desc = How many seconds to countdown before the real countdown timer for the match starts.
| param2 = limit
| param2type = float
| param2desc = How many seconds to set the countdown timer to? (Basically, setting the match length.)
| param3 = byWho
| param3type = const char*
| param3desc = The name of the player starting the countdown. Note that the name displayed does not have to be a player in the server, it can be any string.
}}

===Example===
Once 4 players have joined, the countdown will automatically begin by SERVER using the default time limit set by the server with a 10 second starting delay.
case bz_ePlayerJoinEvent: {
if (bz_getTeamCount(eBlueTeam)+
bz_getTeamCount(eRedTeam)+
bz_getTeamCount(eRogueTeam)+
bz_getTeamCount(eGreenTeam)+
bz_getTeamCount(ePurpleTeam)>=4 &&
(!bz_isCountDownActive() || !bz_isCountDownInProgress)) {
bz_sendTextMessage(BZ_SERVER,BZ_ALLUSERS,"Enough players have joined, starting countdown.");
bz_startCountdown(10,bz_getTimeLimit(),"SERVER");
}
}break;

Bz resumeCountdown

2011-10-19T09:36:32Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_resumeCountdown
| returns =
| returntype = void
| description = Resumes the countdown that is currently paused.
| param1 = resumedBy
| param1type = const char*
| param1desc = The name of the player resuming the countdown. Note that this value does not have to be a callsign of a player in the server, it can be any string.
}}

===Example===
Resume the countdown if a player unpauses, saying the player that unpaused decided to unpause the countdown also.
case bz_ePlayerPausedEvent:{
if (!bz_isCountDownActive() && !((bz_PlayerPausedEventData_V1*)eventData)->pause) {
bz_resumeCountdown(bz_getPlayerCallsign(((bz_PlayerPausedEventData_V1*)eventData)->playerID));
}
}break;

Bz pauseCountdown

2011-10-19T09:34:52Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_pauseCountdown
| returns =
| returntype = void
| description = Pauses the countdown that is currently running.
| param1 = pausedBy
| param1type = const char*
| param1desc = The name of the player stopping the countdown. Note that this value does not have to be a callsign of a player in the server, it can be any string.
}}

===Example===
Pause the countdown if a player pauses, saying the player that paused decided to pause the countdown also.
case bz_ePlayerPausedEvent:{
if (bz_isCountDownActive() && ((bz_PlayerPausedEventData_V1*)eventData)->pause) {
bz_pauseCountdown(bz_getPlayerCallsign(((bz_PlayerPausedEventData_V1*)eventData)->playerID));
}
}break;

Bz ePlayerPausedEvent

2011-10-19T09:31:17Z

Sigonasr2: /* Data */ Clarify which value is returned for which pause state.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_ePlayerPausedEvent''' is an API event that is called each time a playing tank is paused.

==Data==
'''bz_ePlayerPausedEvent''' returns the '''bz_PlayerPausedEventData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_ePlayerPausedEvent
|-
|playerID
|int
|ID of the player who paused.
|-
|pause
|bool
|Whether the player is pausing(true) or unpausing(false)
|-
|time
|double
|Time local server time for the event.
|}

Bz isCountDownInProgress

2011-10-19T09:27:59Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_isCountDownInProgress
| returns = Whether or not the match is going to start.
| returntype = bool
| description = Retrieves whether or not the countdown to the start of the match is occurring.
}}

===Example===
Kick a player if they join when a match is about to start and they are not an observer.
case bz_eAllowPlayer: {
if (bz_isCountDownInProgress() && bz_getPlayerTeam(((bz_AllowPlayerEventData_V1*)eventData)->playerID)!=eObservers) {
((bz_AllowPlayerEventData_V1*)eventData)->allow=false;
((bz_AllowPlayerEventData_V1*)eventData)->reason="Sorry! A match is about to start.";
}
}break;

Bz isCountDownActive

2011-10-19T09:21:58Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_isCountDownActive
| returns = Whether or not the countdown timer is ticking down.
| returntype = bool
| description = Retrieves whether or not the countdown is active. The countdown timer is active if the timer is continuing to go down every second.
}}

===Example===
Tell players that join that a match is in progress if they join while the countdown is active.
case bz_ePlayerJoinEvent: {
if (bz_isCountDownActive()) {
bz_sendTextMessage(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"Welcome! There is currently a timed match in progress.");}
}break;

Bz isTimeManualStart

2011-10-19T09:18:58Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_isTimeManualStart
| returns = True if the time limit requires manual startup or false if it is automatically running from the start.
| returntype = bool
| description = Retrieves whether or not the time limit has to be started via a player issuing the '''/countdown''' command. The '''-timemanual''' BZFS option would make this return value true.
}}

===Example===
If a player joins and the timer requires manual starting, tell the user that.
case bz_ePlayerJoinEvent: {
if (bz_isTimeManualStart()) {
bz_sendTextMessage(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"Welcome! You can start the timer with /countdown at any time.");}
}break;

Bz getTimeLimit

2011-10-19T09:15:15Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getTimeLimit
| returns = The value of the last time limit.
| returntype = float
| description = Retrieves the value of the time limit that was last set.
}}

===Example===
Display time limit to user upon joining. Note that the '''-time''' BZFS option or [[bz_setTimeLimit]]() must be called for this to return a value other than 0.
case bz_ePlayerJoinEvent: {
bz_sendTextMessagef(BZ_SERVER,((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,
"Welcome! The current countdown timer is set to %lf seconds!",bz_getTimeLimit());
}break;

Bz setTimeLimit

2011-10-19T09:09:13Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_setTimeLimit
| returns = Whether or not the time limit was able to be set.
| returntype = bool
| description = Sets the countdown timer to a new value. '''Note:''' Any players that retrieved the countdown value before this function is called will not see the changes until they rejoin or a new countdown is triggered via [[bz_startCountdown]]().
| param1 = timeLimit
| param1type = float
| param1desc = The amount of time in seconds to set the countdown timer to.
}}

===Example===
Set the countdown timer to 54 seconds remaining.
bz_setTimeLimit(54);

Bz getReports

2011-10-19T09:06:36Z

Sigonasr2: doe -> does

{{apicall
| name = bz_getReports
| returns = A [[bz_APIStringList]] data type containing all the reports available on the server.
| returntype = bz_APIStringList*
| description = Retrieves reports made by other players in the same format as the '''/viewreports''' command does
}}

===Example===
Shows all reports to any administrators that join the game as if they typed /viewreports.
case bz_ePlayerJoinEvent: {
if (bz_getAdmin(((bz_PlayerJoinPartEventData_V1*)eventData)->playerID)) {
for (int i=0;i<bz_getReports()->size();i++) {
bz_sendTextMessagef(BZ_SERVER,
((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"%s",bz_getReports()->get(i).c_str());
}
}
}break;

Bz getReports

2011-10-19T08:49:26Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getReports
| returns = A [[bz_APIStringList]] data type containing all the reports available on the server.
| returntype = bz_APIStringList*
| description = Retrieves reports made by other players in the same format as the '''/viewreports''' command doe
}}

===Example===
Shows all reports to any administrators that join the game as if they typed /viewreports.
case bz_ePlayerJoinEvent: {
if (bz_getAdmin(((bz_PlayerJoinPartEventData_V1*)eventData)->playerID)) {
for (int i=0;i<bz_getReports()->size();i++) {
bz_sendTextMessagef(BZ_SERVER,
((bz_PlayerJoinPartEventData_V1*)eventData)->playerID,"%s",bz_getReports()->get(i).c_str());
}
}
}break;

Bz HostUnbanUser

2011-10-19T08:37:10Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_HostUnbanUser
| returns = Whether or not the removal of the ban was executed successfully.
| returntype = bool
| description = Unbans a host name that has been previously banned.
| param1 = hostmask
| param1type = const char*
| param1desc = The exact host name address to remove. An example would be *.myhost.biz
}}

===Example===
bz_HostUnbanUser("*.myhost.biz");

Bz IDUnbanUser

2011-10-19T08:36:03Z

Sigonasr2: Created new API Function page with example.

{{apicall
| name = bz_IDUnbanUser
| returns = Whether or not the removal of the ban was executed successfully.
| returntype = bool
| description = Unbans a bzID address currently listed in the ban list. '''Note:''' The bzID is automatically assigned via the registration process at the [http://my.bzflag.org/bb BZBB]. In the version 2.4.0 API, there is no corresponding [[bz_IDBanUser]]() function which means previous bans had to be made by administrators manually.
| param1 = bzID
| param1type = const char*
| param1desc = The exact bzID to remove from the ban list. Note that this is not an integer, but a string.
}}

===Example===
bz_IDUnbanUser("1372");

Bz IPUnbanUser

2011-10-19T08:32:03Z

Sigonasr2: Created Documentation for this API Event.

{{apicall
| name = bz_IPUnbanUser
| returns = Whether or not the removal of the ban was executed successfully.
| returntype = bool
| description = Unbans an IP address that is currently listed in the ban list.
| param1 = ip
| param1type = const char*
| param1desc = The exact IP address to remove from the banlist.
}}

===Example===
bz_IPUnbanUser("127.0.0.1");

Bz HostBanUser

2011-10-19T08:30:05Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_HostBanUser
| returns = Whether or not the ban was executed successfully.
| returntype = bool
| description = Sets up a new Host ban Rule in the ban list.
| param1 = bannedByIndex
| param1type = int
| param1desc = The player ID that is banning the IP Address. '''NOTE:''' This has to be a player that is currently on the server, so at least one player must be present for a ban to be created.
| param2 = hostmask
| param2type = const char*
| param2desc = The Hosting address of the player to be banned. Host bans use wildcard (*) character also, such as *.myhost.biz
| param3 = duration
| param3type = int
| param3desc = The amount of time in minutes to ban the host.
| param4 = reason
| param4type = const char*
| param4desc = The reason that is displayed to the banned user upon failure to join.
}}

===Example===
bz_HostBanUser(0,"*.myhost.biz",3600,"This host abused the server.")

Functions (API)

2011-10-19T08:04:17Z

Sigonasr2: /* Server Administration */ Updated, bz_IDBanUser() is not a 2.3+ function.

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x
}}

{{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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

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

Bz IPBanUser

2011-10-19T07:50:45Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_IPBanUser
| returns = Whether or not the ban was executed successfully.
| returntype = bool
| description = Sets up a new IP Rule in the ban list. '''Note''' that if the player is currently playing when their IP address is banned it will not take effect immediately until they rejoin. This can be counteracted by kicking the player upon the ban, or using [[bz_IDBanUser]]() instead.
| param1 = bannedByIndex
| param1type = int
| param1desc = The player ID that is banning the IP Address. '''NOTE:''' This has to be a player that is currently on the server, so at least one player must be present for a ban to be created.
| param2 = ip
| param2type = const char*
| param2desc = The IP Address string to ban. Note that this can contain wildcard (*) characters for higher level bans.
| param3 = duration
| param3type = int
| param3desc = The amount of time in minutes to ban the player.
| param4 = reason
| param4type = const char*
| param4desc = The reason that is displayed to the banned user upon failure to join.
}}

===Example===
This code will check if the TK ratio is greater than 0.3 (30%) after at least 5 rounds of play. If so, the player will be IP Banned and kicked. This is basically an auto TK ban method.
case bz_ePlayerDieEvent: {
if ((double)bz_getPlayerTKs(((bz_PlayerDieEventData_V1*)eventData)->killerID)
/(double)(bz_getPlayerWins(((bz_PlayerDieEventData_V1*)eventData)->killerID)
+bz_getPlayerLosses(((bz_PlayerDieEventData_V1*)eventData)->killerID))
>0.3
&&
bz_getPlayerWins(((bz_PlayerDieEventData_V1*)eventData)->killerID)
+bz_getPlayerLosses(((bz_PlayerDieEventData_V1*)eventData)->killerID)
+bz_getPlayerTKs(((bz_PlayerDieEventData_V1*)eventData)->killerID)>=5) {
//Ban the teamkiller and kick them
bz_IPBanUser(((bz_PlayerDieEventData_V1*)eventData)->killerID,
bz_getPlayerIPAddress(((bz_PlayerDieEventData_V1*)eventData)->killerID),
60,"Auto Ban for Intentional Teamkilling.");
bz_kickUser(((bz_PlayerDieEventData_V1*)eventData)->killerID,
"Auto Ban for Intentional Teamkilling.",true);
};
}break;

More information on this function can be found on the [[BZFS_API_2.4_Upgrade]] page.

Register

2011-10-19T07:30:54Z

Sigonasr2: Removed () from function name.

{{apicall
| name = Register
| returns = Whether or not the register was successful.
| returntype = bool
| description = Registers a new event handler. This event handler will receive events of the event type specified.
| param1 = eventType
| param1type = bz_eEventType
| param1desc = The type of event to listen for
}}

===Example===
void SAMPLE_PLUGIN::Init ( const char* /*commandLine*/ )
{
Register(bz_ePlayerUpdateEvent);
}

More information on this function can be found on the [[BZFS_API_2.4_Upgrade]] page.

Functions (API)

2011-10-19T07:29:05Z

Sigonasr2: /* Server Administration */ Spelling correction, durration -> duration

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x
}}

{{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_getPlayerByCallsign]] ( const char* name );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
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);

==== 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 );

=== 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_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 [[bzApiString]] [[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 );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3], bool reset = true );
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 );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

=== 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_IDBanUser]] ( int bannedByIndex, const char* bzID , 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 );

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

Bz getDebugLevel

2011-10-19T07:25:03Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_getDebugLevel
| returns = An integer containing the BZFS debugging level.
| returntype = int
| description = Gets the debugging level of the server.
}}
===Example===
Creates a basic BZFS output from debug mode for administrators to watch. Uses bz_getDebugLevel() to determine which messages actually show up.
case bz_eLoggingEvent: {
if (((bz_LoggingEventData_V1*)eventData)->level==bz_getDebugLevel()) {
bz_sendTextMessagef(BZ_SERVER,BZ_ALLUSERS,
"[BZFS] %s",((bz_LoggingEventData_V1*)eventData)->message.c_str());
}
}break;

Bz setBZDBInt

2011-10-19T06:36:53Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_setBZDBInt
| returns = Whether or not the set was successful.
| returntype = bool
| description = Sets a BZDB variable to a given '''int''' value.
| param1 = variable
| param1type = const char*
| param1desc = Variable name (E.g. "_shockOutRadius")
| param2 = val
| param2type = int
| param2desc = The value to set the variable to.
| param3 = perms = 0
| param3type = int
| param3desc = What to set the permission value to. (Range: 1-3. Using 0 sets it to the default [2], and using a higher number sets it to 3.)
| param4 = persistent = false
| param4type = bool
| param4desc = Whether or not the variable will be persistent.
}}
===Example===
Sets the shockwave radius to a random value between 50 and 100.
bz_setBZDBDouble("_shockOutRadius",rand()%50+50);

Bz setBZDBBool

2011-10-19T06:34:22Z

Sigonasr2: Create API Function Page. Include Example.

{{apicall
| name = bz_setBZDBBool
| returns = Whether or not the set was successful.
| returntype = bool
| description = Sets a BZDB variable to a given '''bool''' value.
| param1 = variable
| param1type = const char*
| param1desc = Variable name (E.g. "_shockOutRadius")
| param2 = val
| param2type = bool
| param2desc = The value to set the variable to.
| param3 = perms = 0
| param3type = int
| param3desc = What to set the permission value to. (Range: 1-3. Using 0 sets it to the default [2], and using a higher number sets it to 3.)
| param4 = persistent = false
| param4type = bool
| param4desc = Whether or not the variable will be persistent.
}}
===Example===
Turns no climbing on sloped objects off to allow climbing and jumping off from them.
bz_setBZDBBool("_noClimb",false);