Plugin-API v2CommonJS

TBot Plugin-API

Alles, was du brauchst, um eigene Commands, Buttons, Formulare, Timer und Dashboard-Einstellungen für TBot zu bauen – mit einer Referenz zu jeder Funktion und fertigen Beispiel-Plugins.

Abgeschottete Sandbox Einstellungen im Dashboard Rechte mit Freigabe
Leere VorlageKopieren, als index.js speichern, hochladen – fertig. Woher kommt tbot?

Einstieg

Ein Plugin ist ein kleines JavaScript-Programm (CommonJS), das TBot um eigene Funktionen erweitert. Du lädst es im TBot Market hoch – privat für dich oder öffentlich für alle – und Server-Admins installieren es mit einem Klick auf ihrem Server.

Die Sandbox

Jedes Plugin läuft in einem eigenen Node-Prozess, getrennt vom Bot. Es hat keinen Zugriff auf Dateien außerhalb des Plugins, keine Prozesse, keine Umgebungsvariablen und nie das Bot-Token. Internet gibt es nur über ctx.fetch zu Domains, die du angibst.

Alles, was nach außen wirkt, ist ein Aufruf an ctx.*. TBot prüft jeden Aufruf: Gehört der Kanal zu diesem Server? Hat der Admin das nötige Recht erlaubt? Ist ein Limit erreicht? Ein Plugin kann deshalb nie einen anderen Server anfassen.

Alle ctx-Methoden geben ein Promise zurück – nutze immer await, sonst gehen Fehler verloren und die Reihenfolge deiner Nachrichten ist zufällig.

Schnellstart in 3 Schritten

  1. Datei anlegen

    Erstelle eine Datei index.js mit der leeren Vorlage. Die exportierte Funktion bekommt das tbot-Objekt – darüber meldest du alles an, was dein Plugin kann.

    Woher kommt tbot? TBot übergibt es, wenn es deine exportierte Funktion aufruft – siehe Der Export.

  2. Hochladen

    Öffne Plugin hochladen, wähle die Datei und lass sie erst einmal privat. Der Sicherheits-Scan prüft sie sofort.

  3. Installieren & testen

    Installiere das Plugin im Dashboard unter Plugins auf deinem Server und tippe /hello in einen Kanal. Fertig!

Nächster Schritt: ein Prefix-Command (!hello) und ein Slash-Command mit Option und privater Antwort:

Hochladen & installieren

So kommt dein Plugin von der Datei auf einen Server:

  1. Hochladen

    Lade unter Market → Hochladen eine .js-Datei oder ein .zip-Paket hoch. Wähle privat (nur du kannst es installieren) oder öffentlich (alle sehen es im Market).

  2. Sicherheits-Scan

    Jeder Upload wird automatisch geprüft (siehe Sicherheits-Scan). Danach startet TBot das Plugin einmal in der Sandbox und liest aus, was es anmeldet.

  3. Market-Vorschau

    Die Market-Seite zeigt, was dein Plugin tut: Commands, Slash-Commands, Events, Buttons, Timer, die angeforderten Rechte, die Domains für ctx.fetch und die Einstellungen.

  4. Installieren & Freigabe

    Ein Server-Admin installiert das Plugin. Fordert es Rechte an, muss der Admin sie in einem Dialog ausdrücklich erlauben – sonst wird es nicht installiert.

  5. Einrichten

    Im Dashboard (Plugins) füllt der Admin dein Einstellungs-Formular aus. Speichern löst das Event configChange aus, ab dann stehen die Werte in ctx.config.

  6. Updates

    Neue Versionen kannst du jederzeit hochladen. Fordert eine neue Version mehr Rechte an, gelten die neuen erst, wenn ein Admin sie im Dashboard freigibt – bis dahin schlagen diese Aufrufe fehl.

Free-Server können 3 Plugins installieren, VIP-Server 20. Teste erst privat auf deinem eigenen Server und veröffentliche dann.

Plugin-Aufbau

Ein Plugin ist entweder eine einzelne .js-Datei oder ein .zip-Paket. Beide nutzen CommonJS (module.exports, require()) – ES-Module (import/export) lehnt der Scan ab.

Der Export: woher kommt tbot?

Die Startdatei jedes Plugins muss genau eine Funktion exportieren. TBot ruft sie auf und übergibt dir dabei das fertige tbot-Objekt – du musst nichts installieren oder importieren. Zum Loslegen gibt es oben die leere Vorlage.

  • Wer ruft sie auf? TBot – einmal, wenn das Plugin in der Sandbox startet: nach der Installation, beim Start des Bots und nach einer neuen Version.
  • Woher kommt tbot? TBot übergibt es als Argument. Es gibt kein npm-Paket, require('tbot') existiert nicht (und nicht erlaubte Module sind ohnehin gesperrt).
  • Der Name ist frei: (bot) => { … } funktioniert genauso – tbot ist nur die Konvention dieser Doku.
  • Alternative Form: module.exports = { setup(tbot) { … } }; – TBot ruft dann setup auf.
  • Darf async sein: TBot wartet auf das Promise, bevor das Plugin als gestartet gilt (max. 8 Sekunden). Melde alles – Commands, Events, Einstellungen, Rechte – darin an, nicht später (z. B. in einem Handler oder Timeout).
  • ctx gehört nicht zum Export: ctx bekommst du nicht beim Start. TBot übergibt es deinen Handlern (run, tbot.on, tbot.button …) jedes Mal, wenn etwas passiert.
  • Lokal starten bringt nichts: node index.js definiert nur die Funktion – niemand ruft sie auf. Teste, indem du das Plugin privat hochlädst und auf deinem eigenen Server installierst.

Eine einzelne .js-Datei

Perfekt für kleine und mittlere Plugins, bis 1 MB. Die Datei exportiert eine Funktion, die TBot einmal mit dem tbot-Objekt aufruft:

ZIP-Paket mit plugin.json

Für größere Plugins mit mehreren Dateien. Erlaubt sind .js, .json, .md und .txt – bis 1 MB gepackt, 3 MB entpackt, 60 Dateien, 512 KB pro Datei. Eigene Dateien lädst du mit require('./file.js').

ticket-plugin.zip ├── plugin.json // name, version, main file ├── index.js // module.exports = (tbot) => { … } ├── lib/ │ └── panel.js // require('./lib/panel.js') ├── texts.json // require('./texts.json') └── README.md
FeldTypBeschreibung
namestringName des Plugins (max. 40 Zeichen)
versionstringVersion wie 1.2.0 (sonst 1.0.0)
descriptionstringKurze Beschreibung (max. 500 Zeichen)
mainstringStartdatei, Standard index.js

Setup und Handler

TBot startet dein Plugin einmal und ruft die exportierte Funktion mit tbot auf. Darin meldest du alles an: Commands, Events, Buttons, Timer, Rechte und Einstellungen (die Setup-Funktionen). Der Start darf höchstens 8 Sekunden dauern. Danach ruft TBot deine Handler bei jedem Ereignis mit einem neuen ctx auf.

Ein Prozess für alle Server: Dein Plugin läuft einmal für alle Server, auf denen es installiert ist. Variablen in deinem Code teilen sich also alle Server – speichere Daten pro Server in ctx.storage und nimm ctx.guild.id in die Schlüssel eigener Zwischenspeicher auf.

Erlaubte Module

require() funktioniert für eigene Dateien und diese eingebauten Node-Module:

utileventsurlquerystringassertbufferstring_decodertimerscryptopath

Alles andere – z. B. fs, http, net, child_process oder npm-Pakete – ist gesperrt. console.log und console.error landen in deinen Plugin-Logs.

Sicherheits-Scan

Jeder Upload wird geprüft, bevor er im Market landet. Der Scan lehnt ab:

  • Syntaxfehler und ES-Module (import / export)
  • Gesperrte Module, eval und new Function
  • Verschleierten oder minifizierten Code und lange kodierte Datenblöcke (z. B. Base64)
  • Verschlüsselte ZIPs, andere Archive (RAR, 7z, GZip), Programme und Binärdaten

Setup-Funktionen

Diese Funktionen gibt es am tbot-Objekt. Du rufst sie nur beim Start auf (direkt in deiner exportierten Funktion). Sie beschreiben, was dein Plugin kann – TBot zeigt diese Infos im Market und Dashboard an.

Context (ctx)

Jeder Handler bekommt genau ein Argument: ctx. Darin stecken die Daten zum aktuellen Ereignis und alle Methoden zum Handeln – immer nur für diesen Server.

Immer vorhanden: ctx.guild, ctx.config, ctx.event, ctx.storage, ctx.levels, ctx.economy, die Lookups und Aktionen. Die übrigen Felder hängen vom Event ab – siehe Tabelle unten und die Events.

Welche Antwort geht wo?

Nachrichten

msg ist entweder einfacher Text (bis 2000 Zeichen) oder ein Nachrichten-Objekt mit Embeds, Buttons, Auswahlmenü und Dateien. Alle Sende-Methoden geben { id, channelId } zurück – bei ephemeral ist es { id: null }.

@everyone, @here und Rollen-Pings sind immer blockiert. Erwähnungen von Nutzern (<@id>) funktionieren.

Embeds, Buttons & Auswahlmenüs

Statt einfachem Text nimmt jede Sende-Methode auch ein Objekt. So sieht die folgende Nachricht in Discord aus:

primarysecondarysuccessdangerlinkselect

Formulare (Modals)

Formulare sind Discord-Pop-ups mit bis zu 5 Textfeldern. Du öffnest eins mit ctx.showModal() aus einem Slash-Command, Button oder Auswahlmenü und bekommst die Antworten in tbot.modal().

  1. Öffnen

    Im Slash-, Button- oder Select-Handler: ctx.showModal({ … }) – als erste Antwort, innerhalb von 2 Sekunden.

  2. Ausfüllen

    Die Person füllt das Formular in Discord aus und klickt Absenden.

  3. Empfangen

    Dein Handler tbot.modal(id, fn) läuft mit ctx.fields und antwortet mit ctx.reply().

Lookups

Nur-lesende Infos über den Server. Lookups brauchen kein Recht.

Mitglieder verwalten

Rollen, Nicknames und Moderation. Jede Methode braucht ein Recht, das der Admin erlaubt hat. Moderations-Aktionen landen im Mod-Log des Servers mit [Plugin <Name>].

Schutzregeln: nur Rollen unter dem Bot, keine verwalteten Rollen und keine Rollen mit Admin-, Server-verwalten-, Rollen-verwalten-, Bann- oder Kick-Rechten. Kick, Bann und Timeout treffen nie Admins, den Owner oder Mitglieder mit höherer Rolle als der Bot.

Levels & Economy

Zugriff auf das Level-System und die Candy-Economy von TBot auf diesem Server. Lesen geht immer, Ändern braucht levels bzw. economy.

Speicher

ctx.storage ist ein kleiner Schlüssel-Wert-Speicher – getrennt pro Server und Plugin. Werte sind beliebiges JSON (Zahlen, Text, Arrays, Objekte). Mit ctx.storage.user(id) bekommst du dieselben Methoden, automatisch getrennt pro Mitglied.

1000Schlüssel pro Server
8 KBpro Wert (als JSON)
100Zeichen pro Schlüssel
Nutze Präfixe wie ticket:12 oder poll:ab12 – dann listet keys('ticket:') alle Tickets. Lösche, was du nicht mehr brauchst, damit du nicht an das Limit von 1000 Schlüsseln stößt.

JSON-Dokumente

Mit ctx.json(name) speicherst du ein ganzes JSON-Objekt unter einem Namen – pro Server und Plugin – und liest oder änderst Teile davon über Pfade. Ideal für Statistiken, Spielstände, Profile oder Protokolle. Mit files schickst du jedes Dokument als .json-Datei.

Pfade

  • Ebenen trennst du mit Punkten: 'users.123.points'. Eine Zahl im Pfad meint ein Listen-Element: 'log.0'.
  • Fehlende Ebenen werden automatisch als Objekte angelegt – auch bei Zahlen wie User-IDs. set('users.123.points', 5) ergibt { users: { "123": { points: 5 } } }.
  • Listen entstehen nur über push. delete('log.0') entfernt das Element aus der Liste.
  • Pfad-Teile: A-Z a-z 0-9 _ -, max. 12 Ebenen; __proto__, constructor und prototype sind verboten.
64 KBpro Dokument
20Dokumente pro Server
1000Einträge pro Liste
12Pfad-Ebenen

ctx.json oder ctx.storage?

ctx.storagectx.json(name)
Gut fürViele kleine, unabhängige Werte: Zähler, Schalter, Panel-IDs, Werte pro MitgliedEine zusammenhängende Struktur, die du oft als Ganzes liest oder exportierst: Bestenlisten, Spielstände, Protokolle
Größe8 KB pro Wert, 1000 Schlüssel64 KB pro Dokument, 20 Dokumente
ZugriffGanzer Wert pro SchlüsselPfade ins Dokument, Listen mit push

JSON-Dokumente zählen zum Speicher-Limit (1000 Schlüssel) und erscheinen in ctx.storage.keys() als json:<name>.

Internet (fetch)

Plugins haben keinen direkten Internetzugang. Mit ctx.fetch kannst du trotzdem Web-APIs aufrufen – aber nur zu Domains, die du mit tbot.network() angegeben hast, und mit dem Recht network.

  • Nur https://, nur angegebene Domains (max. 10), keine privaten oder lokalen Adressen
  • Max. 512 KB Antwort, 8 Sekunden Zeitlimit, 20 Anfragen pro Minute und Server
  • Leg keine geheimen Schlüssel in den Code – sie wären für jeden sichtbar, der Zugriff auf die Plugin-Dateien hat

Events

Mit tbot.on(event, fn) reagiert dein Plugin auf Dinge, die auf dem Server passieren. Jedes Event füllt andere ctx-Felder:

Einstellungen für Server-Admins

Mit tbot.settings() beschreibst du ein Formular. TBot baut daraus automatisch eine Einstellungsseite im Dashboard – mit Kanal- und Rollen-Auswahl, Schaltern und Prüfung der Eingaben. Die gespeicherten Werte stehen in ctx.config, inklusive Standardwerten.

tbot.settings({ … })Du definierst die Felder
Dashboard-FormularAdmin füllt aus und speichert
PrüfungGegen dein Schema, unbekannte Keys fliegen raus
ctx.configDazu das Event configChange

Felder für jeden Typ

FeldTypBeschreibung
typestringEiner der 12 Typen unten (Pflicht)
labelstringBeschriftung im Dashboard, max. 60 Zeichen
descriptionstringHilfetext unter dem Feld, max. 200 Zeichen
defaultanyStandardwert – steht in ctx.config, solange nichts gespeichert ist
requiredbooleanMuss ausgefüllt werden – Speichern ohne Wert schlägt fehl
sectionstringGruppiert Felder unter einer Überschrift, max. 40 Zeichen
placeholderstringPlatzhaltertext, max. 100 Zeichen
  • Max. 30 Felder pro Plugin. Keys: ^[a-zA-Z][a-zA-Z0-9_]{0,31}$ (z. B. teamRoles, max_open)
  • Werte in ctx.config: channel/role = ID-String oder null; channels/roles/multiselect/list = Array; alles andere = der Wert (oder der Standardwert)
  • Pflichtfelder können direkt nach der Installation noch leer sein – prüfe vor der Nutzung auf null

Alle 12 Typen

Jede Karte zeigt die Definition, den Wert in ctx.config und wie das Feld im Dashboard aussieht.

Rechte

Heikle Aktionen brauchen ein Recht. Du forderst sie mit tbot.permissions([…]) an, der Server-Admin muss sie beim Installieren erlauben. Ohne erlaubtes Recht wirft die Methode einen Fehler: Recht "roles" nicht erlaubt.

  1. Anfordern

    Dein Plugin ruft tbot.permissions(['roles', 'dm']) auf (und tbot.network([…]) für Internet).

  2. Freigabe-Dialog

    Beim Installieren sieht der Admin alle angeforderten Rechte und Domains und muss sie akzeptieren. Ohne Zustimmung keine Installation.

  3. Neue Version, neue Rechte

    Fordert ein Update mehr Rechte an, läuft das Plugin mit den alten Rechten weiter. Im Dashboard erscheint ein Hinweis; erst wenn der Admin auf Freigeben klickt, gelten die neuen.

Fordere nur an, was du wirklich nutzt. Weniger Rechte = mehr Vertrauen = mehr Installationen. Fang fehlende Rechte mit try/catch ab (siehe Fehler).

Limits

Limits schützen jeden Server vor fehlerhaften oder zu eifrigen Plugins. Wird ein Limit überschritten, schlägt der Aufruf mit einem Fehler fehl.

Pro Event

10Nachrichten
60ctx-Aufrufe
8 sLaufzeit

Pro Server und Plugin pro Minute

30Nachrichten
10DMs
20Moderations-/Rollen-Aktionen
20fetch-Anfragen
60XP-/Economy-Aufrufe

Prozess

64 MBArbeitsspeicher
Keineval / new Function
KeineDateien, Prozesse, Internet (außer ctx.fetch)

API-Grenzen im Überblick

WasLimit
Slash-Commands10 pro Plugin
Timer (tbot.every)5 pro Plugin, Intervall 60 s – 7 Tage
Nachrichtentext2000 Zeichen
Embeds5 pro Nachricht, je 25 Felder
Buttons25 pro Nachricht, 5 pro Reihe
Auswahlmenü1 pro Nachricht, 25 Optionen
Formulare (Modals)5 Felder, Titel und Labels max. 45 Zeichen
Komponenten-/Formular-IDs[A-Za-z0-9_:.-], max. 80 Zeichen
Domains (tbot.network)10
Einstellungs-Felder30
Speicher1000 Schlüssel, 8 KB pro Wert, Schlüssel max. 100 Zeichen
JSON-Dokumenteje 64 KB, 20 pro Server, 12 Pfad-Ebenen, 1000 Listen-Einträge
Dateien (files)5 pro Nachricht, je 1 MB, zusammen 3 MB; .json .txt .csv .md .log
ctx.fetch512 KB Antwort, 8 s
ctx.levels.addXp−1000 … 1000 pro Aufruf
ctx.economy.add/removemax. 100 000 pro Aufruf
ctx.timeoutmax. 28 Tage
levels.top / economy.topmax. 25 Einträge

tbot.util

Kleine Helfer für den Plugin-Alltag. Sie sind synchron (außer sleep) und funktionieren auch außerhalb von Handlern, ohne ctx. Die JSON-Helfer tbot.util.json.* stehen unter JSON-Dokumente.

Fehler & Logs

Wirft ein Handler einen Fehler (oder schlägt ein await fehl), wird nur dieses eine Event abgebrochen – das Plugin läuft weiter. TBot merkt sich den Fehler, und er erscheint im Dashboard unter Plugins → Logs/Fehler.

Was landet wo?

QuelleSichtbar inWer sieht es
Fehler in Handlern (throw, fehlgeschlagenes await)Fehler auf diesem Server + Alle LogsServer-Admins (erste Zeilen des Stacktrace)
Zeitüberschreitung (über 8 s)Fehler auf diesem ServerServer-Admins
console.log()Alle LogsNur du (der Autor)
console.error(), unbehandelte Fehler und PromisesAlle Logs (rot)Nur du (der Autor)
Fehler beim Start / SyntaxfehlerStatus Abgestürzt mit MeldungAlle, die es installiert haben

Plugin-Status

  • LäuftAlles in Ordnung, Events werden zugestellt.
  • Startet …Der Prozess fährt hoch (max. 8 s).
  • AbgestürztDer Prozess wurde beendet. TBot startet ihn automatisch neu; nach 5 Abstürzen in 10 Minuten wird das Plugin pausiert.
  • Gestoppt / DeaktiviertIm Dashboard ausgeschaltet oder nicht gestartet.
Endlosschleifen blockieren den ganzen Prozess. TBot merkt das und startet das Plugin neu: Plugin reagiert nicht mehr (Endlosschleife?) – wurde neu gestartet.

Häufige Fehlermeldungen

MeldungUrsache & Lösung
Recht "roles" nicht erlaubtRecht in tbot.permissions() eintragen – und der Admin muss es im Dashboard freigeben.
Zeitüberschreitung bei "message" (über 8 s)Der Handler hat länger als 8 s gebraucht. Weniger Aufrufe, kürzere sleeps, schnellere APIs.
Das Modul "fs" ist in Plugins gesperrt.Nur die erlaubten Module funktionieren.
Unbekanntes Event: …Tippfehler in tbot.on() – siehe Event-Liste.
Timer brauchen mindestens 60 Sekundentbot.every() braucht mindestens '1m' bzw. 60.
Höchstens 10 Slash-Commands pro PluginFasse Commands mit subcommands zusammen.
Ungültige Button-ID: …Nur A-Z a-z 0-9 _ : . -, max. 80 Zeichen, optional * am Ende.
Das Plugin muss eine Funktion exportieren: module.exports = (tbot) => { … }Deine Startdatei exportiert keine Funktion.

Fehler sauber abfangen

Fang erwartbare Fehler ab und gib der Person eine hilfreiche Antwort statt Stille:

Beispiel-Plugins

Komplette Plugins, die du so hochladen kannst – oder als Startpunkt nimmst. Jedes ist eine einzelne .js-Datei.

Bereit? Lade dein Plugin hochTeste es erst privat und veröffentliche es dann im Market.
Hochladen

FAQ

Woher bekomme ich tbot?

Gar nicht selbst: Deine Startdatei exportiert eine Funktion (module.exports = (tbot) => { … }), und TBot ruft sie beim Start des Plugins mit dem fertigen tbot-Objekt auf. Es gibt kein Paket zum Installieren. Details: Der Export.

Läuft mein Plugin auf mehreren Servern gleichzeitig?

Ja. Ein Prozess bedient alle Server, die es installiert haben. ctx, ctx.storage und ctx.config gehören immer zum Server des aktuellen Events – deine eigenen Variablen teilen sich aber alle. Speichere Zustand pro Server im Speicher.

Warum wirft ctx.addRole „Recht "roles" nicht erlaubt“?

Dein Plugin muss das Recht mit tbot.permissions(['roles']) anfordern, und der Admin muss es erlauben. Nach einem Update mit neuen Rechten muss der Admin erst im Dashboard auf Freigeben klicken.

Wie teste ich, bevor ich veröffentliche?

Lade das Plugin privat hoch, installiere es auf deinem eigenen Test-Server und schau in die Logs im Dashboard. console.log hilft beim Debuggen. Wenn alles klappt, stellst du es auf öffentlich.

Kann ich npm-Pakete nutzen?

Nein. Nur eigene Dateien im ZIP-Paket und die erlaubten eingebauten Module. Kleine Helfer stecken oft schon in tbot.util.

Mein Slash-Command erscheint nicht – warum?

Es kann ein paar Sekunden dauern, bis Discord neue Commands anzeigt. Namen von eingebauten TBot-Commands sind nicht möglich, und pro Plugin gibt es höchstens 10 Slash-Commands. Schau in den Logs nach Fehlern beim Start.

Kann ein Timer zu einer festen Uhrzeit laufen?

tbot.every läuft im Intervall, nicht zu einer Uhrzeit. Prüf die Uhrzeit im Handler und merk dir im Speicher, ob du heute schon gesendet hast – siehe Beispiel Tägliche Erinnerung.

Warum pingt @everyone nicht?

@everyone, @here und Rollen-Pings sind für Plugins immer blockiert, damit kein Plugin einen Server zuspammen kann. Erwähnungen von Nutzern funktionieren normal.

Was passiert mit den Daten, wenn ein Server das Plugin entfernt?

Der Speicher dieses Servers wird gelöscht. Andere Server sind nicht betroffen.

Ich brauche eine Discord-Funktion, die hier nicht steht.

Plugins können nur nutzen, was diese Referenz beschreibt – alles andere (z. B. Kanäle erstellen) ist bewusst nicht verfügbar, weil TBot jede Aktion prüfen muss.