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.
!hallo und echte Slash-Commands mit Optionen.
Buttons, Menüs & FormulareInteraktive Nachrichten mit Buttons, Auswahlmenüs und Pop-up-Formularen.
Events & TimerReagiere auf Nachrichten, Beitritte, Reaktionen und Voice – oder zeitgesteuert.
EinstellungenServer-Admins richten dein Plugin im Dashboard ein – ganz ohne Code.
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.
ctx.addRole()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.
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
-
Datei anlegen
Erstelle eine Datei
index.jsmit der leeren Vorlage. Die exportierte Funktion bekommt dastbot-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. -
Hochladen
Öffne Plugin hochladen, wähle die Datei und lass sie erst einmal privat. Der Sicherheits-Scan prüft sie sofort.
-
Installieren & testen
Installiere das Plugin im Dashboard unter Plugins auf deinem Server und tippe
/helloin 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:
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).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.
Market-Vorschau
Die Market-Seite zeigt, was dein Plugin tut: Commands, Slash-Commands, Events, Buttons, Timer, die angeforderten Rechte, die Domains für
ctx.fetchund die Einstellungen.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.
Einrichten
Im Dashboard (Plugins) füllt der Admin dein Einstellungs-Formular aus. Speichern löst das Event
configChangeaus, ab dann stehen die Werte inctx.config.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.
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 –tbotist nur die Konvention dieser Doku. - Alternative Form:
module.exports = { setup(tbot) { … } };– TBot ruft dannsetupauf. - Darf
asyncsein: 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). ctxgehört nicht zum Export:ctxbekommst 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.jsdefiniert 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').
| Feld | Typ | Beschreibung |
|---|---|---|
name | string | Name des Plugins (max. 40 Zeichen) |
version | string | Version wie 1.2.0 (sonst 1.0.0) |
description | string | Kurze Beschreibung (max. 500 Zeichen) |
main | string | Startdatei, 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.
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_decodertimerscryptopathAlles 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,
evalundnew 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:
primarysecondarysuccessdangerlinkselectFormulare (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().
Öffnen
Im Slash-, Button- oder Select-Handler:
ctx.showModal({ … })– als erste Antwort, innerhalb von 2 Sekunden.Ausfüllen
Die Person füllt das Formular in Discord aus und klickt Absenden.
Empfangen
Dein Handler
tbot.modal(id, fn)läuft mitctx.fieldsund antwortet mitctx.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>].
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.
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__,constructorundprototypesind verboten.
ctx.json oder ctx.storage?
ctx.storage | ctx.json(name) | |
|---|---|---|
| Gut für | Viele kleine, unabhängige Werte: Zähler, Schalter, Panel-IDs, Werte pro Mitglied | Eine zusammenhängende Struktur, die du oft als Ganzes liest oder exportierst: Bestenlisten, Spielstände, Protokolle |
| Größe | 8 KB pro Wert, 1000 Schlüssel | 64 KB pro Dokument, 20 Dokumente |
| Zugriff | Ganzer Wert pro Schlüssel | Pfade 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.
configChangeFelder für jeden Typ
| Feld | Typ | Beschreibung |
|---|---|---|
type | string | Einer der 12 Typen unten (Pflicht) |
label | string | Beschriftung im Dashboard, max. 60 Zeichen |
description | string | Hilfetext unter dem Feld, max. 200 Zeichen |
default | any | Standardwert – steht in ctx.config, solange nichts gespeichert ist |
required | boolean | Muss ausgefüllt werden – Speichern ohne Wert schlägt fehl |
section | string | Gruppiert Felder unter einer Überschrift, max. 40 Zeichen |
placeholder | string | Platzhaltertext, 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 odernull;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.
So funktioniert die Freigabe
Anfordern
Dein Plugin ruft
tbot.permissions(['roles', 'dm'])auf (undtbot.network([…])für Internet).Freigabe-Dialog
Beim Installieren sieht der Admin alle angeforderten Rechte und Domains und muss sie akzeptieren. Ohne Zustimmung keine Installation.
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.
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
Pro Server und Plugin pro Minute
Prozess
eval / new FunctionAPI-Grenzen im Überblick
| Was | Limit |
|---|---|
| Slash-Commands | 10 pro Plugin |
Timer (tbot.every) | 5 pro Plugin, Intervall 60 s – 7 Tage |
| Nachrichtentext | 2000 Zeichen |
| Embeds | 5 pro Nachricht, je 25 Felder |
| Buttons | 25 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-Felder | 30 |
| Speicher | 1000 Schlüssel, 8 KB pro Wert, Schlüssel max. 100 Zeichen |
| JSON-Dokumente | je 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.fetch | 512 KB Antwort, 8 s |
ctx.levels.addXp | −1000 … 1000 pro Aufruf |
ctx.economy.add/remove | max. 100 000 pro Aufruf |
ctx.timeout | max. 28 Tage |
levels.top / economy.top | max. 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.
- Error: Recht "dm" nicht erlaubt at index.js:58:15
- Zeitüberschreitung bei "message" (über 8 s)
- Panel updated in 1123581321
- Error: Recht "dm" nicht erlaubt
- Ticket #42 created
Was landet wo?
| Quelle | Sichtbar in | Wer sieht es |
|---|---|---|
Fehler in Handlern (throw, fehlgeschlagenes await) | Fehler auf diesem Server + Alle Logs | Server-Admins (erste Zeilen des Stacktrace) |
| Zeitüberschreitung (über 8 s) | Fehler auf diesem Server | Server-Admins |
console.log() | Alle Logs | Nur du (der Autor) |
console.error(), unbehandelte Fehler und Promises | Alle Logs (rot) | Nur du (der Autor) |
| Fehler beim Start / Syntaxfehler | Status Abgestürzt mit Meldung | Alle, 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.
Plugin reagiert nicht mehr (Endlosschleife?) – wurde neu gestartet.Häufige Fehlermeldungen
| Meldung | Ursache & Lösung |
|---|---|
Recht "roles" nicht erlaubt | Recht 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 Sekunden | tbot.every() braucht mindestens '1m' bzw. 60. |
Höchstens 10 Slash-Commands pro Plugin | Fasse 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.
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.
