Construction d’une commande

La première étape est d’obtenir un nouveau constructeur CommandSpec. Le constructeur fournit des méthodes permettant de modifier les messages d’aides de la commande, les différents arguments de la commande et la commande en elle-même. Ces méthodes peuvent être enchaînées.

Pour finalement construire sa commande, il faudra appeler la méthode CommandSpec.Builder#build().

Après cela, vous devez enregistrer la commande.

Exemple: Construction d’une Commande Simple

import org.spongepowered.api.Sponge;
import org.spongepowered.api.text.Text;
import org.spongepowered.api.command.spec.CommandSpec;

CommandSpec myCommandSpec = CommandSpec.builder()
    .description(Text.of("Hello World Command"))
    .permission("myplugin.command.helloworld")
    .executor(new HelloWorldCommand())
    .build();

Sponge.getCommandManager().register(plugin, myCommandSpec, "helloworld", "hello", "test");

Vue d’ensemble des méthodes du constructeur CommandSpec

Méthode	Description
`executor`	Définit l’exécution de la commande. (Voir Écrire l’Exécution de la Commande). Définir l’objectif de la commande est impératif si la commande n’a pas de sous–commandes définies.
`arguments`	Définit la spécification de l’argument pour cette commande (voir Analyse des Arguments).
`permission`	Définit la permission qui est requise afin d’utiliser la commande.
`description`	Une description peu complète d’une seule ligne sur l’utilité de la commande, elle est affichée lorsque le joueur utilise le système d’aide.
`extendedDescription`	Définit une description plus complète qui est affichée dans la liste d’aide. Elle sera ajoutée à la description moins complète.
`child`	Ajoute une commande subsidiaire à cette commande avec un alias (voir Sous-Commandes).
`children`	Définit les commandes subsidiaires de cette commandes avec leurs alias (voir Sous-Commandes).
`inputTokenizer`	Définit comment les arguments vont être décomposés. Par défaut, ils sont séparés par des espaces. Les guillemets comptent comme un seul argument. Exemple: `/tpworld Notch "My World"` est composée de 2 arguments `Notch` et `My World`.
`build`	Construit la commande. Après cela, vous devrez l’enregistrer.

Écrire l’Éxécution de la Commande

La seule chose requise pour construire une commande simple est la classe de l’exécution de la commande, qui contient la logique de la commande.

La classe doit implémenter l’interface CommandExecutor, qui définit la méthode CommandExecutor#execute(CommandSource, CommandContext). La méthode est appelée pendant l’exécution de la commande et possède deux arguments:

La source qui exécute la commande. (ex: la console, un bloc de commande ou bien un joueur)
L’objet du contexte de la commande, qui contient l’analyse des arguments (voir Analyse des Arguments)

Exemple: Un Simple Exécuteur de Commande

import org.spongepowered.api.command.CommandException;
import org.spongepowered.api.command.CommandResult;
import org.spongepowered.api.command.CommandSource;
import org.spongepowered.api.command.args.CommandContext;
import org.spongepowered.api.command.spec.CommandExecutor;

public class HelloWorldCommand implements CommandExecutor {

    @Override
    public CommandResult execute(CommandSource src, CommandContext args) throws CommandException {
        src.sendMessage(Text.of("Hello World!"));
        return CommandResult.success();
    }
}

Astuce

Vous pouvez utiliser des classes anonymes pour définir l’exécuteur de la commande dans le processus de construction des commandes (voir la page Analyse des Arguments).

Commandes utilisables par les Joueurs Seulement

Parfois il est nécessaire que seulement le joueur puisse exécuter une commande (ex: la commande /suicide).

Effectuer une vérification à l’aide de instanceof permet de déterminer le type de CommandSource:

import org.spongepowered.api.entity.living.player.Player;
import org.spongepowered.api.command.source.CommandBlockSource;
import org.spongepowered.api.command.source.ConsoleSource;

if(src instanceof Player) {
    Player player = (Player) src;
    player.sendMessage(Text.of("Hello " + player.getName() + "!"));
}
else if(src instanceof ConsoleSource) {
    src.sendMessage(Text.of("Hello GLaDOS!"));
    // The Cake Is a Lie
}
else if(src instanceof CommandBlockSource) {
    src.sendMessage(Text.of("Hello Companion Cube!"));
    // <3
}

Note

Il est recommandé d’ajouter un argument facultatif [player] afin de rendre la commande utilisable par la console (ex /suicide [player]).

La solution la plus simple pour ça est d’ajouter playerOrSource à l’élément de la commande (voir Analyse des Arguments).

Résultats de la Commande

La méthode CommandExecutor::execute() doit toujours retourner un CommandResult. Dans la plupart des cas, il suffit juste de retourner CommandResult#success() si la commande a été exécutée avec succès ou CommandResult#empty() si ce n’est pas le cas. Dans les cas où plusieurs d’informations doivent être déplacées, un CommandResult#builder() peut se révéler utile. Il fournit les méthodes affectedBlocks(), affectedEntities(), affectedItems(), queryResult() et successCount(), chacune acceptant un entier et affectant l’attribut de même nom. Tous les attributs qui ne sont pas définis pas le constructeur seront vides.

Les command blocks peuvent utiliser ces valeurs pour modifier les stats de scoreboard, ce qui peut être utilisé pour élaborer des constructions constituées de multiples command blocks. Un tutoriel sur la manière d’accéder aux données peut être trouvée ici.

Exemple: Faire un CommandResult

CommandResult result = CommandResult.builder()
    .affectedEntities(42)
    .successCount(1)
    .build();

Cet exemple utilise un constructeur pour créer un CommandResult pour une commande qui affecte 42 entités et a été un succès.

Gestion des erreurs

La méthode execute() peut également lever une CommandException, signalant qu’une erreur est survenue lors de l’exécution de la commande. Si cette Exception est levée, son message sera affiché dans la source de la commande, formatée comme une erreur. L’usage de la commande peut être aussi affiché. Un ArgumentParseException, un sous-type de CommandException est automatiquement levé si les arguments de la commande ne peuvent pas être analysés.