BZFS API examples

Various examples of the BZFS API. This may be used a quick reference or guide for getting started and contains various tips or tricks for using it.

Examples List

• bz_ePlayerPausedEvent
• bz ePlayerSpawnEvent
• bz eTickEvent
• bz_ePlayerScoreChanged

bz_ePlayerPausedEvent

Note: This is generally used to either prevent players from pausing or to help handle players who pause in custom game modes. Starter code from official docs: www.bzflag.org/documentation/developer/bzfs_api/events/bz_eplayerpausedevent/

bz_PlayerPausedEventData_V1* dataObject = (bz_PlayerPausedEventData_V1*)eventData;

// Data
// ---
// (int)          playerID - ID of the player who paused.
// (bool)         pause - Whether the player is pausing (true) or unpausing (false)
// (double)       eventTime - Time local server time for the event.

Here's an example of how to prevent players from pausing:

if (dataObject->pause == true) {
 bz_killPlayer(dataObject->playerID, false, BZ_SERVER); // Kill player, but don't force them to respawn at base.
 bz_incrementPlayerLosses(dataObject->playerID, -1); // We punished them, but we don't need to have them lose points. Remove a death.
}

bz ePlayerSpawnEvent

Note: This is commonly used for either granting players flags on spawn, or the eventTime is used as a timer of some sorts. (Players need to do x goal after spawning within x seconds.) Starter code from official docs: www.bzflag.org/documentation/developer/bzfs_api/events/bz_eplayerspawnevent/

bz_PlayerSpawnEventData_V1* dataObject = (bz_PlayerSpawnEventData_V1*)eventData;

// Data
// ---
// (int)          playerID - ID of the player who was added to the world.
// (bz_eTeamType) team - The team the player is a member of.
// (bz_PlayerUpdateState) state - The state record for the spawning player
// (double)       eventTime - Time local server time for the event.

Here's an example of granting players flags on spawn by their team. Note: This will only work on CTF mode and needs multiple team flags per team, as well as useless flags. This code could be much cleaner, but for the sake of minimal complexity, it's written as such.

if (bz_getPlayerTeam(dataObject->team) == eRogueTeam)  {bz_givePlayerFlag(dataObject->playerID, "US", true);}
if (bz_getPlayerTeam(dataObject->team) == eRedTeam)    {bz_givePlayerFlag(dataObject->playerID, "R*", true);}
if (bz_getPlayerTeam(dataObject->team) == eGreenTeam)  {bz_givePlayerFlag(dataObject->playerID, "G*", true);}
if (bz_getPlayerTeam(dataObject->team) == eBlueTeam)   {bz_givePlayerFlag(dataObject->playerID, "B*", true);}
if (bz_getPlayerTeam(dataObject->team) == ePurpleTeam) {bz_givePlayerFlag(dataObject->playerID, "P*", true);}

bz eTickEvent

Note: This is commonly used for timers. Since the delay between intervals is unpredictable, bz_setMaxWaitTime is sometimes used to specify what is the max duration between intervals.

Starter code from official docs: www.bzflag.org/documentation/developer/bzfs_api/events/bz_etickevent/

bz_TickEventData_V1* dataObject = (bz_TickEventData_V1*)eventData;

// Data
// ---
// (double)       eventTime - Local Server time of the event (in seconds)

Here's an example of how to implement a simple timer system with it:

// This code is outside of the tick event.
double timer; // This is used when we trigger it, possibly via slash command or game start event.
int countdown = 5; // This gives us 5 seconds.

// This is the code used in the tick event.
if ((dataObject->eventTime - timer) > 1.0) { // We check if a second has passed since our last timer update.
 timer += 1.0;
 countdown -= 1;
 bz_sendTextMessagef(BZ_SERVER, BZ_ALLUSERS, "%d", countdown);
 if (countdown <= 0) {
  // Do something here.
 }
}

bz_ePlayerScoreChanged

Note: Using any of the player score modifying/changing functions without any conditionals will lead to infinite loops.

Starter code from official docs: www.bzflag.org/documentation/developer/bzfs_api/events/bz_eplayerscorechanged/

bz_PlayerScoreChangeEventData_V1* dataObject = (bz_PlayerScoreChangeEventData_V1*)eventData;

// Data
// ---
// (int)          playerID - Player that has had a change of score.
// (bz_eScoreElement) element - The type of score that is being changed.
// (int)          thisValue - The new amount of element score the playerID has.
// (int)          lastValue - The old amount of element score the playerID had.
// (double)       eventTime - Time local server time for the event.

Here's an example of how we can use the player score changed event to modify player scores and keep them tied to specific game play accomplishments.

// Example of keeping a score tied.
if (dataObject->element == bz_eWins) {
 if (WinsFrom[dataObject->playerID] != dataObject->thisValue) { // We lookup from our WinsFrom array,
  //...to see if the players wins matches our score system, if not, we adjust it.
  bz_setPlayerWins(dataObject->playerID, WinsFrom[dataObject->playerID]);// This keeps our score in sync, but it doesn't keep us in a loop.
 }
}