Difference between revisions of "Plug-ins"

From BZFlagWiki
Jump to: navigation, search
m (Overview: missed a d)
(Facts is facts.)
Line 1: Line 1:
 
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.  
 
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 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==
 
==Overview==
Line 87: Line 87:
 
==Plug-in Development==
 
==Plug-in Development==
 
{{DoDoc|Describe the basics of 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 it's lifespan.
  
  

Revision as of 02:11, 10 May 2011

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 Microsoft Windows they are built as DLL files. On Linux and other 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 developers. These plug-ins are located in the /plugins directory.

As of August 2009, SVN TRUNK( version 2.99) contains the following plug-ins:

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":

  1. In the plugins directory of the BZFlag source tree run the command ./newplugin.sh Example
  2. Remove all of the files from the newly created plugins/Example directory (they were created by newplugin.sh)
  3. Copy all of the distributed Example files into the plugins/Example directory
  4. In the top-level BZFlag source directory, edit configure.ac, and add plugins/Example/Makefile to the list of AC_CONFIG_FILES
  5. 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

Plywood hammer100x101.gif 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.


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 it's lifespan.