BZFlagWiki - User contributions [en]

Plug-ins

2009-09-29T23:07:31Z

Xalendare: /* Preparing a Linux BZFS */

BZFS can be built to support the loading of external libraries as plug-ins. These plug-ins can alter or replace the logic applied by the server, as well as automate many common tasks.

Plug-ins are a simpler way to apply modifications to the game, as they do not require the server owner to modify or recompile his/her BZFS application. By using the [[BZFS API]] plug-ins are also able to be mixed and matched in an easy way.

==Overview==
Plug-ins are compile dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On [http://www.microsoft.com/windows Microsoft Windows] they are built as [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] files. On [http://www.linux.org Linux] and other [http://www.unix.org/ Unix]-like systems they are built as .so files.

==Use==
Plug-ins are loaded at startup by the '''-loadplugin''' option, or at run time with the ''/loadplugin'' command. If the full path to the plug-in is not specified, then [[BZFS]] will search a number of known sub directories for the plug-in as it attempts to load it. Using a valid path to the plug-in on load is highly recommended. While playing, all plug-ins loaded onto the server are visible with the /listplugins command.
===Parameters===
Some plug-ins take parameters that are passed to the plug-in on load. This is often a numeric value, or a path to a file. To pass a parameter to a plug-in, simply add a ',' after the plug-in name or path, and then add the parameter. Parameters can not have spaces, due to the way [[BZFS]] parses command line options and / commands.

On load, plug-ins install a number of callbacks and event handlers with the hosting [[BZFS]] that are called when specific events happen. This allows the plug-in to perform additional actions on these events, or if need be, alter the results of the default logic of the server.
===Search Paths===
[[BZFS]] searches for plug-ins in two standard locations: the config directory and the global plug-ins directory. The config directory is where the BZFlag config.cfg file is located, and the global plug-ins directory is $(prefix)/lib/bzflag/.

==BZFS API==
All plug-ins are linked to the [[BZFS API]]. This programing layer provides the interface to the BZFS application. All events and functions that a plug-in can call are in the [[BZFS API]].

==Standard plug-ins==
The [[BZFlag Source]] distribution contains a number of plug-ins that are maintained by the project [http://my.bzflag.org/wiki/index.php/Category:Developer developers].
These plug-ins are located in the ''/plugins'' directory.

As of August 2009, [[BZFlag SVN|SVN]] TRUNK( version [[BZFlag 3.0|2.99]]) contains the following plug-ins:

*[[airspawn]]
*[[bzfscron]]
*[[chathistory]]
*[[chatlog]]
*[[customflagsample]]
*[[fastmap]]
*[[flagStay]]
*[[hiddenAdmin]]
*[[HoldTheFlag]]
*[[HTTPServer]]
*[[httpTest]]
*[[keepaway]]
*[[killall]]
*[[koth]]
*[[logDetail]]
*[[mapchange]]
*[[nagware]]
*[[Phoenix]]
*[[playHistoryTracker]]
*[[python(plug-in)|python]]
*[[rabidRabbit]]
*[[recordmatch]]
*[[regFlag]]
*[[RogueGenocide]]
*[[SAMPLE_PLUGIN]]
*[[serverControl]]
*[[serverSideBotSample]]
*[[shockwaveDeath]]
*[[soundTest]]
*[[teamflagreset]]
*[[thiefControl]]
*[[timedctf]]
*[[torBlock]]
*[[unrealCTF]]
*[[weaponArena]]
*[[webadmin]]
*[[webReport]]
*[[webstats]]
*[[wwzones]]

==Third Party Plug-ins==
A number of non-developers have created plug-ins for BZFS, and usually release them on the [http://my.bzflag.org/bb/ BZFlag Forums].

Here are the steps to compile a hypothetical third party plug-in named "Example":

# In the plugins directory of the BZFlag source tree run the command '''./newplugin.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplugin.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# In the top-level BZFlag source directory, edit configure.ac, and add plugins/Example/Makefile to the list of AC_CONFIG_FILES
# In the top-level BZFlag source directory run '''autogen.sh''', '''configure''', and '''make''' as usual

When that finishes successfully the plug-in should be ready to use as described above.

==Preparing a Linux BZFS==

In order to run plugins in BZFS, you need to recompile it with the --enable-shared option on the configure script.

$ ./configure --enable-shared --disable-client;
make;
make install;

==Plug-in Development==
{{DoDoc|Describe the basics of plug-in development.}}

[[Category:Server]]
[[Category:Development]]
[[Category:Plug-Ins]]

Plug-ins

2009-09-29T23:06:48Z

Xalendare: /* Preparing a Linux BZFS */

BZFS can be built to support the loading of external libraries as plug-ins. These plug-ins can alter or replace the logic applied by the server, as well as automate many common tasks.

Plug-ins are a simpler way to apply modifications to the game, as they do not require the server owner to modify or recompile his/her BZFS application. By using the [[BZFS API]] plug-ins are also able to be mixed and matched in an easy way.

==Overview==
Plug-ins are compile dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On [http://www.microsoft.com/windows Microsoft Windows] they are built as [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] files. On [http://www.linux.org Linux] and other [http://www.unix.org/ Unix]-like systems they are built as .so files.

==Use==
Plug-ins are loaded at startup by the '''-loadplugin''' option, or at run time with the ''/loadplugin'' command. If the full path to the plug-in is not specified, then [[BZFS]] will search a number of known sub directories for the plug-in as it attempts to load it. Using a valid path to the plug-in on load is highly recommended. While playing, all plug-ins loaded onto the server are visible with the /listplugins command.
===Parameters===
Some plug-ins take parameters that are passed to the plug-in on load. This is often a numeric value, or a path to a file. To pass a parameter to a plug-in, simply add a ',' after the plug-in name or path, and then add the parameter. Parameters can not have spaces, due to the way [[BZFS]] parses command line options and / commands.

On load, plug-ins install a number of callbacks and event handlers with the hosting [[BZFS]] that are called when specific events happen. This allows the plug-in to perform additional actions on these events, or if need be, alter the results of the default logic of the server.
===Search Paths===
[[BZFS]] searches for plug-ins in two standard locations: the config directory and the global plug-ins directory. The config directory is where the BZFlag config.cfg file is located, and the global plug-ins directory is $(prefix)/lib/bzflag/.

==BZFS API==
All plug-ins are linked to the [[BZFS API]]. This programing layer provides the interface to the BZFS application. All events and functions that a plug-in can call are in the [[BZFS API]].

==Standard plug-ins==
The [[BZFlag Source]] distribution contains a number of plug-ins that are maintained by the project [http://my.bzflag.org/wiki/index.php/Category:Developer developers].
These plug-ins are located in the ''/plugins'' directory.

As of August 2009, [[BZFlag SVN|SVN]] TRUNK( version [[BZFlag 3.0|2.99]]) contains the following plug-ins:

*[[airspawn]]
*[[bzfscron]]
*[[chathistory]]
*[[chatlog]]
*[[customflagsample]]
*[[fastmap]]
*[[flagStay]]
*[[hiddenAdmin]]
*[[HoldTheFlag]]
*[[HTTPServer]]
*[[httpTest]]
*[[keepaway]]
*[[killall]]
*[[koth]]
*[[logDetail]]
*[[mapchange]]
*[[nagware]]
*[[Phoenix]]
*[[playHistoryTracker]]
*[[python(plug-in)|python]]
*[[rabidRabbit]]
*[[recordmatch]]
*[[regFlag]]
*[[RogueGenocide]]
*[[SAMPLE_PLUGIN]]
*[[serverControl]]
*[[serverSideBotSample]]
*[[shockwaveDeath]]
*[[soundTest]]
*[[teamflagreset]]
*[[thiefControl]]
*[[timedctf]]
*[[torBlock]]
*[[unrealCTF]]
*[[weaponArena]]
*[[webadmin]]
*[[webReport]]
*[[webstats]]
*[[wwzones]]

==Third Party Plug-ins==
A number of non-developers have created plug-ins for BZFS, and usually release them on the [http://my.bzflag.org/bb/ BZFlag Forums].

Here are the steps to compile a hypothetical third party plug-in named "Example":

# In the plugins directory of the BZFlag source tree run the command '''./newplugin.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplugin.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# In the top-level BZFlag source directory, edit configure.ac, and add plugins/Example/Makefile to the list of AC_CONFIG_FILES
# In the top-level BZFlag source directory run '''autogen.sh''', '''configure''', and '''make''' as usual

When that finishes successfully the plug-in should be ready to use as described above.

==Preparing a Linux BZFS==

For becoming BZFS able to run plugins you need to recompile it with the --enable-shared option on the configure script.

$ ./configure --enable-shared --disable-client;
make;
make install;

==Plug-in Development==
{{DoDoc|Describe the basics of plug-in development.}}

[[Category:Server]]
[[Category:Development]]
[[Category:Plug-Ins]]

Talk:Plug-ins

2009-09-29T23:05:15Z

Xalendare:

So is it plug-ins or plugins? [[User:DonnyBaker|DonnyBaker]] 21:33, 23 March 2007 (EDT)

I made a redirect from Plugins to Plug-ins. [[User:F687s|F687/s]]

The instructions at the bottom of the page for building third-party plugins appeared to be incorrect, so I edited them. If this is due to differences between the version I am building (2.0.12) and the current development version, feel free to revert my changes. [[User:Xalendare|Xalendare]] 19:05, 29 September 2009 (EDT)

Plug-ins

2009-09-29T22:59:26Z

Xalendare: /* Third Party Plug-ins */

BZFS can be built to support the loading of external libraries as plug-ins. These plug-ins can alter or replace the logic applied by the server, as well as automate many common tasks.

Plug-ins are a simpler way to apply modifications to the game, as they do not require the server owner to modify or recompile his/her BZFS application. By using the [[BZFS API]] plug-ins are also able to be mixed and matched in an easy way.

==Overview==
Plug-ins are compile dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On [http://www.microsoft.com/windows Microsoft Windows] they are built as [http://en.wikipedia.org/wiki/Dynamic-link_library DLL] files. On [http://www.linux.org Linux] and other [http://www.unix.org/ Unix]-like systems they are built as .so files.

==Use==
Plug-ins are loaded at startup by the '''-loadplugin''' option, or at run time with the ''/loadplugin'' command. If the full path to the plug-in is not specified, then [[BZFS]] will search a number of known sub directories for the plug-in as it attempts to load it. Using a valid path to the plug-in on load is highly recommended. While playing, all plug-ins loaded onto the server are visible with the /listplugins command.
===Parameters===
Some plug-ins take parameters that are passed to the plug-in on load. This is often a numeric value, or a path to a file. To pass a parameter to a plug-in, simply add a ',' after the plug-in name or path, and then add the parameter. Parameters can not have spaces, due to the way [[BZFS]] parses command line options and / commands.

On load, plug-ins install a number of callbacks and event handlers with the hosting [[BZFS]] that are called when specific events happen. This allows the plug-in to perform additional actions on these events, or if need be, alter the results of the default logic of the server.
===Search Paths===
[[BZFS]] searches for plug-ins in two standard locations: the config directory and the global plug-ins directory. The config directory is where the BZFlag config.cfg file is located, and the global plug-ins directory is $(prefix)/lib/bzflag/.

==BZFS API==
All plug-ins are linked to the [[BZFS API]]. This programing layer provides the interface to the BZFS application. All events and functions that a plug-in can call are in the [[BZFS API]].

==Standard plug-ins==
The [[BZFlag Source]] distribution contains a number of plug-ins that are maintained by the project [http://my.bzflag.org/wiki/index.php/Category:Developer developers].
These plug-ins are located in the ''/plugins'' directory.

As of August 2009, [[BZFlag SVN|SVN]] TRUNK( version [[BZFlag 3.0|2.99]]) contains the following plug-ins:

*[[airspawn]]
*[[bzfscron]]
*[[chathistory]]
*[[chatlog]]
*[[customflagsample]]
*[[fastmap]]
*[[flagStay]]
*[[hiddenAdmin]]
*[[HoldTheFlag]]
*[[HTTPServer]]
*[[httpTest]]
*[[keepaway]]
*[[killall]]
*[[koth]]
*[[logDetail]]
*[[mapchange]]
*[[nagware]]
*[[Phoenix]]
*[[playHistoryTracker]]
*[[python(plug-in)|python]]
*[[rabidRabbit]]
*[[recordmatch]]
*[[regFlag]]
*[[RogueGenocide]]
*[[SAMPLE_PLUGIN]]
*[[serverControl]]
*[[serverSideBotSample]]
*[[shockwaveDeath]]
*[[soundTest]]
*[[teamflagreset]]
*[[thiefControl]]
*[[timedctf]]
*[[torBlock]]
*[[unrealCTF]]
*[[weaponArena]]
*[[webadmin]]
*[[webReport]]
*[[webstats]]
*[[wwzones]]

==Third Party Plug-ins==
A number of non-developers have created plug-ins for BZFS, and usually release them on the [http://my.bzflag.org/bb/ BZFlag Forums].

Here are the steps to compile a hypothetical third party plug-in named "Example":

# In the plugins directory of the BZFlag source tree run the command '''./newplugin.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplugin.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# In the top-level BZFlag source directory, edit configure.ac, and add plugins/Example/Makefile to the list of AC_CONFIG_FILES
# In the top-level BZFlag source directory run '''autogen.sh''', '''configure''', and '''make''' as usual

When that finishes successfully the plug-in should be ready to use as described above.

==Preparing a Linux BZFS==

For becoming BZFS able to run plugins you need to recompile it with the --enable-shared and --enable-plugins options on the configure script.

$ ./configure --enable-shared --enable-plugins --disable-client;
make;
make install;

==Plug-in Development==
{{DoDoc|Describe the basics of plug-in development.}}

[[Category:Server]]
[[Category:Development]]
[[Category:Plug-Ins]]

Bz eKickEvent

2009-05-08T17:47:33Z

Xalendare:

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eKickEvent''' is an API event triggered when a player is kicked from the server.

==Data==
'''bz_eKickEvent''' returns the '''bz_KickEventData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eKickEvent
|-
|kickerID
|int
|The ID of the player who performed the kick.
|-
|kickedID
|int
|The ID of the player being kicked from the server.
|-
|reason
|[[bz_ApiString]]
|The reason (provided by the kicker using the '''/kick''' [[Slash_commands|slash command]]) for the kick.
|-
|eventTime
|double
|The server time the event occurred (in seconds.)
|}

==Uses==

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Events (API)

2009-05-08T04:04:09Z

Xalendare: /* Events */ Added pipe from bz_eGameEndEvent to bz_eGameStartEvent page, since they share the same EventData class.

{{DoDoc|Fill in articles for all API events}}

{{BZFS_API_Doc}}

==Overview==
API events are callbacks that a [[Plug-ins|plug-in]] can install into [[BZFS]] to be called in response to specific actions or state changes in the server side game world. Events are the primary method of communication from BZFS to installed plug-ins. Specific events exist for nearly all logical actions that can happen during a game of BZFlag.

==Installation and Removal==
The callbacks for events are typically installed during the [[bz_Load]] entry point in a plug-in, so they can be active when a plug-in is first loaded.

The plug-in must call the function;

BZF_API bool [[bz_registerEvent]] ( bz_eEventType eventType, [[bz_EventHandler]]* eventHandler );

The plug-in registers and event callback derived from [[bz_EventHandler]] for each specific event types it wishes to monitor.

When a plug-in no longer needs to monitor an event, or when it is unloaded in the [[bz_Unload]] entry point, the plug-in must remove the installed callback by calling the function;

BZF_API bool [[bz_removeEvent]] ( bz_eEventType eventType, [[bz_EventHandler]]* eventHandler );

==Event Handler==
The plug-in must define a class that is derived from [[bz_EventHandler]] and pass a pointer to an object of that class when ever it registers an event callback.

When ever a specific event is triggered, BZFS will call the 'process' method of the installed callback class.

virtual void process ( bz_EventData *eventData ) = 0;

==Event Data==
With each call to the 'process' method of the installed event handler, BZFS will pass the plug-in a pointer to a class that contains all the data provided by the event. Each event derives a specific data class from [[bz_EventData]] that contains the specific member variables that contain the data. The base class [[bz_EventData]] contains the data member;
bz_eEventType eventType;
This data member allows a plug-in to identify the specific event and cast the 'bz_EventData' pointer to the appropriate specific data class. This is usefull for plug-ins that use the same 'bz_EventHandler' to process more then one specific message.

Please see the descriptions of each specific event for information and descriptions of the data classes for each event. Some specific events allow plug-ins to change the values of data members in the data class and will use the modified values instead.

Plug-ins should never delete or free the memory for a data class. BZFS will manage all pointers passed to plug-ins.

==Events==
The following list contains all the event types currently supported by BZFS version 2.99

[[bz_eNullEvent]]
[[bz_eCaptureEvent]]
[[bz_ePlayerDieEvent]]
[[bz_ePlayerSpawnEvent]]
[[bz_eZoneEntryEvent]]
[[bz_eZoneExitEvent]]
[[bz_ePlayerJoinEvent]]
[[bz_ePlayerPartEvent]]
[[bz_eRawChatMessageEvent]]
[[bz_eFilteredChatMessageEvent]]
[[bz_eUnknownSlashCommand]]
[[bz_eGetPlayerSpawnPosEvent]]
[[bz_eGetAutoTeamEvent]]
[[bz_eAllowPlayer]]
[[bz_eTickEvent]]
[[bz_eGetWorldEvent]]
[[bz_eGetPlayerInfoEvent]]
[[bz_eAllowSpawn]]
[[bz_eListServerUpdateEvent]]
[[bz_eBanEvent]]
[[bz_eHostBanNotifyEvent]]
[[bz_eHostBanModifyEvent]]
[[bz_eIdBanEvent]]
[[bz_eKickEvent]]
[[bz_eKillEvent]]
[[bz_ePlayerPausedEvent]]
[[bz_eMessageFilteredEvent]]
[[bz_eGameStartEvent]]
[[bz_eGameStartEvent|bz_eGameEndEvent]]
[[bz_eSlashCommandEvent]]
[[bz_ePlayerAuthEvent]]
[[bz_eServerMsgEvent]]
[[bz_eShotFiredEvent]]
[[bz_eAnointRabbitEvent]]
[[bz_eNewRabbitEvent]]
[[bz_eReloadEvent]]
[[bz_ePlayerUpdateEvent]]
[[bz_eNetDataSendEvent]]
[[bz_eNetDataReceveEvent]]
[[bz_eLoggingEvent]]
[[bz_eFlagTransferredEvent]]
[[bz_eFlagGrabbedEvent]]
[[bz_eFlagDroppedEvent]]
[[bz_eShotEndedEvent]]
[[bz_eNewNonPlayerConnection]]
[[bz_eIdleNewNonPlayerConnection]]
[[bz_ePlayerCollision]]
[[bz_eFlagResetEvent]]
[[bz_eWorldFinalized]]
[[bz_eAllowCTFCaptureEvent]]
[[bz_eAllowFlagGrabEvent]]
[[bz_eAllowKillCommandEvent]]
[[bz_eReportFiledEvent]]
[[bz_eTeleportEvent]]

There exists one additional event in the 'bz_eEventType' enumeration in 'bzfsAPI.h', ''bz_eLastEvent''. This event is simply used by BZFS to assist in the counting of the total number of events, it will never be called and can not be installed.

==See also==
[[BZFS API]]

[[plug-ins]]

[[Category:BZFS_API_Events]]

Bz eGameStartEvent

2009-05-08T04:02:33Z

Xalendare: Added event description.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
'''bz_eGameStartEvent''' and '''bz_eGameEndEvent''' are API events triggered when a game (i.e., a time- or score-limited match) begins or ends, respectively.

==Data==
Both '''bz_eGameStartEvent''' and '''bz_eGameEndEvent''' return the '''bz_GameStartEndEventData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eGameStartEvent or bz_eGameEndEvent
|-
|duration
|double
|The duration (in seconds) of the game.
|-
|eventTime
|double
|The server time the event occurred (in seconds.)
|}

==Uses==

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz eListServerUpdateEvent

2009-05-08T02:50:27Z

Xalendare: /* Data */ Added eventTime field.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eListServerUpdateEvent''' is an API event called before the server adds itself to the list server.

==Data==
'''bz_eListServerUpdateEvent''' returns the '''bz_ListServerUpdateEvent_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
| bz_eListServerUpdateEvent
|-
|address
|[[bz_ApiString]]
|The public address of the server, as specified with the '''-publicaddr''' [[BZFS_Command_Line_Options |command-line option]].
|-
|description
|[[bz_ApiString]]
|The public description of the server, as specified with the '''-public''' [[BZFS_Command_Line_Options |command-line option]].
|-
|groups
|[[bz_ApiString]]
|The groups the server will be advertised to, as specified with the '''-advertise''' [[BZFS_Command_Line_Options |command-line option]].
|-
|handled
|bool
|
|-
|eventTime
|double
|The server time the event occurred (in seconds.)
|}

==Uses==
Allows the plugin to programmatically change the information sent to the list server; all fields (except the event type) are read/write.

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz eAllowSpawn

2009-05-08T02:49:15Z

Xalendare: /* Data */ Added eventTime field.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eAllowSpawn''' is an API event called before a player respawns.

==Data==
'''bz_eAllowSpawn''' returns the '''bz_AllowSpawnData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eAllowSpawn
|-
|playerID
|int
|The ID of the player that will spawn.
|-
|team
|[[bz_eTeamType]]
|The team the player belongs to.
|-
|handled
|bool
|
|-
|allow
|bool
|Set to false if the player should not be allowed to spawn.
|-
|eventTime
|double
|The server time the event occurred (in seconds.)
|}

==Uses==

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz eKickEvent

2009-05-08T02:48:30Z

Xalendare: Added documentation for event.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eKickEvent''' is an API event triggered when a player is kicked from the server.

==Data==
'''bz_eKickEvent''' returns the '''bz_KickEventData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eKickEvent
|-
|kickerID
|int
|The ID of the player who performed the kick.
|-
|kickedID
|int
|The ID of the player being kicked from the server.
|-
|reason
|[[bz_ApiString]]
|The reason (provided by the kicker using the '''/kick''' command) for the kick.
|-
|eventTime
|double
|The server time the event occurred (in seconds.)
|}

==Uses==

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz eListServerUpdateEvent

2009-05-08T02:39:54Z

Xalendare: Added documentation for event.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eListServerUpdateEvent''' is an API event called before the server adds itself to the list server.

==Data==
'''bz_eListServerUpdateEvent''' returns the '''bz_ListServerUpdateEvent_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
| bz_eListServerUpdateEvent
|-
|address
|[[bz_ApiString]]
|The public address of the server, as specified with the '''-publicaddr''' [[BZFS_Command_Line_Options |command-line option]].
|-
|description
|[[bz_ApiString]]
|The public description of the server, as specified with the '''-public''' [[BZFS_Command_Line_Options |command-line option]].
|-
|groups
|[[bz_ApiString]]
|The groups the server will be advertised to, as specified with the '''-advertise''' [[BZFS_Command_Line_Options |command-line option]].
|-
|handled
|bool
|
|}

==Uses==
Allows the plugin to programmatically change the information sent to the list server; all fields (except the event type) are read/write.

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz eAllowSpawn

2009-05-08T02:14:34Z

Xalendare: Added (incomplete) documentation for event.

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eAllowSpawn''' is an API event called before a player respawns.

==Data==
'''bz_eAllowSpawn''' returns the '''bz_AllowSpawnData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eAllowSpawn
|-
|playerID
|int
|The ID of the player that will spawn.
|-
|team
|[[bz_eTeamType]]
|The team the player belongs to.
|-
|handled
|bool
|
|-
|allow
|bool
|Set to false if the player should not be allowed to spawn.
|}

==Uses==

[[Category:BZFS_API_Docs]]
[[Category:BZFS_API_Events]]

Bz APIString

2009-05-08T01:57:53Z

Xalendare:

{{BZFS_API_Doc}}

==Overview==
The bz_ApiString is a text string utility class that is used by the [[BZFS API]] for passing text back to a plug-in from various events and functions. The class contains a number of utility methods commonly used by plug-ins.

==Construction==
plug-ins should never create a bz_ApiString, they are only passed back to the plug-in by BZFS.

==Assignment==
The standard = operator is provided to assign the value in a string, from other strings, std::strings, and const char pointers.

==Boolean Operators==
The standard == and != operators are provided to assign allow testing of bz_ApiStrings with other bz_ApiStrings, std::strings and const char* pointers.

BzApiString

2009-05-08T01:57:23Z

Xalendare: BzApiString moved to Bz APIString: Undo

#REDIRECT [[Bz APIString]]

Bz APIString

2009-05-08T01:57:23Z

Xalendare: BzApiString moved to Bz APIString: Undo

{{BZFS_API_Doc}}

==Overview==
The bzApiString is a text string utility class that is used by the [[BZFS API]] for passing text back to a plug-in from various events and functions. The class contains a number of utility methods commonly used by plug-ins.

==Construction==
plug-ins should never create a bzApiString, they are only passed back to the plug-in by BZFS.

==Assignment==
The standard = operator is provided to assign the value in a string, from other strings, std::strings, and const char pointers.

==Boolean Operators==
The standard == and != operators are provided to assign allow testing of bzApiStrings with other bzApiStrings, std::strings and const char* pointers.

BzAPIIntList

2009-05-08T01:56:34Z

Xalendare: BzAPIIntList moved to Bz APIIntList over redirect: Undo...

#REDIRECT [[Bz APIIntList]]

Bz APIIntList

2009-05-08T01:56:34Z

Xalendare: BzAPIIntList moved to Bz APIIntList over redirect: Undo...

A list of integers. This is used for passing lists of integers from the bzfs api itself to the plugin that uses the api.

BZFS API

2009-05-08T01:56:12Z

Xalendare: Undoing..

{{DoDoc|fill in articles for all API functions}}

The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by [[BZFS]] to be used by [[Plug-ins]]. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.

==Overview==
The BZFS API is defined entirely in the '''bzfsAPI.h''' header file that is part of the [[BZFlag Source]] code. The header is also included with each install of the BZFlag installer for Microsoft Windows.

Plug-ins include this file in their source code so that they may access the functions it contains.

==Naming Conventions==
All BZFS API code structures will begin with the prefix '''bz''' or '''bz_''' for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.

==API Versions==
The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.

As of version 2.1 of BZFlag, the entire API was versioned and set up to use derived classes to that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures would be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out a source code change. Once older plug-ins are updated to the new 2.1 API they will use the new versioning system and work fine in newer versions with out any needed changes.

==Entry Points==
There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement.

BZF_PLUGIN_CALL int [[bz_Load]] ( const char* command );
BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
BZF_PLUGIN_CALL int [[bz_GetVersion]] ( void );

[[bz_Load]] is called when the plug-in is first initialized. This is when the plug-in should register any [[Event(API)|event handlers]] needed and initialize any "one time" startup data.

[[bz_Unload]] is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.

[[bz_GetVersion]] is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.

'''bzfsAPI.h''' defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro;

BZ_GET_PLUGIN_VERSION

somewhere in its sources, and then export the function. This will automatically return the API version of the current API you are using. See the sample plug-ins for examples. These will be the only 3 functions called by bzfs for non-event actions.

All entry point functions should be preceded with the BZF_PLUGIN_CALL macro. This macro will tell your compiler to export these functions so bzfs can call them after the plug-in is loaded.

==Types==

Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.

===bz_ApiString===
Any text passed back from the API or events will come in the form of a [[bz_ApiString]]. This is a class defined in the API that behaves much like a std::string. The 'c_str()' method can be used to get the text out as a normal 'const char*'. The class also supports many assignment functions for setting it's contents.

A plug-in should never need to make variables of its' own using the [[bz_ApiString]] type, but should use a standard stl std::string instead, [[bz_ApiString]] provides an appropriate assignment operator.

[[bz_ApiString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.

===bz_APILists===

A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function.
The lists types are;
{| border="1" cellpadding="20" cellspacing="0"
!List
!allocator function
!delete function
!contained type
|-
|[[bz_APIIntList]]
|[[bz_newIntList]]
|[[bz_deleteIntList]]
|int
|-
|[[bz_APIFloatList]]
|[[bz_newFloatList]]
|[[bz_deleteFloatList]]
|float
|-
|[[bz_APIStringList]]
|[[bz_newStringList]]
|[[bz_deleteStringList]]
|[[bz_ApiString]]
|}

===Enumerations===
A number of enumerations exist in the API and are used by a number of API functions and events.
[[bz_eTeamType]]
[[Event(API)|bz_eEventType]]
[[bz_eShotType]]
[[bz_eGameType]]
[[bz_ePlayerStatus]]
[[bz_eWorldObjectType]]
[[bz_eAPIColType]]
[[bz_ePlayerType]]
[[bz_eRejectCodes]]
[[bz_ePlayerDeathReason]]

==Events==
Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.

See the [[Event(API)|API events]] page for more detailed information on events.

==Functions==
The BZFS API provides a number of functions to plug-ins for use in querying the current game state. Functions are used both to get information about the game, and to trigger in game actions, such as activating a world weapon.

See the [[Functions(API)|API Functions]] page for more information on functions.

==Wiki Documentation==
The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a ''History'' section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)

All API developers should use the bzfsAPI.h file as well for exact spellings of methods and parameters.

==See Also==

[[Event(API)|API Events]]

[[Functions(API)|API Functions]]

[[Plug-ins]]

[[BZFS]]

[[Category:Development]]
[[Category:Plug-Ins]]

BzAPIStringList

2009-05-08T01:55:07Z

Xalendare: BzAPIStringList moved to Bz APIStringList over redirect: Undoing previous move...

#REDIRECT [[Bz APIStringList]]

Bz APIStringList

2009-05-08T01:55:07Z

Xalendare: BzAPIStringList moved to Bz APIStringList over redirect: Undoing previous move...

{{BZFS_API_Doc}}{{BZFS_API_Class}}
==Declaration==
class BZF_API bz_APIStringList {
public:
bz_APIStringList();
bz_APIStringList(const bz_APIStringList &r);
bz_APIStringList(const std::vector<std::string> &r);

~bz_APIStringList();

void push_back ( const [[bz_ApiString]] &value );
void push_back ( const std::string &value );
bz_ApiString get ( unsigned int i );

const bz_ApiString& operator[] (unsigned int i) const;
bz_APIStringList& operator= ( const bz_APIStringList &r );
bz_APIStringList& operator= ( const std::vector<std::string> &r );

unsigned int size ( void );
void clear ( void );

void tokenize ( const char* in, const char* delims, int maxTokens = 0, bool useQuotes = false);
};

BZF_API bz_APIStringList* bz_newStringList ( void );
BZF_API void bz_deleteStringList( bz_APIStringList * l );

==Description==
Contains a list of strings.
Comparable to std::vector<std::string>

Plugins generally should never create Bz_APIStringList objects, only copy the data out.

==Member Access==
[[bz_ApiString]] get ( unsigned int i );

const bz_ApiString& operator[] (unsigned int i) const;

===Parameters===
; unsigned int i : bz_ApiString element to return

==Functions==
===size===
unsigned int size ( void );

Returns the number of elements on the list

===clear===
void clear ( void );

Removes all elements from the list

===tokenize===
void tokenize ( const char* in, const char* delims, int maxTokens = 0, bool useQuotes = false);

Appends a list generated from a tokenized string. Use of this function is discouraged, the tokenize() function available in plugin_utils is prefered.

Bz APIStringList

2009-05-08T01:52:45Z

Xalendare: Bz APIStringList moved to BzAPIStringList: Name out-of-date

Bz APIIntList

2009-05-08T01:52:10Z

Xalendare: Bz APIIntList moved to BzAPIIntList: Name out-of-date

A list of integers. This is used for passing lists of integers from the bzfs api itself to the plugin that uses the api.

BZFS API

2009-05-08T01:50:53Z

Xalendare: Changing out-of-date class names

{{DoDoc|fill in articles for all API functions}}

The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by [[BZFS]] to be used by [[Plug-ins]]. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.

==Overview==
The BZFS API is defined entirely in the '''bzfsAPI.h''' header file that is part of the [[BZFlag Source]] code. The header is also included with each install of the BZFlag installer for Microsoft Windows.

Plug-ins include this file in their source code so that they may access the functions it contains.

==Naming Conventions==
All BZFS API code structures will begin with the prefix '''bz''' or '''bz_''' for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.

==API Versions==
The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.

As of version 2.1 of BZFlag, the entire API was versioned and set up to use derived classes to that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures would be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out a source code change. Once older plug-ins are updated to the new 2.1 API they will use the new versioning system and work fine in newer versions with out any needed changes.

==Entry Points==
There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement.

BZF_PLUGIN_CALL int [[bz_Load]] ( const char* command );
BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
BZF_PLUGIN_CALL int [[bz_GetVersion]] ( void );

[[bz_Load]] is called when the plug-in is first initialized. This is when the plug-in should register any [[Event(API)|event handlers]] needed and initialize any "one time" startup data.

[[bz_Unload]] is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.

[[bz_GetVersion]] is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.

'''bzfsAPI.h''' defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro;

BZ_GET_PLUGIN_VERSION

somewhere in its sources, and then export the function. This will automatically return the API version of the current API you are using. See the sample plug-ins for examples. These will be the only 3 functions called by bzfs for non-event actions.

All entry point functions should be preceded with the BZF_PLUGIN_CALL macro. This macro will tell your compiler to export these functions so bzfs can call them after the plug-in is loaded.

==Types==

Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.

===bzApiString===
Any text passed back from the API or events will come in the form of a [[bzApiString]]. This is a class defined in the API that behaves much like a std::string. The 'c_str()' method can be used to get the text out as a normal 'const char*'. The class also supports many assignment functions for setting it's contents.

A plug-in should never need to make variables of its' own using the [[bzApiString]] type, but should use a standard stl std::string instead, [[bzApiString]] provides an appropriate assignment operator.

[[bzApiString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.

===bzAPILists===

A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function.
The lists types are;
{| border="1" cellpadding="20" cellspacing="0"
!List
!allocator function
!delete function
!contained type
|-
|[[bzAPIIntList]]
|[[bz_newIntList]]
|[[bz_deleteIntList]]
|int
|-
|[[bzAPIFloatList]]
|[[bz_newFloatList]]
|[[bz_deleteFloatList]]
|float
|-
|[[bzAPIStringList]]
|[[bz_newStringList]]
|[[bz_deleteStringList]]
|[[bzApiString]]
|}

===Enumerations===
A number of enumerations exist in the API and are used by a number of API functions and events.
[[bz_eTeamType]]
[[Event(API)|bz_eEventType]]
[[bz_eShotType]]
[[bz_eGameType]]
[[bz_ePlayerStatus]]
[[bz_eWorldObjectType]]
[[bz_eAPIColType]]
[[bz_ePlayerType]]
[[bz_eRejectCodes]]
[[bz_ePlayerDeathReason]]

==Events==
Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.

See the [[Event(API)|API events]] page for more detailed information on events.

==Functions==
The BZFS API provides a number of functions to plug-ins for use in querying the current game state. Functions are used both to get information about the game, and to trigger in game actions, such as activating a world weapon.

See the [[Functions(API)|API Functions]] page for more information on functions.

==Wiki Documentation==
The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a ''History'' section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)

All API developers should use the bzfsAPI.h file as well for exact spellings of methods and parameters.

==See Also==

[[Event(API)|API Events]]

[[Functions(API)|API Functions]]

[[Plug-ins]]

[[BZFS]]

[[Category:Development]]
[[Category:Plug-Ins]]

Bz APIString

2009-05-08T01:46:19Z

Xalendare: Changing names...

Bz ApiString

2009-05-08T01:45:13Z

Xalendare: Bz ApiString moved to BzApiString: Class has been renamed in the API

#REDIRECT [[BzApiString]]

Bz APIString

2009-05-08T01:45:12Z

Xalendare: Bz ApiString moved to BzApiString: Class has been renamed in the API

Bz eTickEvent

2009-05-05T00:54:55Z

Xalendare: /* Data */

{{BZFS_API_Doc}}
{{BZFS_API_Events}}

==Overview==
The '''bz_eTickevent''' is an API event that is called once for each [[BZFS]] main loop. The wait time between tick calls can vary grealy depending on server load network conditions. Plug-ins that wish to enforce a maximum wait time between ticks should call [[bz_setMaxWaitTime]] with the longest wait time that is acceptable.

==Data==
'''bz_eTickEvent''' returns the '''bz_TickEventData_V1''' data class.

{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|eventType
|[[Event(API)|bz_eEventType]]
|bz_eTickEvent
|-
|time
|double
|Local Server time of the event (in seconds)
|}

Bz eTickEvent

2009-05-05T00:54:30Z

Xalendare: /* Data */