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

Difference between revisions of "BZFS API"

From BZFlagWiki
Jump to: navigation, search
m (Update links to API events/functions documentation)
 
(40 intermediate revisions by 12 users not shown)
Line 1: Line 1:
−
The BZFS API is used to create [[Plug-ins]] for [[BZFS]].
+
{{DoDoc|
 +
Update to 2.4.x spec<br>
 +
}}
  
−
Here is a general overview, miserably copied with permission of JeffM2501.
+
The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by [[BZFS]] to be used by [[Plug-ins]]. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.
  
−
=== Team Info Functions ===
+
==Overview==
−
BZF_API unsigned int bz_getTeamPlayerLimit ( bz_eTeamType team )
+
The BZFS API is defined entirely in the '''bzfsAPI.h''' header file that is part of the [[BZFlag Source]] code. The header is also included with each install of the BZFlag installer for Microsoft Windows.
  
−
Returns the player limit for the specified team. If an invalid team is used, 0 will be returned.
+
Plug-ins include this file in their source code so that they may access the functions it contains.
  
−
This function is in both 2.0.x CVS and 2.1 as of now.
+
==Naming Conventions==
−
=== Server Reset / Map Management ===
+
All BZFS API code structures will begin with the prefix '''bz''' or '''bz_''' for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.
−
BZF_API bool bz_restart ( void );
+
  
−
This function will do the following things.
+
All wiki documentation references the newer BZFS 3.0 API.
−
1) kick all players
+
−
2) stop any countdowns
+
−
3) stop any recordings
+
−
4) unload the world
+
−
5) reload the world ( calling the bz_eGetWorldEvent that allows for a map file override )
+
−
6) resets all flags.
+
−
7) accept new connections.
+
  
−
This will basically let you do a map reload, with out a full shutdown of the server. none of the plug ins are unloaded, the server is not desisted, none of that ). There may be some additional things we need to reset, we will add them as we find them ( like reload the command line options, or let the plug-in set them ).
+
==API Versions==
 +
The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.
  
−
BZF_API void bz_setClientWorldDowloadURL( const char* URL );
+
In version 3.0 of BZFlag, the entire API will be versioned and set up to use derived classes so that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures will be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out minor source code changes. Once an older plug-in has been updated to the new API it will not work in 2.0.x but will work in all versions after 3.0.
  
−
This function sets the current URL used to download a cached world file. It will be sent to clients that connect giving them the option of using that file. This is helpful if you have changed the map file during a reload.
+
==Entry Points==
 +
There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement.
  
−
BZF_API const bzApiString bz_getClientWorldDowloadURL( void );
+
BZF_PLUGIN_CALL int [[bz_Load]] ( const char* command );
 +
BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
 +
BZF_PLUGIN_CALL int [[bz_GetVersion]] ( void );
  
−
Returns the current world URL.
+
All entry point functions must be preceded with the BZF_PLUGIN_CALL macro. This macro tells the compiler to export these functions so bzfs can find them when the plug-in is loaded.
  
−
BZF_API bool bz_saveWorldCacheFile( const char* file );
+
[[bz_Load]] is called when the plug-in is first initialized. This is when the plug-in should register any [[Event(API)|event handlers]] needed and initialize any "one time" startup data.
  
−
Forces the server to save out a world cache file into the specified file. Returns false on failure.
+
[[bz_Unload]] is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.
  
−
These commands are in CVS for both 2.0.x and 2.1 as of now.
+
[[bz_GetVersion]] is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.
  
−
I'm sure the Restart function will need some work but any help testing it will be greatly appreciated.
+
'''bzfsAPI.h''' defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro;
  
−
=== Flag Drop Messages ===
+
BZ_GET_PLUGIN_VERSION
  
−
bz_eFlagDroppedEvent
+
somewhere in its sources, and then export the function. This will automatically return the API version that the plug-in was compiled with.
  
 +
See the sample plug-ins for examples of each function. These will be the only 3 functions called by bzfs that are not tied to events or other actions installed by the plug-in after load.
  
−
it is called whenever the server gets a dropped flag.
+
==Types==
−
The event will contain a bz_FlagDroppedEvenData_V1 object.
+
−
it has the playerID, the flagID, the flag droped, and the position the flag was dropped at.
+
−
=== Shot Type Control ===
+
  
−
+
Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.
  
 +
===bz_APIString===
 +
Any text passed back from the API or events will come in the form of a [[bz_APIString]]. This is a class defined in the API that behaves much like a std::string. The 'c_str()' method can be used to get the text out as a normal 'const char*'. The class also supports many assignment functions for setting it's contents.
  
−
+
A plug-in should never need to make variables of its' own using the [[bz_APIString]] type, but should use a standard stl std::string instead, [[bz_APIString]] provides an appropriate assignment operator.
−
2.1 now has messages and functions that let you modify the shot type of a tank. The shot type is now independent of the flag you carry. When the shot type is changed, the client will pick up on that change and it will start shoting shots of that type. Once changed, you do NOT have to change the shot type of every shot fired. And yes, the shoting client WILL see the modified shot type, so the entire state will be in sync.
+
  
−
Code:
+
[[bz_APIString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.
−
BZF_API bool bz_setPlayerShotType( int playerId, bz_eShotType shotType );
+
  
−
This will set the current shot type for the player. Any shots fired after the shot type is sent will be of this new type.
+
{{main|bz_APIString}}
  
−
you can also set the shotType field in the bz_eGrabFlagEvent event, and the shot type will be sent with the flag pickup ( this is the best way to do it ).
+
===bz_APILists===
  
−
Any time a player spawns or drops a flag, there shot type will be reset to the standard shot type, and should be reset, if you want to change the default shots.
+
A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function.
 +
The lists types are;
 +
  {| border="1" cellpadding="3" cellspacing="0"
 +
  !List
 +
  !allocator function
 +
  !delete function
 +
  !contained type
 +
  |-
 +
  |[[bz_APIIntList]]
 +
  |[[bz_newIntList]]
 +
  |[[bz_deleteIntList]]
 +
  |int
 +
  |-
 +
  |[[bz_APIFloatList]]
 +
  |[[bz_newFloatList]]
 +
  |[[bz_deleteFloatList]]
 +
  |float
 +
  |-
 +
  |[[bz_APIStringList]]
 +
  |[[bz_newStringList]]
 +
  |[[bz_deleteStringList]]
 +
  |[[bz_APIString]]
 +
|}
 +
 
 +
===Enumerations===
 +
A number of enumerations exist in the API and are used by a number of API functions and events.
 +
  [[bz_eTeamType]]
 +
  [[Event(API)|bz_eEventType]]
 +
  [[bz_eShotType]]
 +
  [[bz_eGameType]]
 +
  [[bz_ePlayerStatus]]
 +
  [[bz_eWorldObjectType]]
 +
  [[bz_eAPIColType]]
 +
  [[bz_ePlayerType]]
 +
  [[bz_eRejectCodes]]
 +
  [[bz_ePlayerDeathReason]]
 +
 
 +
==Events==
 +
Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.
 +
 
 +
{{main|Events (API)}}
 +
 
 +
==Functions==
 +
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.
 +
 
 +
{{main|Functions (API)}}
 +
 
 +
==Wiki Documentation==
 +
The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a ''History'' section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)
 +
 
 +
API developers should use the bzfsAPI.h file as for exact spellings of methods and parameters in the version they wish to use.
 +
 
 +
==See Also==
 +
 
 +
* [[Events (API)|API Events]]
 +
* [[Functions (API)|API Functions]]
 +
* [[Plug-ins]]
 +
* [[BZFS]]
  
 
[[Category:Development]]
 
[[Category:Development]]
 
[[Category:Plug-Ins]]
 
[[Category:Plug-Ins]]

Latest revision as of 10:19, 22 August 2015

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

Update to 2.4.x spec


The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by BZFS to be used by Plug-ins. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.

Overview[edit]

The BZFS API is defined entirely in the bzfsAPI.h header file that is part of the BZFlag Source code. The header is also included with each install of the BZFlag installer for Microsoft Windows.

Plug-ins include this file in their source code so that they may access the functions it contains.

Naming Conventions[edit]

All BZFS API code structures will begin with the prefix bz or bz_ for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.

All wiki documentation references the newer BZFS 3.0 API.

API Versions[edit]

The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.

In version 3.0 of BZFlag, the entire API will be versioned and set up to use derived classes so that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures will be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out minor source code changes. Once an older plug-in has been updated to the new API it will not work in 2.0.x but will work in all versions after 3.0.

Entry Points[edit]

There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement. 

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

All entry point functions must be preceded with the BZF_PLUGIN_CALL macro. This macro tells the compiler to export these functions so bzfs can find them when the plug-in is loaded.

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

bz_Unload is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.

bz_GetVersion is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.

bzfsAPI.h defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro; 

BZ_GET_PLUGIN_VERSION

somewhere in its sources, and then export the function. This will automatically return the API version that the plug-in was compiled with.

See the sample plug-ins for examples of each function. These will be the only 3 functions called by bzfs that are not tied to events or other actions installed by the plug-in after load.

Types[edit]

Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.

bz_APIString[edit]

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

A plug-in should never need to make variables of its' own using the bz_APIString type, but should use a standard stl std::string instead, bz_APIString provides an appropriate assignment operator.

bz_APIString also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.

→ Main article: bz_APIString

bz_APILists[edit]

A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function. The lists types are;

List allocator function delete function contained type
bz_APIIntList bz_newIntList bz_deleteIntList int
bz_APIFloatList bz_newFloatList bz_deleteFloatList float
bz_APIStringList bz_newStringList bz_deleteStringList bz_APIString

Enumerations[edit]

A number of enumerations exist in the API and are used by a number of API functions and events. 

 bz_eTeamType
 bz_eEventType
 bz_eShotType
 bz_eGameType
 bz_ePlayerStatus
 bz_eWorldObjectType
 bz_eAPIColType
 bz_ePlayerType
 bz_eRejectCodes
 bz_ePlayerDeathReason

Events[edit]

Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.

→ Main article: Events (API)

Functions[edit]

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.

→ Main article: Functions (API)

Wiki Documentation[edit]

The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a History section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)

API developers should use the bzfsAPI.h file as for exact spellings of methods and parameters in the version they wish to use.

See Also[edit]

Retrieved from "https://wiki.bzflag.org/index.php?title=BZFS_API&oldid=8930"