L'API

Dans cette page, un tutoriel sur tous les éléments fournis par l'API sera montré.

• Date de début du projet: samedi 27 avril 2019
• Nombre de modules gérés par l'API: 3
• Liste des modules gérés par l'API:
  • Langue
  • Commande
  • Inventaire

Sommaire:

• Initialisation
• Langue
• Commande
• Inventaire

Initialisation

Avant de parler des modules, nous allons voir comment créer et configurer un projet utilisant cette API.
Comme ce projet a été réalisé avec Maven, ce tutoriel l'utilisera comme gestionnaire de dépendances.

pom.xml

Après avoir créé votre projet sous Maven, il faut configurer ses dépendances.

1. Ouvrez le fichier "pom.xml"
2. Ajoutez dans la liste des repository celui de Spigot (https://hub.spigotmc.org/nexus/content/repositories/snapshots/) et celui de JitPack (https://jitpack.io)
3. Ajoutez la dépendance de Spigot et de l'API
4. Rechargez votre projet Maven. C'est tout !

Exemple de pom.xml

Langue

• Depuis: 1.0

La langue est une chose importante en communication. C'est pour cette raison que l'API possède un gestionnaire de langues facile à utiliser et à configurer.

Les langues

Liste des langues supportées:

• Anglais (en_US)
• Français (fr_FR)

Pour ajouter une langue, vous devez créer un dossier contenant les langues.

1. Créez un dossier "lang"
2. Créez un fichier dans le dossier lang dont le nom sera le nom de la langue suivit de ".lang". Example de fichier: fr_FR.lang
3. N'importe où dans votre plugin, appelez la méthode Froxy.register(File) avec comme paramètre le dossier lang (Exemple)

• Le format des fichiers de langues est "key : message". (Exemple)
• Vous pouvez créer des valeurs qui changeront au fil du programme en mettant "{}" (sans les doubles guillemets) dans le message (Exemple). Dans ce cas, le "{}" sera remplacé par une valeur lors de l'execution.
• L'API supporte les codes couleurs ! Vous devez juste entrer le code couleur (§ et pas &) (Exemple)

Pour utiliser une langue, c'est assez simple.

1. Importez de manière statique les méthodes Froxy.$ et Froxy.$_
2. Vous pouvez dès lors utiliser les méthodes $(String), $(String, String...), $(String, Languages), $(String, Languages, String...), $_(String, Language), $_(String, Language, String...).
   1. La méthode $(String) retourne le message traduit en la langue par défaut.
   2. La méthode $(String, String...) retourne le message traduit en la langue par défaut puis rajoutera les paramètres passés.
   3. La méthode $(String, Language) retourne le message traduit en la langue passée en paramètre. Si le message n'a pas été trouvé, cette méthode retournera le message traduit en la langue par défaut.
   4. La méthode $(String, Language, String...) retourne le message traduit en la langue passée en paramètre puis rajoutera les paramètres passés. Si le message n'a pas été trouvé, cette méthode retournera le message traduit en la langue par défaut puis rajoutera les paramètres passés.
   5. La méthode $_(String, Language) retourne le message traduit en la langue passée en paramètre.
   6. La méthode $_(String, Language, String...) retourne le message traduit en la langue passée en paramètre puis rajoutera les paramètres passés.
   7. (Exemple)

Commande

• Depuis: 1.0

Une manière plus simple de créer et d'utiliser les commandes par rapport à Spigot.

1. Votre classe de commande devra implémenter l'interface "Command".
   1. (Exemple)
   2. La méthode getCommand() doit retourner la commande principale. Dans l'exemple, c'est hello (/hello)
   3. La méthode getAliases() doit retourner une liste d'alias, ou null s'il n'y en a pas.
   4. La méthode getPermission() doit retourner la permission requise par le joueur pour pouvoir executer la commande. Peut être null. Si le joueur n'a pas la permission, la méthode noPermission(player) est appelée.
   5. La méthode execute(String, Player, String[]) correspond à l'execution de la commande. Le 1er argument est la commande entrée, le 2ème est le joueur et le 3eme correspond aux arguments entrés. Dans l'exemple, si on entre /hello ou /hi, la commande nous affiche world.
2. Seul les commandes entrées par les joueurs fonctionnent. Pour executer une commande via un command block ou depuis la console, il faudra passer par Spigot.
3. Pour enregistrer la commande, il faut appeler la méthode Froxy.registerCommand(Command) (Exemple)

Inventaire

• Depuis: 1.0

Une manière plus simple de créer et d'utiliser les inventaires par rapport à Spigot. La gestion des inventaires est un peu spéciale. En effet, une interface spéciale est requise pour la création et la modification d'un inventaire

1. Votre classe d'inventaire devra implémenter l'interface "InventoryProvider".
   1. (Exemple)
   2. La méthode title(Inventory) doit retourner le titre de l'inventaire. Ici, "Home ~ 0ddlyoko" si le joueur 0ddlyoko ouvre l'inventaire.
   3. La méthode rows(Inventory) doit retourner le nombre de ligne de l'inventaire. Ici, 6.
   4. La méthode init(Inventory) correspond à l'initialisation de l'inventaire. Cette méthode servira à initialiser les items dans le but d'avoir un inventaire de base.
   5. La méthode update(Inventory) correspond à la mise à jour de l'inventaire. Cette méthode est automatiquement appelée tous les ticks.
2. Une fois fait, enregistrer cet inventaire dans une variable (Exemple)
3. Pour qu'un joueur puisse ouvrir cet inventaire, appelez la méthode Froxy.openInventory(InventoryProvider, Player); (Dans cet Exemple, l'inventaire est ouvert une fois que le joueur entre la commande /test ou /tests)
4. Pour fermer l'inventaire d'un joueur: player.closeInventory() ou Froxy.closeInventory(player)
5. Pour vérifier si un joueur a un inventaire d'ouvert: Froxy.hasInventoryOpened(player)
6. Pour récupérer l'inventaire du joueur: Froxy.getInventory(player) (utile pour vérifier si un joueur ferme son inventaire)

La classe Inventory

La méthode Froxy.openInventory(InventoryProvider, Player) retourne un objet de type Inventory. Il est conseillé de ne pas l'utiliser, sauf dans certains cas.

Il est conseillé d'utiliser cette classe dans la classe implémentant l'InventoryProvider:

• Pour récupérer le joueur correspondant: inv.getPlayer()
• Pour récupérer l'InventoryProvider: inv.getInventoryProvider()
• Pour récupérer le nombre de ligne de l'inventaire: inv.getRows()
• Pour mettre un item dans l'inventaire: inv.set(col, row, item) ou inv.set(pos, item)
  • Le col signifie le numéro de colonne où sera l'item. La 1ère colonne sera le numéro 1.
  • Le row signifie le numéro de ligne où sera l'item. La 1ère sera le numéro 1.
  • Le pos signifie la position de l'item dans l'inventaire. La 1ère case est la position 0, la dernière de la première ligne est la 8 et la 1ère case de la deuxième ligne est le 9.
• Pour remplir l'inventaire: inv.fill(item)
• Pour créer un rectangle: inv.rectangle(col, row, width, height, item) ou inv.rectangle(pos, width, height, item)
  • Le col signifie le numéro de colonne où sera l'item. La 1ère colonne sera le numéro 1.
  • Le row signifie le numéro de ligne où sera l'item. La 1ère sera le numéro 1.
  • Le pos signifie la position de l'item dans l'inventaire. La 1ère case est la position 0, la dernière de la première ligne est la 8 et la 1ère case de la deuxième ligne est le 9.
  • Le width est la largeur du rectangle
  • Le height est la hauteur du rectangle
• Pour créer un rectangle et remplir l'intérieur: inv.fillRectangle(col, row, width, height, item) ou inv.fillRectangle(pos, width, height, item)
  • Le col signifie le numéro de colonne où sera l'item. La 1ère colonne sera le numéro 1.
  • Le row signifie le numéro de ligne où sera l'item. La 1ère sera le numéro 1.
  • Le pos signifie la position de l'item dans l'inventaire. La 1ère case est la position 0, la dernière de la première ligne est la 8 et la 1ère case de la deuxième ligne est le 9.
  • Le width est la largeur du rectangle
  • Le height est la hauteur du rectangle
• Pour récupérer le tick actuel (Le nombre de tick depuis que l'inventaire est ouvert): Integer.parseInt(inv.get(Inventory.TICK).toString());
• Pour sauvegarder une donnée dans l'inventaire: inv.save(key, obj)
• Pour récupérer une donnée de l'inventaire: inv.get(key)