Compilación de un Comando

El primer paso es obtener un nuevo compilador CommandSpec. El compilador proporciona métodos para modificar los mensajes de ayuda del comando, los argumentos del comando y la lógica del comando. Estos métodos pueden estar encadenados.

Para finalmente compilar el comando, querrá llamar al método CommandSpec.Builder#build() .

Después de eso, debe registrar el comando.

Ejemplo: Compilación de un Comando 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");

Resumen de los métodos de compilación CommandSpec

Método	Descripción
`ejecutor`	Define la lógica del comando (Vea Escribir un Ejecutor de Comando). Se requiere ejecutar el ejecutor si no hay comandos secundarios configurados.
`argumentos`	Establece la especificación del argumento para este comando (Ver argumentos).
`permiso`	Establece el permiso que será verificado antes de utilizar este comando.
`descripción`	Una breve descripción de una línea del propósito de este comando que se mostrará en el sistema de ayuda.
`extendedDescription`	Establece una descripción extendida para utilizar en listados de ayuda más largos. Será anexado a la descripción breve.
`secundario`	Agrega un comando secundario para este comando con sus alias (Ver Comandos Hijos).
`secundarios`	Establece los comandos secundarios de este comando con sus alias (Ver Comandos Hijos).
`inputTokenizer`	Define como los argumentos serán analizados. Por defecto, el analizador divide el comando ingresado por espacios. Las citas cuentan como un solo argumento. Ejemplo: `/tpworld Notch "My World"` resultaría en dos argumentos: `Notch` y `My World`.
`compilar`	Compila el comando. Después de eso, debe registrar el comando.

Escribir un Ejecutor de Comando

El único componente requerido para compilar un comando simple es la clase del ejecutor de comando, que contiene la lógica del comando.

La clase debe implementar la interfaz CommandExecutor, que define el método CommandExecutor#execute(CommandSource, CommandContext). El método es llamado en la ejecución de comando y tiene dos argumentos:

El origen de la llamada del comando (ej. la consola, un bloque de comando o un jugador)
El objeto de contexto de comando, que contiene los argumentos analizados (Ver argumentos)

Ejemplo: Ejecutor de Comando Simple

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();
    }
}

Truco

Puede utilizar clases anónimas para definir el ejecutor de comando en el proceso de compilación de comando (Vea en ejemplo en la página argumentos).

Comandos Solo de Jugador

A veces es necesarios que solamente los jugadores puedan ejecutar un comando (ej. un comando /suicidio).

Realice una verificación instanceof para determinar el tipo del 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
}

Nota

Le recomendamos agregar un argumento [player] opcional para hacer que el comando sea compatible con la consola (ej. /suicidio [player]).

La solución más sencilla para esto es anexar un elemento de comando playerOrSource (ver argumentos).

Resultados de Comando

El método CommandExecutor#execute() siempre debe devolver un CommandResult. En muchos casos es suficiente devolver CommandResult#success() si el comando fue exitoso o si no lo fue CommandResult#empty(). En casos donde se necesita transmitir más información, un CommandResult#builder() puede ser utilizado. El compilador proporciona varios métodos diferentes que aceptan un número entero y establecerá el atributo con el mismo nombre. Todos los atributos que no son establecidos por el compilador estarán vacíos.

Bloques de comando pueden utilizar valores para modificar las estadísticas del marcador, que luego pueden ser usadas para compilaciones elaboradas que consisten en múltiples bloques de comando. Un tutorial sobre como se accede a los datos puede encontrarse aquí.

Ejemplo: Construcción de un CommandResult

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

Este ejemplo utiliza un compilador para crear un CommandResult para un comando que afectó 42 entidades y fue exitoso.

Manejo de Errores

El método execute() también puede arrojar un CommandException, señalando que un error ocurrió mientras trataba de ejecutar el comando. Si se produce una Excepción, su mensaje será mostrado en el origen del comando, formateado como un error. Además, se mostrará el mensaje de uso de comandos. Un ArgumentParseException, un subtipo de CommandException es automáticamente arrojado si los argumentos del comando no se pudieron analizar.