Befehle einem Twasi-Plugin hinzufügen

Es gibt mehrere Möglichkeiten, Befehle in dein Plugin zu implementieren:

Bitte beachte, dass dein Plugin keinen Befehl erhält, der nicht in seiner plugin.yml Datei registriert ist.

Die OnCommand-Methode (empfohlen für statische Befehle)

Die einfachste Möglichkeit ist es, die OnCommand-Methode in deiner TwasiUserPlugin-Klasse zu überschreiben. (Wirf einen Blick hierdrauf, falls du nichts über die TwasiUserPlugin Klasse weißt.)

public class MyAmazingUserPlugin extends TwasiUserPlugin {

    @Override
    public void onCommand(TwasiCommandEvent event) {
        String usedCommand = event.getCommand().getCommandName();
        TwasiLogger.log.debug("Used command: " + usedCommand);
    }
}

Du kannst auch mehrere Befehle mit dieser Methode handhaben, aber dies sollte nur für wirklich einfache oder statische Befehle verwendet werden, nicht für komplexere Befehlsstrukturen.

public class MyAmazingUserPlugin extends TwasiUserPlugin {

    @Override
    public void onCommand(TwasiCommandEvent e) {
        switch (e.getCommand().getCommandName().toLowerCase()) {
            case "test":
                e.getCommand().reply("successful");
                break;
            case "ping":
                e.getCommand().reply("pong");
                break;
        }
    }
}

Warnung! Da die OnCommand-Methode registrierte Command Controller aufruft (siehe unten), funktionieren diese nicht, wenn sie überschrieben werden.

Controller-gesteuerte Befehle

Es ist viel übersichtlicher, eine Controller-Klasse für jeden Befehl, den man registriert, zu erstellen. So hältst du deinen Code sauber und trennst alles in Klassen.

Wenn dein Plugin mehrere Befehle hat, solltest du ein neues Paket innerhalb deines Basispakets namens "commands" oder ähnliches erstellen, das alle deine Command Controller Klassen enthält.

Der Command Controller wird wird einmalig instanziiert, wenn du sie in deiner TwasiUserPlugin-Klasse registrierst. Dies bedeutet, dass deine Controller-Klasse für jeden installierten Kanal ein Objekt hat, sodass du Kontextinformationen über einen Kanal in seinen Klassenvariablen speichern kannst.

Die TwasiPluginCommand-Klasse

Die Verwendung der TwasiPluginCommand Klasse wird für einfache und komplexere Befehle empfohlen. In den meisten Fällen solltest du damit zurecht kommen. Wenn dein Befehl mehrere Unterbefehle hat, solltest du dir die StructuredPluginCommand-Klasse ansehen.

Um loszulegen, fügst du zu deinem Projekt eine neue Klasse hinzu und erweiterst die TwasiPluginCommand-Klasse:

package de.merlinw.commands;

import net.twasi.core.plugin.api.TwasiUserPlugin;
import net.twasi.core.plugin.api.customcommands.TwasiCustomCommandEvent;
import net.twasi.core.plugin.api.customcommands.TwasiPluginCommand;

public class ExampleCommand extends TwasiPluginCommand {

    public ExampleCommand(TwasiUserPlugin twasiUserPlugin) {
        super(twasiUserPlugin);
    }

    @Override
    protected boolean execute(TwasiCustomCommandEvent event) {
        event.reply("You successfully executed the example command! :o");
        return true;
    }

    @Override
    public String getCommandName() {
        return "example";
    }

}

Du musst denselben Konstruktor wie die Superklasse haben. Andernfalls wird ein Fehler auftreten, wenn du versuchst, deinen Befehl zu registrieren. Lass es einfach so, wie es ist.

Die Funktion getCommandName() muss ebenfalls überschrieben werden. Es wird der Name des Befehls (ein einzelnes Wort) zurückgegeben, auf den der Controller reagieren soll.

Der Befehlsname sollte nicht das Befehls-Präfix enthalten (welches standardmäßig '!' ist).

Die Funktion execute(TwasiCustomCommandEvent Event) ist deine Hauptausführungsfunktion, die immer aufgerufen wird, wenn jemand deinen Befehl ausführt. Der zurückgegebene Boolean definiert, ob der Befehl erfolgreich ausgeführt wurde oder nicht. Wenn der Befehl erfolgreich ausgeführt wurde, wird der Command Cooldown - falls festgelegt - auf den Benutzer angewendet, der den Befehl ausgeführt hat.

Berechtigungen einrichten

Wenn der Befehl einen bestimmten Berechtigungsschlüssel benötigen sollte, überschreibe einfach die Funktion requirePermissionKey() und lasse den gewünschten Schlüssel zurückgeben. Twasi-Core wird sich um den Rest kümmern.

Dies funktioniert auch für TwasiSubCommands.

Einrichten eines Cooldowns

Befehle haben standardmäßig einen Cooldown von einer Minute, die auf den Benutzer und den Befehl angewendet wird, wenn der Befehl erfolgreich ausgeführt wurde. Wenn du diesen Cooldown erhöhen/verringern möchtest, überschreibst du einfach die Funktion getCooldown() und lässt sie die gewünschte Dauer zurückgeben.

Alias einrichten

Dies wird noch nicht unterstützt. Aber es wird in der Zukunft unterstützt. Versprochen!

Weitere Einstellungen

Timer

Twasi unterstützt Timer. Timer sind Befehle, die automatisch in einem bestimmten Intervall ausgeführt werden, während der Kanal live ist. Wenn dein Befehl als Timer verfügbar sein soll, überschreibe die Funktion allowsTimer() und gib "true" zurück.

Dies ist nur für nicht funktionelle Befehle nützlich. Zum Beispiel der Befehl !hosts des Utitlies Plugins hat Timer aktiviert.

Auflistung

Sollte dein Befehl nicht aufgeführt werden, wenn jemand !commands im Chat ausführt, überschreibe die Funktion allowsListing() und setze es auf "false".

Controller registrieren

Um deinen Controller zu registrieren, rufe diese Funktion einfach aus deiner TwasiUserPlugin-Klasse (z. B. innerhalb des Konstruktors) für jeden deiner Befehle auf:

    public ExampleUserPlugin() {
        registerCommand(ExampleCommand.class);
        registerCommand(ExampleStructuredCommand.class);
    }

Wenn du die Konstruktorsignatur deiner Command-Controller-Klasse geändert hast, wird die obige Syntax einen Fehler auslösen. Du kannst diese Syntax stattdessen verwenden:

    registerCommand(new ExampleCommand(this, otherParameters));

Die StructuredPluginCommand-Klasse

Je mehr Unterbefehle dein Befehl hat ("!command add" und "!command remove", als Beispiel), desto verwirrender wird dein Code. Um die Dinge so sauber und lesbar wie möglich zu halten, haben wir den StructuredPluginCommand in unser Plugin-Framework eingeführt.

Es funktioniert ähnlich wie die TwasiPluginCommand Klasse, aber du kannst eine Reihe von Unterbefehlen angeben, die Twasi automatisch so handhaben wird, als wären sie normale Befehle. Auf diese Weise hast du einen Controller für jeden Unterbefehl und benötigst keine Unmengen an if-elses oder switch cases.

Der StructuredPluginCommand ist auch multidimensional, sodass du Unterbefehle für deine Unterbefehle angeben kannst, was die Dinge wesentlich einfacher macht, wenn du eine komplexe Befehlsstruktur benötigst.

Du kannst damit beginnen, eine Klasse zu erstellen, die StructuredPluginCommand erweitert:

package de.merlinw.commands;

import net.twasi.core.plugin.api.TwasiUserPlugin;
import net.twasi.core.plugin.api.customcommands.TwasiCustomCommandEvent;
import net.twasi.core.plugin.api.customcommands.structuredcommands.StructuredPluginCommand;
import net.twasi.core.plugin.api.customcommands.structuredcommands.subcommands.SubCommandCollection;

public class ExampleStructuredCommand extends StructuredPluginCommand {

    public ExampleStructuredCommand(TwasiUserPlugin twasiUserPlugin) {
        super(twasiUserPlugin);
    }

    @Override
    protected boolean handle(TwasiCustomCommandEvent event) {
        // This is the command handler for !example without a valid subcommand
    }

    @Override
    public String getCommandName() {
        return "example";
    }

    @Override
    public SubCommandCollection getSubCommands() {
        return null;
    }

}

Da die StructuredPluginCommand-Klasse TwasiPluginCommand erweitert, sind alle Funktionen gleich. Der einzige Unterschied besteht darin, dass die Funktion execute in StructuredPluginCommands handle heißt, da die execute-Funktion im Hintergrund arbeitet. Du kannst die verfügbaren Funktionen und Methoden hier finden.

Unterbefehle hinzufügen

Um einige Unterbefehle zu deinem Controller hinzuzufügen, musst du eine SubCommandCollection auf der Funktion getSubCommands() zurückgeben.

Erster Unterbefehl

package de.merlinw.commands.example_subcommands;

import net.twasi.core.plugin.api.customcommands.TwasiCustomCommandEvent;
import net.twasi.core.plugin.api.customcommands.structuredcommands.TwasiStructuredCommandEvent;
import net.twasi.core.plugin.api.customcommands.structuredcommands.subcommands.ISubCommands;
import net.twasi.core.plugin.api.customcommands.structuredcommands.subcommands.TwasiSubCommand;

public class FirstSubCommand extends TwasiSubCommand {

    public FirstSubCommand(TwasiCustomCommandEvent event, ISubCommands parent) {
        super(event, parent);
    }

    @Override
    protected boolean handle(TwasiStructuredCommandEvent event) {
        event.reply(event.getArgs().get(0));
        return true;
    }

    @Override
    public String getCommandName() {
        return "first";
    }
}

Zweiter Unterbefehl

package de.merlinw.commands.example_subcommands;

import net.twasi.core.plugin.api.customcommands.TwasiCustomCommandEvent;
import net.twasi.core.plugin.api.customcommands.structuredcommands.TwasiStructuredCommandEvent;
import net.twasi.core.plugin.api.customcommands.structuredcommands.subcommands.ISubCommands;
import net.twasi.core.plugin.api.customcommands.structuredcommands.subcommands.TwasiSubCommand;

public class SecondSubCommand extends TwasiSubCommand {

    public SecondSubCommand(TwasiCustomCommandEvent event, ISubCommands parent) {
        super(event, parent);
    }

    @Override
    protected boolean handle(TwasiStructuredCommandEvent event) {
        event.reply("This is the second subcommand!");
        return true;
    }

    @Override
    public String getCommandName() {
        return "second";
    }
}

Übergeordnete Klasse

    @Override
    public SubCommandCollection getSubCommands() {
        return SubCommandCollection.OFCLASSES(
                FirstSubCommand.class,
                SecondSubCommand.class
        );
    }

Du kannst auch die getSubCommands() Methode auf Unterbefehls-Controllern überschreiben, um Unterbefehle deinen Unterbefehlen hinzuzufügen. ( ͡° ͜ʖ ͡°)

Der FirstSubCommand-Controller würde auf Befehle wie '!example first' reagieren. Es wird das erste Befehlsargument zurückgegeben. Da Unterbefehle darauf abzielen, sich wie normale Befehle zu verhalten, wird der verwendete Unterbefehlsname automatisch aus der Argumentenliste entfernt. Für '!example first 123', wäre 123 die Befehlsausgabe.

Eingehende Befehle, die einen ungültigen Unterbefehl haben, werden von der übergeordneten Klasse behandelt.

Übersetzungen

Du wirst auf der nächsten Seite mehr über den Übersetzungsrenderer erfahren.

Wenn du die Funktion handle nicht überschreibst, rendert und gibt sie automatisch den Übersetzungsschlüssel command-name.syntax' zurück.

Dies funktioniert auch für Unterbefehle. Wenn der Beispielbefehl einen Unterbefehl namens 'add' hatte, würde er standardmäßig den Übersetzungsschlüssel 'example.add.syntax' rendern und zurücksenden.

Fortfahren

Im nächsten Teil der "Getting started" Serie wirst du lernen, wie du Übersetzungen zu deinem Plugin hinzufügen kannst!