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

Difference between revisions of "Bz eGetWorldEvent"

From BZFlagWiki
Jump to: navigation, search
(Map file override)
 
(5 intermediate revisions by 2 users not shown)
Line 3: Line 3:
  
 
==Overview==
 
==Overview==
The '''bz_eGetWorldEvent''' is an API event that is called when the world is defined.
+
The '''bz_eGetWorldEvent''' is an API event that is called before the [[BZFS]] server defines the world.
  
 
==Data==
 
==Data==
Line 19: Line 19:
 
   |generated
 
   |generated
 
   |bool
 
   |bool
   |Set to true if the world is generated (ie, not literally loaded from a file)
+
   |The value representing the state of the world generation. If another plug-in has generated a world, this value will be set to true. If the plug-in processing this event, adds world geometry using the '''bz_addWorld''' methods ([[bz_addWorldBox]], [[bz_addWorldPyramid]] etc. ) then it must set this value to true.
 
   |-
 
   |-
 
   |ctf
 
   |ctf
 
   |bool
 
   |bool
   |Set to true if the game is a [[CTF]]-type game
+
   |This value represents the game state being a Capture the Flag (CTF) type game. Mutually exclusive with other game type setings.
 
   |-
 
   |-
   |rabit
+
   |rabbit
 
   |bool
 
   |bool
   |Set to true if the game is a [[Rabbit Hunt]]-type game
+
   |This value represents the game state being a Rabbit Hunt type game. Mutually exclusive with other game type setings.
 
   |-
 
   |-
 
   |openFFA
 
   |openFFA
 
   |bool
 
   |bool
   |Set to true if the game is a [[Free For All]]-type game
+
   |This value represents the game state being a [[Free For All]] type game. Mutually exclusive with other game type setings.
 +
  |-
 +
  |worldBlob
 +
  |char*
 +
  |A pointer to a memory location from which to read the world stream.  Overrides worldFile.
 
   |-
 
   |-
 
   |worldFile
 
   |worldFile
 
   |[[bz_ApiString]]
 
   |[[bz_ApiString]]
   |Path to the world file, set to "" (empty string) if not used
+
   |The path to the map file that will be used when this event is completed. If the string is zero length, then either a plug-in defined map or a random map will be used.
 
   |-
 
   |-
 
   |eventTime
 
   |eventTime
 
   |double
 
   |double
   |Time of the event
+
   |Local Server time of the event.
 
   |}
 
   |}
 +
 
==Uses==
 
==Uses==
This event is a notification only event, none of the data returned can be changed.
+
This event is a modification event. It is the primary hook for plug-ins that wish to modify the world.  The available options are;
 +
 
 +
===Map file override ===
 +
If the plug-in wishes to force the server to use a specific map file, it can set the '''worldFile''' member.  This member may be set to any valid local path or an http:// or ftp:// URL.
 +
 
 +
The plug-in may instead use the worldFile member for information only, and write a valid BZW world into a contiguous memory location with a 0 terminating character, passing that pointer back to BZFS via the worldBlob member.  It is the caller's responsibility to free this memory; this may be done in the [[bz_eWorldFinalized]] event.
  
[[Category:BZFS_API_Docs]]
+
===Game Style overide===
[[Category:BZFS_API_Events]]
+
The plug-in may change the game style flags to override the initial game mode.

Latest revision as of 01:39, 27 January 2009

BZFS API Documentation This page contains part of the BZFS API documentation for use by Plug-ins on the BZFS server.

BZFS Event. This page documents a BZFS event that is called by the game server to notify plug-ins of various actions and state changes in the game world.


Overview[edit]

The bz_eGetWorldEvent is an API event that is called before the BZFS server defines the world.

Data[edit]

bz_eGetWorldEvent returns the bz_GetWorldEventData_V1 data class.

name type value description
eventType bz_eEventType bz_eGetWorldEvent
generated bool The value representing the state of the world generation. If another plug-in has generated a world, this value will be set to true. If the plug-in processing this event, adds world geometry using the bz_addWorld methods (bz_addWorldBox, bz_addWorldPyramid etc. ) then it must set this value to true.
ctf bool This value represents the game state being a Capture the Flag (CTF) type game. Mutually exclusive with other game type setings.
rabbit bool This value represents the game state being a Rabbit Hunt type game. Mutually exclusive with other game type setings.
openFFA bool This value represents the game state being a Free For All type game. Mutually exclusive with other game type setings.
worldBlob char* A pointer to a memory location from which to read the world stream. Overrides worldFile.
worldFile bz_ApiString The path to the map file that will be used when this event is completed. If the string is zero length, then either a plug-in defined map or a random map will be used.
eventTime double Local Server time of the event.

Uses[edit]

This event is a modification event. It is the primary hook for plug-ins that wish to modify the world. The available options are;

Map file override[edit]

If the plug-in wishes to force the server to use a specific map file, it can set the worldFile member. This member may be set to any valid local path or an http:// or ftp:// URL.

The plug-in may instead use the worldFile member for information only, and write a valid BZW world into a contiguous memory location with a 0 terminating character, passing that pointer back to BZFS via the worldBlob member. It is the caller's responsibility to free this memory; this may be done in the bz_eWorldFinalized event.

Game Style overide[edit]

The plug-in may change the game style flags to override the initial game mode.