Difference between revisions of "BZFS API"

From BZFlagWiki
Jump to: navigation, search
m (bzAPILists: The classes now use underscores (bz_APIIntList vs bzAPIIntList, bz_ApiString vs bzApiString, etc))
m (bzApiString: s/bzApiString/bz_ApiString)
Line 39: Line 39:
 
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.
  
===bzApiString===
+
===bz_ApiString===
Any text passed back from the API or events will come in the form of a [[bzApiString]]. 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.
  
A plug-in should never need to make variables of its' own using the [[bzApiString]] type, but should use a standard stl std::string instead, [[bzApiString]] provides an appropriate assignment operator.
+
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.
  
[[bzApiString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.
+
[[bz_ApiString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.
  
 
===bz_APILists===
 
===bz_APILists===

Revision as of 03:10, 14 August 2007

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

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 there source code so that they may access the functions it contains.

Naming Conventions

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

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.

As of version 2.1 of BZFlag, the entire API was versioned and set up to use derived classes to 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

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

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 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.

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

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.

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

bz_APILists

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

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

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.

See the API events page for more detailed information on events.

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.

See the API Functions page for more information on functions.

See Also

BZFS

Plug-ins