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.
Plug-ins are compile dynamic link libraries, that are built for the same OS/RuntimeEnvironment as the BZFS server that hosts them. On Microsoft Windows they are built as DLL files. On Linux and other Unix-like systems they are built as .so files.
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.
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.
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/.
Third Party Plug-ins
A number of non-developers have created plug-ins for BZFS, and usually release them on the 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
- To save time type ctrl/c to stop the command when it says "Running autogen.sh, please wait..."
- 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 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;
|There is still documentation to be done here!! If you feel up to the task, please have a go at it. Specifically what needs to be added is:|
Describe the basics of plug-in development.