BZFlagWiki - User contributions [en]

Plug-ins

2013-03-25T17:52:37Z

Rob5a: /* Third Party Plug-ins */ it's newplug.sh, not newplugin.sh

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 one of the more popular ways to apply modifications to the game. They do not require modifications of the BZFS application source code so it can be kept up to date with out the need to constantly apply patches. They have also proven to be a very simple method for distributing modifications from developers to players.

==Overview==
Plug-ins are compiled 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 [[:Category:Developer|developers]].
These plug-ins are located in the ''/plugins'' directory.

As of March 2013, [[BZFlag SVN|SVN]] TRUNK contains the following plug-ins:

*[[airspawn]]
*[[autoFlagReset]]
*[[bzfscron]]
*[[chathistory]]
*[[customflagsample]]
*[[fairCTF]]
*[[fastmap]]
*[[flagStay]]
*[[hiddenAdmin]]
*[[HoldTheFlag]]
*[[keepaway]]
*[[killall]]
*[[koth]]
*[[logDetail]]
*[[nagware]]
*[[Phoenix]]
*[[playHistoryTracker]]
*[[plugin_utils]]
*[[pushstats]]
*[[rabbitTimer]]
*[[rabidRabbit]]
*[[recordmatch]]
*[[regFlag]]
*[[RogueGenocide]]
*[[SAMPLE_PLUGIN]]
*[[serverControl]]
*[[serverSidePlayerSample]]
*[[shockwaveDeath]]
*[[superUser]]
*[[teamflagreset]]
*[[thiefControl]]
*[[timedctf]]
*[[TimeLimit]]
*[[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 '''./newplug.sh Example'''
# Remove all of the files from the newly created plugins/Example directory (they were created by newplug.sh)
# Copy all of the distributed Example files into the plugins/Example directory
# 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.

In Xcode on Mac OS X, follow these instructions:

# Click on the BZFlag project name in the project navigator. Click Add Target, and create a new C/C++ Library. Name the plugin, and select "Dynamic" for type.
# In the project navigator, move the new library target from the bottom of the screen into the "Targets" group.
# Click on the BZFlag project name in the project navigator again. In the list of targets, select the BZFlag application target. In the Build Phases tab, in the Target Dependencies pane, add your new library target as a dependency of the application target. Also add it to the Copy Files phase for the PlugIns directory.
# Select your new library target. Select the Build Settings tab, and locate the Other Linker Flags option. Add the option "-undefined dynamic_lookup"
# Find the Architecture build setting for your new library. Make sure it is the same architecture as the main codebase, or click Levels, click the Architecture setting under your library target, click Other, and delete the setting. This will make it assume the overall project build architecture.
# Add your source file(s) to the project, and make them members of your library target.
# Build as usual.

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

''Note that as of 2.4.0 the BZFlag configuration has --enable-shared automatically enabled.''

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

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

==History==
The plug-in system was added in BZFlag V. 2.0.4 and was initially met with a lukewarm reception by some of the core developers and the maintainer. The community has since embraced the concept and built a multitude of useful modifications, many that have been incorporated into the project as standard plug-ins.

For Version 3.0 major changes to the [[BZFS API]] have been made to increase its lifespan.

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

Bz RegisterCustomFlag

2012-10-03T15:28:32Z

Rob5a: typo

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API bool bz_RegisterCustomFlag ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

==Parameters==
; 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==
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==
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==
Requires BZFS 2.1.16 (r15952) or newer.

DI-Machine

2012-02-13T11:34:07Z

Rob5a: Updated links with proper formatting.

The DrawInfo-Machine is a script written in PHP to convert a WaveFront .obj file into a [[drawInfo]]-specific .bzw file. The related forum thread can be found [http://forums.bzflag.org/viewtopic.php?f=24&t=11514 here].

==Instructions for use==
#Download the script from [http://forums.bzflag.org/download/file.php?id=8018 here] and change the file-name to dI-Machine.php
# Download and install PHP 5 or later from [http://www.php.net/downloads.php#v5 the php website]. (PHP 4 may work, but it has not been tested)
#Using your favorite 3D modeler, export your model as an obj file.
# If desired, create multiple copies of your model with lower resolution (less polygons). This can be included in your map for viewing from a distance.
# At the command-line, type: php drawinfomachine.php /path/to/object.obj
#Copy and paste or pipe the result into a your map.

==History/Information==
The script was originally conceived by Optic Delusion and Tedius in an IRC conversation relating to the similarity of the obj syntax with that of the drawInfo object. The code was created by Tedius and improved by suggestions and submissions by Optic Delusion, Anomaly, Tanner, and Teppic. The machine was the first to give mappers a practical way to incorporate LODs and spinning objects in their maps. [[Modeltool | ModelTool v1.8.1]] and later [http://my.bzflag.org/bb/viewtopic.php?t=10820 BZWorkbench] also incorporated this capability as well.

[[category:Map Making]]
[[category:Map Editors]]

Category:Leagues

2010-01-11T11:32:54Z

Rob5a: added LavaHiX League

== BZFlag Leagues ==

To join a league click on one of the links below and register your callsign. Some leagues may require that you be added to a list by an admin before you are allowed to talk/spawn on match servers. Please use the same callsign for matching that you have register on the league site. Most of the IRC channels for each league are situated on the [http://freenode.net/ freenode] network. Please refer to [[BZFlag on IRC]] for help on using IRC.

== Ducati League ==
Website: [http://league.bzflag.org/ http://league.bzflag.org/]

IRC Channel: [irc://irc.freenode.net/##ducleague ##ducleague]

Match Length: 15, 20 or 30 minutes

Rules: 2 shots, no jumping, ricochet, CTF, randomly generated map.

== [[GU League]] ==
Website: [http://gu.bzleague.com/ http://gu.bzleague.com/]

IRC Channel: [irc://irc.freenode.net/#guleague #guleague]

Match Length: 30 minutes.

Rules: 3 shots, jumping, ricochet, CTF, [[HiX]] map.

== Pillbox League ==
Website: [http://pillbox.bzleague.com/ http://pillbox.bzleague.com/]

IRC Channel: [irc://irc.freenode.net/#pillbox #pillbox]

Match Length: 15, 20 or 30 minutes.

Rules: 3 shots, no jumping, no ricochet, CTF, pillbox map.

== [[Open League]] ==
Website: [http://openleague.net/ http://openleague.net/]

IRC Channel: [irc://irc.freenode.net/#openleague.net #openleague.net]

Match Length: 15, 20, 30, 45 or 60 minutes.

Rules: 3 shots, jumping , ricochet, CTF, [[babel]] or a map that changes every week (which can have different rules).

== 1vs1 League ==
Website: [http://1vs1.bzleague.com/ http://1vs1.bzleague.com/]

IRC Channel: None.

Match Length: First to 10 kills.

Rules:
:classic & fancy style: -> FFA mode, 2 shots, ricochet, no jumping, no superflags, small randomly generated map
:hix style -> FFA mode, 3 shots, ricochet, jumping, no superflags, hix map

== Fun League ==
Website: [http://fun.bzleague.com/ http://fun.bzleague.com/]

IRC Channel: None.

Match Length: Depends on which map you play on.

Rules: Depends on which map you play on.

== BZSoccer League ==

Website: [http://bzsoccer.bzleague.com/ http://bzsoccer.bzleague.com/] *Note* Website has many bugs and will be fixed soon.

IRC Channel: ##divi

Match length: 15 minutes

Rules: 2 shots, jumping, ricochet, soccer field map.

Please note that this league is inactive. The league will be revived when the website is fixed.

== LavaHiX League ==
Website: [http://lavahix.wtwrp.de/ http://lavahix.wtwrp.de/]

IRC Channel: None.

Match Length: 15 minutes.

Rules: 3 shots, jumping, ricochet, CTF, [[HiX]] map with "lava" ground.

== Defunct Leagues ==

=== Plosileague ===

Website: [http://bzfx.net/league/ http://bzfx.net/league/]

IRC Channel: [irc://irc.freenode.net/#plosileague #plosileague]

Match Length: 30 minutes or first to 5 caps and ahead of the other team by at least 2 caps

Rules: 3 shots, jumping, ricochet, CTF, [[overlord]] or [[babel]] map.

List Server

2010-01-07T20:42:59Z

Rob5a: It's now PHPBB3.

==Overview==
The BZFlag list server is a public service provided by the project administrators. By default all official game clients will connect to the list server to retrieve a list of publicly available [[BZFS|game servers]] as well as to authenticate [[Global Registration]] data.

==Technology==

The list server is written in php and runs on top of an apache web server. It uses a pair of MYSQL databases to store data. The user portion of the database is shared with the PHPBB3 software that isused to run the BZFlag forums. The source code for the list server is licensed under the LGPL as part of the [[BZFlag Source|BZFlag Source Code]] under the 'db' project.

=== URL ===
Multiple URLs are provided for the list server. Some Internet Service Providers (ISPs) are known to cache web traffic on the default HTTP port (port 80). For users with such ISPs it may benefit them to use an alternate URL.

Valid URLs are;
* http://my.bzflag.org/db/
* http://my.bzflag.org:81/db/

==Global Registration==

The list server is the authentication point for the [[Global Registration]] system. The registration system lets users tie their user accounts from the [[BZFlag Forums]] to the playing account.

The list server is used to verify each users login credentials and provide a temporary token for the client to pass to the game server. The game server then verifies the token with the list server, and gets any authentication info it may need, such as user groups.

==Hosting==

Currently the list server runs on the same web server as the official [[BZFlag Forums|BZFlag bulletin boards]] in the United States.

=== Outages ===
The project administrators attempt to keep list server outages to a minimum, but the current list server implementation does not handle heavy traffic loads as well as it could. Discussion and design work has been done on ways to improve the list server, anyone who would like to help with this project should read the [[DevelopmentGoals#List_Server|Development Goals section]] on the list server, as well as discuss ideas with the development staff on IRC.

==Public Usage Policy==

The list server is subject to the BZFlag [[List Server Usage Policy]]. This policy states what the intended uses of the service are, as well as accepted behaviors of it's users are.

==See also==
[[Global Registration]]

[[List Server Usage Policy]]

[[BZFlag Forums]]

[[BZFS]]

[[Category:Public Services]]