bz RegisterCustomFlag

From BZFlagWiki
Jump to: navigation, search
BZFS API Documentation This page contains part of the BZFS API documentation for use by Plug-ins on the BZFS server.
BZFS API Function. This page documents a BZFS_API Function, that is provided by the BZFS game server for plug-ins to call.

Prototype[edit]

BZF_API bool bz_RegisterCustomFlag ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

Parameters[edit]

const char* abbr 
The desired flag abbreviation. Must be unique. Must be 1 or 2 characters.
const char* name 
The desired flag name. Max length 32 characters.
const char* helpString 
The desired help string. Max length 128 characters.
bz_eShotType shotType 
The default shot type for the flag.
bz_eFlagQuality quality 
The flag's quality (good/bad).

Description[edit]

This function registers a custom flag. The registered abbreviation must be unique (that is, may not conflict with existing built-in or API flags).

The registered flag will have no functionality by default (i.e. it will behave like Useless), but it can be used by your plugin by examining player records to see if they hold the flag, and taking appropriate action.

The flag's "stickiness" will be determined by quality; this is roughly consistent with BZFlag's builtin flags. Good flags will be Unstable (that is, when dropped they will disappear and be respawned); bad flags will be Sticky (that is, undroppable).

Usage[edit]

If you wish to use a custom flag with +/-f or -sl server parameters (including +f good and -f bad), or in flag zones on the map, you must register the flag during init via -loadplugin (or before a call to bz_restart, if using it in a map).

If a plugin registers a flag while there are clients connected, they will automatically receive the update. However, be aware that there is no corresponding bz_UnregisterCustomFlag function, so there is a limit to the dynamic capability of this functionality.

Version[edit]

Requires BZFS 2.1.16 (r15952) or newer.