Einen Befehl erstellen
Der erste Schritt ist einen neuen CommandSpec-Builder zu holen. Er stellt Methoden zu Modifikation der Befehlshilfe, Argumente, und Logik bereit. Diese Methoden können beliebig miteinander verkettet werden.
Um schließlich den Befehl zu erstellen, musst du die CommandSpec.Builder#build() Methode aufrufen.
Danach kann der Befehl registriert werden.
Beispiel: Einen einfachen Befehl erstellen
import org.spongepowered.api.Sponge;
import org.spongepowered.api.text.Text;
import org.spongepowered.api.command.spec.CommandSpec;
PluginContainer plugin = ...;
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");
Überblick über die Methoden des CommansSpec-Builders
Methode |
Beschreibung |
---|---|
|
Definiert die Befehlslogik (siehe Einen CommandExecutor schreiben). Das Festlegen des Executors ist erforderlich, wenn keine Kinder-Befehle festgelegt sind. |
|
Legt die Argument-Spezifikation für diesen Befehl fest (siehe Paramenterverarbeitung). |
|
Legt die Berechtigung fest, die überprüft wird, bevor diese Kommando genutzt wird. |
|
Eine kurze, einzeilige Beschreibung des Zweckes dieses Befehls, der vom Hilfesystem angezeigt wird. |
|
Legt eine erweiterte Beschreibung fest, die in der längeren Hilfe genutzt wird. Wird an die kurze Beschreibung angehängt. |
|
Fügt die Kinder Befehle dieses Befehls mit ihren Aliasen hinzu (siehe Untergeordnete Befehle). |
|
Legt die Kinder Befehle dieses Befehls mit ihren Aliasen fest (siehe Untergeordnete Befehle). |
|
Definiert, wie die Argumente geparst werden sollen. Standardmäßig teilt der Parser die Befehlseingabe durch Leerzeichen. Zitate zählen als ein eigenes Argument. Beispiel: |
|
Erstellt den Befehl. Danach musst du den Befehl noch registrieren. |
Einen CommandExecutor schreiben
Die einzige benötigte Komponente, einen einfachen Befehl zu erstellen, ist die CommandExecutor
Klasse, welche die Logik des Befehls enthält.
Die Klasse muss das CommandExecutor Interface implementieren, welches die CommandExecutor#execute(CommandSource, CommandContext) Methode definiert. Die Methode wird beim Aufruf des Befehls aufgerufen und hat zwei Argumente:
Die Quelle des Befehlsaufrufes (z.B. die Konsole, ein Befehlsblock oder ein Spieler)
Den Befehlskontext, welche die ausgewerteten Argumente enthält (Siehe Paramenterverarbeitung)
Beispiel: Ein einfacher CommandExecutor
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();
}
}
Tipp
Du kannst anonyme Klassen verwenden, um den CommandExecutor
im Befehlserstellungsprozess zu definieren (Siehe auch das Beispiel auf der Paramenterverarbeitung Seite).
Befehle nur für Spieler
Sometimes it is necessary that only players can execute a command (e.g. a /suicide
command).
Führe eine instanceof
Überprüfung durch, um den Typ der CommandSource herauszufinden:
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
}
Bemerkung
Wir empfehlen dir, dass du ein optionales [player]
Argument hinzufügst, um deinen Befehl Konsolen-freundlich zu machen (z.B. /suicide [player]
).
Die einfachste Lösung hierfür ist es, ein playerOrSource
Befehlselement (Siehe Paramenterverarbeitung) hinzuzufügen.
Befehlsergebnisse
Die CommandExecutor#execute()
Methode muss immer ein CommandResult zurückgeben. In den meisten Fällen ist es ausreichend CommandResult#success() zurückzugeben, wenn der Befehl erfolgreich war, oder CommandResult#empty(), wenn es das nicht war. In den Fällen, wo mehr Informationen übertragen werden müssen, sollte der CommandResult#builder() benutzt werden. Der Builder bietet verschiedene Methoden an, die Integers akzeptieren und das gleichnamige Attribut setzen. Alle Attribute, die nicht von Builder gesetzt werden, bleiben leer.
Befehlsblocke können diese Werte verwenden um die Scoreboard Statistiken anzupassen, die dann wiederum für sorgfältig ausgearbeitete Konstruktionen aus mehreren Befehlsblöcken verwendet werden können. Ein Tutorial, wie auf Daten zugegriffen werden kann hier gefunden werden.
Beispiel: Ein CommandResult erstellen
CommandResult result = CommandResult.builder()
.affectedEntities(42)
.successCount(1)
.build();
Dieses Beispiel zeigt, wie man einen Builder verwendet, um ein CommandResult
für einen Befehl zu erstellen, der 42 Entitäten betroffen hat und erfolgreich durchgelaufen ist.
Fehlerbehandlung
The execute()
method may also throw a CommandException, signaling that an error occurred while trying to
execute the command. If such an Exception is thrown, its message will be displayed to the command source, formatted as
an error. Also, the commands usage message will be displayed. An ArgumentParseException, a subtype of
CommandException
is automatically thrown if the commands arguments could not be parsed.