Plugins

BZFS peut être construit pour prendre en charge le chargement de bibliothèques externes sous forme de plug-ins. Ces plug-ins peuvent modifier ou remplacer la logique appliquée par le serveur, ainsi qu'automatiser de nombreuses tâches courantes.

Les plug-ins sont l’un des moyens les plus populaires d’appliquer des modifications au jeu. Ils ne nécessitent pas de modifications du code source de l'application BZFS, ce qui permet de le maintenir à jour sans qu'il soit nécessaire d'appliquer constamment des correctifs. Ils se sont également révélés être une méthode très simple pour distribuer les modifications des développeurs aux joueurs.

## Contenu

* 1. Vue d'ensemble
* 2 Utilisation
	+ 2.1 Paramètres
	+ 2.2 Chemins de recherche
* 3API BZFS
* 4 plug-ins standards
* 5 plug-ins tiers
	+ 5.1 Sous Linux
		- 5.1.1 Pour les versions antérieures à 2.4.3
		- 5.1.2 Pour les versions 2.4.3 ou ultérieures
	+ 5.2 Sous Mac OS X
* 6 Préparation d'un BZFS Linux
* 7 Développement de plug-ins
* 8 Histoire

## Aperçu

Les plug-ins sont des bibliothèques de liens dynamiques compilées, conçues pour le même système d'exploitation/environnement d'exécution que le serveur BZFS qui les héberge. Sous Microsoft Windows, ils sont créés sous forme de fichiers DLL . Sous Linux et d'autres systèmes de type Unix , ils sont construits sous forme de fichiers .so.

## Utiliser

Les plug-ins sont chargés au démarrage par l' **option -loadplugin** ou au moment de l'exécution avec la *commande /loadplugin* . Si le chemin complet du plug-in n'est pas spécifié, BZFS recherchera le plug-in dans un certain nombre de sous-répertoires connus lors de sa tentative de chargement. L’utilisation d’un chemin valide vers le plug-in lors du chargement est fortement recommandée. Pendant la lecture, tous les plug-ins chargés sur le serveur sont visibles avec la commande /listplugins.

### Paramètres

Certains plug-ins acceptent des paramètres qui sont transmis au plug-in lors du chargement. Il s'agit souvent d'une valeur numérique ou d'un chemin d'accès à un fichier. Pour transmettre un paramètre à un plug-in, ajoutez simplement un ',' après le nom ou le chemin du plug-in, puis ajoutez le paramètre. Les paramètres ne peuvent pas contenir d'espaces, en raison de la façon dont BZFS analyse les options de ligne de commande et les commandes /.

Au chargement, les plug-ins installent un certain nombre de rappels et de gestionnaires d'événements avec le BZFS d'hébergement qui sont appelés lorsque des événements spécifiques se produisent. Cela permet au plug-in d'effectuer des actions supplémentaires sur ces événements, ou si besoin, de modifier les résultats de la logique par défaut du serveur.

### Chemins de recherche

BZFS recherche les plug-ins dans deux emplacements standard : le répertoire de configuration et le répertoire global des plug-ins. Le répertoire de configuration est l'endroit où se trouve le fichier config.cfg de BZFlag et le répertoire global des plug-ins est $(prefix)/lib/bzflag/.

## API BZFS

Tous les plug-ins sont liés à l' API BZFS . Cette couche de programmation fournit l'interface avec l'application BZFS. Tous les événements et fonctions qu'un plug-in peut appeler se trouvent dans l' API BZFS .

## Plugins standards

La distribution BZFlag Source contient un certain nombre de plug-ins gérés par les développeurs du projet . Ces plug-ins se trouvent dans le *répertoire /plugins* .

Depuis février 2016, l'arborescence Git contient les plug-ins suivants :

## Plugins tiers

Un certain nombre de non-développeurs ont créé des plug-ins pour BZFS et les publient généralement sur les forums BZFlag .

### Sous Linux

Voici les étapes pour compiler un hypothétique plug-in tiers nommé « Exemple » :

#### Pour les versions antérieures à 2.4.3

1. Dans le répertoire plugins de l'arborescence des sources de BZFlag exécutez la commande **./newplug.sh Exemple**
2. Supprimez tous les fichiers du répertoire plugins/Example nouvellement créé (ils ont été créés par newplug.sh)
3. Copiez tous les fichiers d'exemple distribués dans le répertoire plugins/Example
4. Dans le répertoire source BZFlag de niveau supérieur, exécutez **autogen.sh** , **configure** et **make** comme d'habitude

#### Pour les versions 2.4.3 ou ultérieures

1. Stockez les fichiers de plugin distribués dans le *plugins/ Example* répertoire
2. Dans le répertoire source BZFlag de niveau supérieur, exécutez :

```
./autogen.sh
  ./configure --enable-custom-plugins=  *Exemple*
  ./faire

```

Notez que vous pouvez utiliser une liste séparée par des virgules pour spécifier plusieurs plugins à créer :

```
./configure --enable-custom-plugins=  *Exemple*  ,  *AutreExemple*  ,  *AutrePlugin*

```

Une fois cette opération terminée, le plug-in devrait être prêt à être utilisé comme décrit ci-dessus.

### Sur Mac OS X

Dans Xcode sur Mac OS X, suivez ces instructions :

1. Créez une nouvelle cible pour votre plug-in.
	* **Xcode 5 (et inférieur)**  : Cliquez sur le nom du projet BZFlag dans le navigateur de projet. Cliquez sur Ajouter une cible et créez une nouvelle bibliothèque C/C++. Nommez le plugin et sélectionnez « Dynamique » pour le type.
	* **Xcode 6**  : Cliquez sur le projet BZFlag dans le navigateur de projet. Allez dans Fichier > Nouveau > Cible. Lorsque vous êtes invité à indiquer le modèle de la cible, sous la section « OS X », sélectionnez la section « Framework & Library » et enfin sélectionnez « Bibliothèque ». Dans la boîte de dialogue suivante, sélectionnez « Aucun (Bibliothèque Plain C/C++) » pour le Framework et « Dynamique » pour le type.
2. Dans le navigateur de projet, déplacez la nouvelle cible de bibliothèque du bas de l'écran vers le groupe "Cibles".
3. Cliquez à nouveau sur le nom du projet BZFlag dans le navigateur de projet. Dans la liste des cibles, sélectionnez la cible de l'application BZFlag. Dans l'onglet Phases de construction, dans le volet Dépendances cibles, ajoutez votre nouvelle cible de bibliothèque en tant que dépendance de la cible de l'application. Ajoutez-le également à la phase Copier les fichiers pour le répertoire PlugIns.
4. Sélectionnez votre nouvelle cible de bibliothèque. Sélectionnez l’onglet Paramètres de construction et localisez l’option Autres indicateurs de l’éditeur de liens. Ajoutez l'option "-undefineddynamic\_lookup"
5. Recherchez le paramètre de construction d'architecture pour votre nouvelle bibliothèque. Assurez-vous qu'il s'agit de la même architecture que la base de code principale, ou cliquez sur Niveaux, cliquez sur le paramètre Architecture sous la cible de votre bibliothèque, cliquez sur Autre et supprimez le paramètre. Cela lui fera assumer l’architecture globale de construction du projet.
6. Si votre plug-in utilise « plugin\_utils.h », assurez-vous que sous Phases de construction, la **bibliothèque libplugin\_utils.a** est répertoriée sous « Lier le binaire aux bibliothèques » ; ajoutez la bibliothèque si elle n'est pas déjà répertoriée.
7. Recherchez le paramètre de construction Executable Prefix pour votre nouvelle bibliothèque et supprimez le paramètre "lib".
8. Ajoutez votre (vos) fichier(s) source au projet et faites-en des membres de votre bibliothèque cible ; assurez-vous de cocher la case « Copier les éléments si nécessaire » et de choisir « Créer des groupes ».
9. Construisez comme d'habitude.

## Préparer un BZFS Linux

Afin d'exécuter des plugins dans BZFS, vous devez le recompiler avec l'option --enable-shared sur le script de configuration.

*Notez qu'à partir de la version 2.4.0, la configuration de BZFlag a automatiquement activé --enable-shared.*

```
$ ./configure --enable-shared --disable-client ;
       faire;
       faire l'installation ;

```

## Histoire

Le système de plug-in a été ajouté dans BZFlag V. 2.0.4 et a initialement rencontré un accueil mitigé de la part de certains des principaux développeurs et du responsable. La communauté a depuis adopté le concept et construit une multitude de modifications utiles, dont beaucoup ont été intégrées au projet sous forme de plug-ins standard.

Pour la version 3.0, des modifications majeures à l' API BZFS ont été apportées pour augmenter sa durée de vie.