Das Twasi-Plugin

Twasi selbst bietet nicht viele Funktionen, die im Twitch-Chat genutzt werden können. Stattdessen lädt es Plugins, die diese Funktionen in einer .jar-Datei enthalten.

Das Twasi-Plugin-Framework

Twasi-Core enthält das Twasi-Plugin-Framework. Dies ist ein Java-Framework, um Twasi-Funktionen so einfach wie möglich zu bauen. Du kannst es mit dem Java-Paketmanager "Maven" zu einem Projekt hinzufügen, da Twasi Core in unserer öffentliches Maven Artifactory hochgeladen wird.

Aus was besteht ein Twasi-Plugin?

Die TwasiPlugin-Klasse

Jedes Twasi-Plugin hat eine Hauptklasse, die von Twasi-Core geladen wird. Diese Klasse muss die "TwasiPlugin" Klasse von Twasi-Core erweitern. Es ist die Hauptschnittstelle für die Interaktion mit dem Twasi-Core.

Sie besteht aus folgenden Methoden und Funktionen, die überschrieben werden können:

Name	Rückgabewert	Muss überschrieben werden	Beschreibung
getUserPluginClass()	Class<? extends TwasiUserPlugin>	Ja	Gibt die Klasse zurück, die für jeden Benutzer, der das Plugin installiert hat, instanziiert wird.
onActivate()	void	Nein	Ein Event-Handler, der aufgerufen wird, wenn das Plugin aktiviert wird.
onDeactivate()	void	Nein	Ein Event-Handler, der aufgerufen wird, wenn das Plugin deaktiviert wird.
onReady()	void	Nein	Ein Event-Handler, der aufgerufen wird, wenn das Plugin bereit ist.
getGraphQLResolver()	GraphQLQueryResolver	Nein	Wenn ein Plugin API-Endpunkte für die öffentliche GraphQL-API bereitstellt, muss hier der GraphQL-Resolver zurückgegeben werden.

Die TwasiUserPlugin-Klasse

Die TwasiPlugin Klasse wird nach dem Laden des Plugins einmal instanziiert. Es hat eine Funktion namens getUserPluginClass(), die überschrieben werden muss. Diese gibt eine Klasse aus, welche die TwasiUserPlugin Klasse erweitert. Diese Klasse wird nun für jeden Twasi-User instanziiert, der das Plugin installiert hat. Die Idee dahinter ist Einfachheit für die Entwickler. Du kannst Informationen und Zusammenhänge, die zu einem Kanal gehören, vorübergehend in Klassenvariablen deiner UserPlugin-Klasse speichern und musst diese Informationen nicht in Karten oder ähnliches einfügen.

Sie besteht aus folgenden Methoden und Funktionen, die überschrieben werden können:

Name	Rückgabewert	Beschreibung
onEnable(TwasiEnableEvent)	void	Ein Event-Handler, der aufgerufen wird, wenn das UserPlugin aktiviert ist (nach dem Neustart des Cores).
onDisable(TwasiDisableEvent)	void	Ein Event-Handler, der aufgerufen wird, wenn das UserPlugin deaktiviert ist (beim Stoppen des Cores).
onInstall(TwasiInstallEvent)	void	Ein Event-Handler, der bei der Installation des UserPlugins aufgerufen wird.
onUninstall(TwasiInstallEvent)	void	Ein Event-Handler, der bei der Deinstallation des UserPlugins aufgerufen wird.
onCommand(TwasiCommandEvent)	void	Ein Event-Handler, der aufgerufen wird, wenn ein Befehl ausgeführt wird.
onMessage(TwasiMessageEvent)	void	Ein Event-Handler, der aufgerufen wird, wenn eine Nachricht an den User-Chat gesendet wird (ignoriert die Nachrichten des Bots).

Keiner von ihnen muss überschrieben werden

Das Überschreiben der OnCommand-Methode deaktiviert das Befehl-Registrierungssystem, welches jedoch aufgrund seiner Flexibilität sehr empfohlen wird.

Wenn du die onMessage-Methode verwenden möchtest, musst du "messageHandler" in deiner plugin.yml-Datei auf true setzen.

Die Plugin.yml Datei

Um Twasi dein Plugin verständlich zu machen, musst du eine plugin.yml-Datei in deinen Ressourcenordner (oder direkt in deine jar-Datei) legen. Diese Datei enthält grundlegende Informationen über das Plugin und zeigt dem Core, welche Befehle, Berechtigungen und API-Endpunkte verfügbar sind. Aber wir werden später mehr auf diese Dinge eingehen.

Beispiel plugin.yml

Dies ist ein Beispiel dafür, wie eine einfache Plugin.yml-Datei aussehen könnte:

name: "My cool plugin"
author: "DieserMerlin"
main: net.twasiplugin.example.ExamplePlugin
version: "1.0"
description: "An example plugin"
commands:
    - test
permissions:
    - exampleplugin.test

plugin.yml Eigenschaften

Folgende Eigenschaften sind verfügbar:

Name	Typ	Beschreibung	notwendig
name	string	Der einzigartige Name des Plugins. Sollte später nicht geändert werden.	Ja
description	string	Eine kurze Beschreibung des Plugins.	Nein
author	string	Der Name des Autors.	Ja
version	string	Die aktuelle Version des Plugins.	Ja
main	string	Der vollständige Pfad zu deiner TwasiPlugin-Klasse inklusive des Pakets.	Ja
helpText	string	Eine Erklärung, wie dein Plugin funktioniert.	Nein
api	string	GraphQL API Definitionen.	Nein
messageHandler	boolean	Ob das Plugin alle Nachrichten empfangen sollte.	Nein
dynamicCommandNames	boolean	Ob das Plugin auf alle Befehle hören soll.	Nein
dependency	boolean	Ob das Plugin eine TwasiDependency ist.	Nein
hidden	boolean	Ob das Plugin im Plugin-Shop versteckt werden soll.	Nein
autoInstall	boolean	Ob das Plugin automatisch installiert werden soll.	Nein
commands	string[]	Eine Liste aller Befehlsnamen.	Nein
permissions	string[]	Eine Liste aller Berechtigungsschlüssel, die das Plugin verwendet.	Nein
dependencies	string[]	Andere Twasi-Plugins, von denen das Plugin abhängt.	Nein

Während der Name des Plugins benötigt wird (weil es die "ID" des Plugins ist), sind die Beschreibung und der Hilfetext nicht erforderlich. Der Grund dafür ist, dass du diese lokalisiert in den Übersetzungsdateien des Plugins später zur Verfügung stellen kannst.

Das Verhalten von hidden und autoInstall:

Die Eigenschaften hidden und autoInstall sollten in den meisten Fällen nicht verwendet werden. Sie wurden implementiert, um Plugins zu erstellen, die immer installiert werden, wie das Debug-Plugin oder der StreamTracker.

hidden	autoInstall	Verhalten
true	false	Das Plugin erscheint nicht im Plugin-Store und wird in keinem Kanal installiert, es sei denn, es wird manuell über die Datenbank in die Plugin-Liste eines Benutzers aufgenommen.
false	true	Neue Benutzer werden das Plugin auf der Setup-Seite von Twasi als empfohlen sehen.
true	true	Das Plugin erscheint nicht im Plugin Store, sondern wird beim Start von Twasi automatisch für jeden Benutzer geladen.

Plugin-Konfigurationen

Wenn dein Plugin eine Konfigurationsdatei benötigt, kannst du eine Template-Klasse mit allen Einstellungen erstellen, die verfügbar sein sollen. Twasi erstellt die Datei automatisch für dich, auf Basis der von dir angegebenen Vorlage. Danach ist es möglich, diese Datei mit einer einzigen Zeile Code in den Code zu laden.

Mögliche Anwendungen: Dein Plugin lässt sich in eine Drittanbieter-API integrieren und benötigt API-Anmeldeinformationen. Anstatt sie fest zu programmieren, kannst du eine Konfigurationsdatei erstellen, in die der Instanzhoster sie einfügen kann.

Übersetzungen

Twasi ist nicht auf eine Sprache beschränkt. Derzeit unterstützen wir die deutsche und die englische Sprache. Um mehrere Sprachen zu unterstützen, verwendet Twasi Übersetzungsdateien (Ländercode.lang) im Ressourcenverzeichnis des Plugins unter /translations.

Derzeit unterstützte Sprachen:

Code	Land
DE_DE	Deutschland
EN_GB	Großbritannien

Sie sind so strukturiert:

translation.key=Dies ist ein Beispiel-Text.
command.output=Hey {sender.displayName}!

Über die Parameterverbindung wie {sender.displayName} kannst du hier mehr erfahren.

Übersetzungsschlüssel können vom Plugin-Entwickler ausgewählt werden, sollten aber durch Punkte getrennt werden.

Es gibt Standardübersetzungsschlüssel, die immer gesetzt werden sollten:

Schlüssel	Beschreibung
plugin.name	Der lokalisierte Name des Plugins.
plugin.description	Die lokalisierte Beschreibung des Plugins.
plugin.helptext	Der lokalisierte Hilfetext des Plugins.