bz RegisterCustomFlag

From BZFlagWiki
Revision as of 22:46, 25 September 2007 by DTRemenak (Talk | contribs) (doc registercustomflag)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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.


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


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


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


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


Requires BZFS 2.1.16 or newer.