BukkitWiki

Welcome to the BukkitWiki!

This Wiki is home to Bukkit's documentation and regulations surrounding the Bukkit Project and it's services. Want to help out? We would love to have you! Signup to get started!

READ MORE

BukkitWiki
Register
Advertisement
Réécriture totale

Cette page est en train d'être entièrement refaite avec les informations à jour et les dernières fonctionnalités, et notamment avec des liens vers des tutos français et non anglais. La version définitive ne sera plus vraiment sur la base de l'article anglais. MERCI DE NE PAS REMETTRE CE QU'IL Y AVAIT AVANT.

TODOIcon
Travail en cours...

Cette page est toujours en cours de rédaction. Revenez bientôt pour voir du contenu supplémentaire


Apprendre à programmer en Java

Avant de commencer à créer des plugins bukkit, il est nécessaire d'avoir suffisamment de connaissances en programmation en général, et plus particulièrement en Java. Si les mots IDE, JDK, fonction, variable, main, classe, jar, package, etc… vous sont inconnus, ou si vous avez encore du mal avec le langage Java, voici quelques pistes :

Il y a aussi la solution des tutoriaux en vidéo. Privilégiez tout de même les tutoriaux écris.

Si vous souhaitez vraiment devenir développeur, suivez bien le tutoriel du site du zéro, en prenant bien le temps de comprendre chaque notion. Cela vous aidera énormément pour la suite.

Outils du développeur

Java

Vous aurez bien sûr besoin de Java, c'est-à-dire d'un JRE (Java Runtime Environment ou "Environnement d'Exécution Java" c'est ce qu'on appelle communément "Java" et qui permet d'utiliser des programmes Java compilés, comme par exemple Minecraft) ou d'un JDK (Java Development Kit, des outils qui permettent de créer des programmes Java et de les déboguer. Contient le JRE). Il est préférable d'utiliser le JDK pour programmer, même si certains IDE comme Eclipse peuvent s'en passer, d'autres l'utilisent.

=> Télécharger le dernier JRE ou JDK

Un IDE

Un IDE, Integrated Development Environment (ou "Environnement de Développement Intégré"), est un outil qui va permettre d'écrire le code du programme, de le compiler pour en faire un fichier utilisable par l'ordinateur, et de le déboguer, c'est-à-dire de trouver où se trouvent les bogues (ou "bugs" en anglais) pour les corriger rapidement. Le tout-en-un du développeur.

Il existe différents IDE. Voici les principaux qu'on observe dans l'environnement Bukkit, ceux que l'on peut croiser :

  • Eclipse - Gratuit, le plus utilisé
  • NetBeans - Gratuit, aussi très utilisé
  • IntelliJ Idea - Payant, objectivement le meilleur IDE. Sa version gratuite est un peu moins complète qu'Eclipse ou NetBeans.

Si vous êtes débutant "total", choisissez Eclipse. Il est le plus utilisé, et donc le plus représenté dans les tutoriels, comme celui-ci !

=> Téléchargez la dernière version d'Eclipse IDE

Sur cette page, vous trouverez toutes les dernières versions d'Eclipse. Pour développer en Java, vous pouvez utiliser Eclipse IDE for Java Developers ou Eclipse Standard. Si vous avez un ordinateur 64 bits, prenez la version 64 bits. Eclipse, tout comme NetBeans, est plutôt lourd, autant utiliser une version plus rapide si vous le pouvez.

Lightbulb Note: Si vous avez un vieux Mac à processeur PowerPC, vous devrez télécharger une version plus ancienne d'Eclipse telle que Indigo ou Juno

L'API bukkit

Le système de plugins des serveurs CraftBukkit utilise une API (Application Programming Interface ou "Interface de Programmation Applicative") nommée Bukkit. Lorsque vous créez un plugin pour les serveurs utilisant CraftBukkit, vous utilisez des classes, interfaces et méthodes de l'API Bukkit. Si vous lisez ceci, vous êtes censé connaître Java et la programmation, vous comprendrez donc cette phrase : on dit que CraftBukkit implémente Bukkit. Pour pouvoir utiliser tout cela dans votre projet Eclipse, il faut spécifier que le projet utilisera l'API Bukkit.

L'API bukkit se présente sous la forme d'un fichier JAR non éxécutable. téléchargeable ici: => Télécharger l'API Bukkit

Warning Warning: Vous ne devez JAMAIS utiliser CraftBukkit à la place de Bukkit lorsque vous développez. Vous seriez tenté d'utiliser des classes, interfaces et méthodes de CraftBukkit qui ne font pas partie de l'API. Au final, vous aurez un "plugin-mod" qui devra être recompilé pour chaque mise à jour du projet Bukkit.
Lightbulb Note: Vous trouverez tout de même des plugins plutôt importants qui utilisent CraftBukkit pour étendre l'API Bukkit (Ex: TagAPI, ProtocolLib), ou pour des raisons de performances (Ex: WorldEdit).

Un serveur CraftBukkit

Si vous voulez tester votre plugin, il vous faudra un serveur Minecraft CraftBukkit fonctionnel. Vous DEVEZ tester votre plugin avant de le publier.

=> Voir wiki.bukkit.org/Setting_up_a_server/fr

Création du projet

Maintenant que vous avez tout ce qu'il faut, vous pouvez commencer la partie intéressante : le développement du plugin lui-même. Pour commencer, vous allez créer un nouveau projet dans Eclipse que vous appellerez comme votre plugin :

Nouveau projet

Utiliser l'API bukkit

Je vous avais dit plus haut que, pour pouvoir utiliser l'API Bukkit afin de créer votre plugin, il fallait le spécifier à Eclipse. Pour cela, allez dans les propriétés de votre projet (clic droit sur votre projet > Properties) :


Properties


Properties fenetre

Dans cette fenêtre, cliquez sur le bouton Add external jar et sélectionnez le bukkit.jar que vous avez téléchargé.

Ensuite, cliquez sur la petite flèche à gauche de "bukkit.jar" pour dérouler un menu :

Properties - javadoc location 1


Double-cliquez sur JavaDoc Location afin de faire apparaître cette fenêtre :

Properties - set javadoc


Dans le premier cadre "JavaDoc Location Path", entrez ceci: http://jd.bukkit.org/apidocs


Puis cliquez sur "Ok" et encore sur "Ok" dans la fenêtre des propriétés ("Properties").

La classe principale

Tous les plugins disposent d'une classe principale. Cette classe sera utilisée au démarrage du plugin et vous permet donc de lancer certaines actions.

Création

Créez tout d'abord un nouveau paquet ("package") dans votre projet en cliquant sur le bouton Nouveau paquet qui se trouve en haut de la fenêtre d'Eclipse, dans cette barre de menus:

Barre de menu

Vous devez suivre certaines conventions lors du choix du nom de votre package :

  • Si vous possédez un nom de domaine, le nom du package doit commencer par ce nom de domaine à l'envers.
    • Exemple : mondomaine.fr => Votre package sera préfixé par fr.mondomaine (source)
    • N'utilisez surtout pas de domaine que vous ne possédez pas.
  • Si vous ne possédez pas de nom de domaine, il y a plusieurs alternatives possibles :
    1. Créez un compte sur un site de gestion de sources comme GitHub ou SourceForge
      • Pour GitHub, suivez ces instructions et vous aurez un sous-domaine, donc votre package serait préfixé par com.github.<votrePseudo>
    2. Utilisez votre addresse mail. Exemple : <votrePseudo>@gmail.com donne com.gmail.<votrePseudo>
    3. Et voici la méthode déconseillée, si vous n'avez ni nom de domaine, ni l'envie de faire un compte GitHub, ni même d'addresse mail (!) : utilisez ce que vous voulez, tant que ce n'est pas un nom déjà utilisé. On pourra conseiller me.<votrePseudo>.

Voici ce par quoi votre nom de package ne doit absolument pas commencer :

  • org.bukkit
  • net.bukkit
  • com.bukkit
  • net.minecraft

Maintenant que vous avez un "préfix" de package, vous pouvez lui ajouter le nom de votre plugin. Par exemple, sk89q, l'auteur de WorldEdit, possède le nom de domain sk89q.com. Le nom du package contenant l'ensemble du cote de WorldEdit est com.sk89q.worldedit.

Lightbulb Note: Il est très important que votre nom de package ne contienne aucune lettre majuscule.



Ensuite, créez une nouvelle Classe dans ce package en cliquant sur le bouton Nouvelle classe qui se trouve également dans la barre de menus.

Généralement, on appelle la classe principale du plugin par le nom du plugin.

JavaPlugin

Cette classe principale doit hériter de la classe JavaPlugin de l'API Bukkit afin d'être vraiment considérée comme la classe principale d'un plugin par le serveur CraftBukkit.

Vous pouvez donc modifier

public class Plugin {
}

en

public class Plugin extends JavaPlugin {
}

Eclipse, comme tout IDE, devrait vous proposer d'importer org.bukkit.plugin.java.JavaPlugin. Vous devriez donc avoir ceci en haut de votre classe.

import org.bukkit.plugin.java.JavaPlugin;

La méthode onEnable()

La classe JavaPlugin possède une méthode onEnable() qui est appellée à chaque lancement du plugin. Afin de pouvoir effectuer vos propre actions au démarrage du plugin, vous devez redéfinir la méthode onEnable() dans la classe principale de votre plugin:

public class Plugin extends JavaPlugin {
    @Override
    public void onEnable(){
        // Actions à effectuer au démarrage du plugin, c'est-à-dire :
        //   - Au démarrage du serveur
        //   - Après un /reload
    }

}

La méthode onDisable()

La classe JavaPlugin possède aussi une méthode onDisable() qui, vous l'avez sûrement deviné, est appellée à chaque fois que le plugin est désactivé. Comme pour onEnable(), vous devez redéfinir la méthode onDisable() dans la classe principale de votre plugin:

public class Plugin extends JavaPlugin {
    @Override
    public void onDisable(){
        // Actions à effectuer à la désactivation du plugin
        //   - A l'extinction du serveur
        //   - Pendant un /reload
    }

}
Lightbulb Note: Pour faire simple, la commande /reload appelle les méthodes onDisable() de chacun des plugins actifs, puis les méthodes onEnable().

Le fichier plugin.yml

Lorsque CraftBukkit démarre, il va regarder à l'intérieur de tous les fichiers JAR dans le dossier /plugins et y chercher un fichier plugin.yml. Ce fichier plugin.yml contient des informations sur le plugin, telles que:

  • Le nom du plugin
  • La version du plugin
  • Le chemin de la classe principale
  • Les commandes du plugin
  • Les permissions du plugin
  • Le nom de l'auteur du plugin
  • Le site de l'auteur du plugin
  • etc...


=> Voir Référence plugin.yml

Création

Faites un clic droit sur votre projet > New > File
Nouveau fichier

Appelez le fichier plugin.yml et mettez-y ceci :

name: <nomDuPlugin>
main: <votrePackage>.<VotreClassePrincipale>
version: <versionDuPlugin>
description: <Description du plugin>
author: <votreNom>
Warning Warning: Les 3 premières informations sont cruciales. Sans elles, CraftBukkit refusera de lancer le plugin.


Voici un exemple, le début du plugin.yml de WorldEdit 5.5.7:

name: WorldEdit
main: com.sk89q.worldedit.bukkit.WorldEditPlugin
version: 5.5.7

Les commandes

Il est conseillé de mettre les commandes de votre plugin dans le fichier plugin.yml. Pour cela, ajoutez-y un tag "commands":

commands:
  exemple:
    description: Description de la commande.
    usage: /exemple [parametre1] [parametre2]
    permission: permission.exemple
    aliases:
    - ex
    - e
  • exemple: le nom de la commande
  • usage: (uniquement à tire d'information)comment votre commande doit être exécutée, avec quels paramètres
  • permission: (uniquement à titre d'information)la permission requise pour effectuer cette commande
  • aliases: la liste des "alias" de la commande. Au lieu de taper le nom complet de la commande pour l'utiliser, vous pouvez taper le nom d'un des alias.

Les permissions

Il est conseillé d'ajouter les permissions que votre plugin utilise dans le fichier plugin.yml. Pour cela, ajoutez-y un tag "permissions":

permissions:
  plugin.exemple:
    description: permet d'utiliser la commande exemple
    default: op
  • plugin.exemple: le nom de la permission
  • description: description de la commande
  • default: qui par défaut a cette permission. 4 valeurs sont possibles:
    • true: par défaut, tout le monde a cette permission
    • false: par défaut, personne n'a cette permission
    • op: par défaut, seuls les admins (OP) du serveur ont cette permission
    • not op: par défaut, seuls ceux qui ne sont PAS admins du serveur ont cette permission



Il est possible de définir des permissions "parents" et "enfants" avec le tag children:

permissions:
  plugin.*:
    description: donne acces a toutes les permissions enfants
    children:
      plugin.exemple: true   
  plugin.exemple:
    description: permet d'utiliser la commande exemple
    default: op
  • plugin.*: nom de la permission parent. Généralement on utilise le signe * pour remplacer la/les dernière(s) partie(s) de la permission parent, selon ce qui change chez les enfants.
  • children: en dessous on va mettre toutes les permissions enfants.
    • plugin.exemple: nom de la permission enfant. 2 valeurs sont possibles:
      • true: Si on donne à un joueur la permission parent, il aura cette permission enfant selon ce qui est précisé pour celle-ci ("true", "false", "op" ou "not op")
      • false: Si on donne à un joueur la permission parent, il aura cette permission enfant selon l'inverse de ce qui est précisé pour celle-ci.

Les fichiers de configuration

L'api bukkit met à disposition des outils pour gérer facilement des fichiers de configuration. Le fichier de configuration principal d'un plugin se trouve toujours ici: dossier du serveur/plugins/NomDuPlugin/config.yml.

Le fichier config.yml par défaut

Il est conseillé d'avoir un fichier config.yml par défaut dans le .jar du plugin. Cela servira notamment à créer le fichier de configuration principal s'il n'existe pas.
Pour créer ce fichier, faites un clic droit sur votre projet > New > File et appelez-le "config.yml". Dans ce fichier vous pouvez mettre:

  • De simples valeurs:
nom: valeur
  • Des listes:
nom:
  - élément 1
  - élément 2
  • Des groupes de valeurs, avec des parents et des enfants:
parent:
  enfant1: valeur
  enfant2:
    sousEnfant:
      - élément
  • Des commentaires: en ajoutant le signe # en début de ligne


Afin de sauvegarder cette configuration par défaut dans dossier du serveur/plugins/NomDuPlugin/config.yml lorsque ce dernier n'existe pas, utilisez la méthode JavaPlugin.saveDefaultConfig(). Exemple au chargement du plugin:

@Overrride
public void onEnable() {
    this.saveDefaultConfig();
}

</bloquote>

Accéder un fichier de configuration

Afin d'accéder, d'écrire ou de lire des fichiers de configuration, on utilise l'objet FileConfiguration de l'api bukkit. Il y'a plusieurs façons de récupérer une instance de FileConfiguration:

  • Si vous voulez accéder à dossier du serveur/plugins/NomDuPlugin/config.yml, utilisez la méthode JavaPlugin.getConfig()
  • Si vous voulez accéder au fichier de configuration par défaut stocké dans le .jar du plugin, utilisez JavaPlugin.getConfig().getDefault()
  • Pour tout autre fichier de configuration, faites comme ceci:
File configFile = new File("plugin/NomDuPlugin/monFichierConfig.yml");
FileConfiguration config = YamlConfiguration.loadConfiguration(configFile);


Vous devez aussi savoir qu'une valeur dans un fichier de configuration est identifiée grâce à son chemin, qui est construit de la façon suivante: parent.enfant.sousEnfant.nomDeLaValeur

Lire des valeurs

Les méthodes getXXX() de la classe FileConfiguration permettent de récupérer une valeur de type XXX. Voici les méthodes les plus utilisées:

Advertisement