BZFS API Updates

The BZFS API was first introduced in BZFlag 2.0.4. Since then, there has been numerous changes, including the massive overhaul from 2.0 to 2.4.x (More information on this can be found on the BZFS_API_2.4_Upgrade page.)

2.0.x

bz_Load

Code Example

 BZF_PLUGIN_CALL int bz_Load ( const char* /*commandLine*/ ) {
     bz_debugMessage(4,"SAMPLE_PLUGIN plugin loaded");
     return 0;
 }

Functions

The bz_Load function is required for all plugins. In this function all debug messages, events, map objects, and slash commands are registered. Available functions for this are as follows:

• bz_debugMessage
• bz_registerEvent
• bz_registerCustomMapObject
• bz_registerCustomSlashCommand

Deprecation

All calls to bz_Load have been deprecated as of 2.4 and will be replaced with:

# void SAMPLE_PLUGIN::Init ( const char* config);

bz_registerEvent

bool bz_registerEvent (bz_eEventType eventType, bz_EventHandler* eventHandler)

Registers a new event handler. This event handler will receive events of the event type specified.

Parameters:

eventType  -  The type of event to listen for

eventHandler  -  The listener that will be called when events of the specified type occur

Returns:

Whether or not the event was registered successfully.

Deprecation

All calls to bz_registerEvent have been deprecated as of 2.4 and will be replaced with:

# Register(bz_eEventType eventType)

bz_Unload

Code Example

 BZF_PLUGIN_CALL int bz_Unload ( void ) {
     bz_debugMessage(4,"SAMPLE_PLUGIN plugin unloaded");
     return 0;
 }

Functions

The bz_Unload function is required for all plugins. In this function all debug messages, events, map objects, and slash commands are unregistered. Available functions for this are as follows:

• bz_debugMessage
• bz_removeEvent
• bz_removeCustomSlashCommand
• bz_removeCustomMapObject

Deprecation

All calls to bz_Unload have been deprecated as of 2.4 and will be replaced with:

 virtual void Cleanup() {Flush();}

bz_removeEvent

bool bz_removeEvent (bz_eEventType eventType, bz_EventHandler* listener)

Removes the specified event listener. The event listener must previously have been added by a call to bz_registerEvent.

Parameters:

eventType  -  The type of event that this listener was previously registered to handle. This is so that if this listener is registered for multiple event types, only one of those will be removed.

listener  -  The listener to remove.

Returns:

Whether or not the event was removed successfully.

Deprecation

All calls to bz_removeEvent in the bz_Unload have been deprecated as of 2.4 and will be replaced with:

# Flush();

2.4.x

Init

Code Example

 void SAMPLE_PLUGIN::Init ( const char* /*commandLine*/ ) {
     bz_debugMessage(4,"SAMPLE_PLUGIN plugin loaded");
     return 0;
 }

Functions

The Init function is required for all plugins 2.4 and higher. This function replaces the bz_Load function. In this function all debug messages, events, map objects, and slash commands are registered. Available functions for this are as follows:

• bz_debugMessage
• Register
• bz_registerCustomMapObject
• bz_registerCustomSlashCommand

Register

Example

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

Cleanup

Code Example

 void SAMPLE_PLUGIN::Cleanup( void ) {
     Flush(); //This removes all events that were registered with Registered()
     bz_debugMessage(4,"SAMPLE_PLUGIN plugin unloaded");
     return 0;
 }

Functions

The Cleanup function is required for all plugins. This function replaces the bz_Unload function in plugins written for 2.4 or higher. In this function all debug messages, events, map objects, and slash commands are unregistered. Available functions for this are as follows:

• bz_debugMessage
• Flush()
• bz_removeCustomSlashCommand
• bz_removeCustomMapObject

The Flush() function is called once in 2.4 plugins instead of having to a bz_removeEvent remove each registered event individually.