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

BZFS API

From BZFlagWiki
Revision as of 01:18, 14 August 2007 by JeffM2501 (Talk | contribs)

Jump to: navigation, search

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

Events

Functions

TO BE MOVED TO REAL PAGES

All the following needs to be moved into real doc pages.

Team Info Functions

BZF_API unsigned int bz_getTeamPlayerLimit ( bz_eTeamType team )

Returns the player limit for the specified team. If an invalid team is used, 0 will be returned.

This function is in both 2.0.x CVS and 2.1 as of now.

Server Reset / Map Management

BZF_API bool bz_restart ( void );

This function will do the following things. 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 delisted, 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 ).

BZF_API void bz_setClientWorldDowloadURL( const char* URL );

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.

BZF_API const bzApiString bz_getClientWorldDowloadURL( void );

Returns the current world URL.

BZF_API bool bz_saveWorldCacheFile( const char* file );

Forces the server to save out a world cache file into the specified file. Returns false on failure.

These commands are in CVS for both 2.0.x and 2.1 as of now.

I'm sure the Restart function will need some work but any help testing it will be greatly appreciated.

Flag Drop Messages

bz_eFlagDroppedEvent


it is called whenever the server gets a dropped flag. 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

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.

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.

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

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.