Editing BZFS API

Jump to: navigation, search

Warning: The database has been locked for maintenance, so you will not be able to save your edits right now. You may wish to copy and paste your text into a text file and save it for later.

The administrator who locked it offered this explanation: Server migration

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 1: Line 1:
{{DoDoc|
+
{{DoDoc|fill in articles for all API functions}}
Update to 2.4.x spec<br>
+
}}
+
  
 
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.
 
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.
Line 12: Line 10:
 
==Naming Conventions==
 
==Naming Conventions==
 
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 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==
 
==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.
 
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.
+
As of version 2.1 of BZFlag, the entire API was 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 would 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 a source code change. Once older plug-ins are updated to the new 2.1 API they will use the new versioning system and work fine in newer versions with out any needed changes.
  
 
==Entry Points==
 
==Entry Points==
Line 26: Line 22:
 
  BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
 
  BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
 
  BZF_PLUGIN_CALL int [[bz_GetVersion]] ( 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(API)|event handlers]] needed and initialize any "one time" startup data.
 
[[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.
Line 39: Line 33:
 
  BZ_GET_PLUGIN_VERSION
 
  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.  
+
somewhere in its sources, and then export the function. This will automatically return the API version of the current API you are using. See the sample plug-ins for examples. These will be the only 3 functions called by bzfs for non-event actions.
  
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.
+
All entry point functions should be preceded with the BZF_PLUGIN_CALL macro. This macro will tell your compiler to export these functions so bzfs can call them after the plug-in is loaded.
  
 
==Types==
 
==Types==
Line 47: Line 41:
 
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.
 
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===
+
===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.
 
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.
  
Line 98: Line 92:
 
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.
 
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)}}
+
{{main|Event(API)}}
  
 
==Functions==
 
==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.
 
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)}}
+
{{main|Functions(API)}}
  
 
==Wiki Documentation==
 
==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)
 
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.
+
All API developers should use the bzfsAPI.h file as well for exact spellings of methods and parameters.
  
 
==See Also==
 
==See Also==
  
* [[Events (API)|API Events]]
+
* [[Event(API)|API Events]]
* [[Functions (API)|API Functions]]
+
* [[Functions(API)|API Functions]]
 
* [[Plug-ins]]
 
* [[Plug-ins]]
 
* [[BZFS]]
 
* [[BZFS]]

Please note that all contributions to BZFlagWiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see BZFlagWiki:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel | Editing help (opens in new window)

Templates used on this page: