Triggers — passive Auto-Antworten ("Tags")

GrumpyTriggers lässt Admins Stichwörter definieren, auf die der Bot automatisch reagiert, sobald jemand sie in einer normalen Chat-Nachricht schreibt — ganz ohne Befehl. Dieses Muster ist von Carl-bot/YAGPDB bekannt und wird dort oft "Tags" genannt.

---

Der zentrale Unterschied zu Custom Commands

Das verwechseln viele zuerst, deshalb ganz deutlich:

	Trigger (/trigger)	Custom Command (/cc / /cmd)
Auslösung	Automatisch/passiv — feuert, sobald das Stichwort in einer normalen Nachricht auftaucht	Aktiv — User muss selbst /cmd <name> eintippen
Beispiel	User schreibt "wie lautet die serverip?" im Chat → Bot antwortet sofort	User tippt /cmd ip → Bot antwortet
Antwort-Typen	text, embed	text, embed, role-toggle
Cooldown	Ja, pro Trigger (siehe unten)	Nein

Kurz gesagt: Ein Trigger "lauscht" auf den Chat und springt selbstständig an, wenn ein Stichwort erkannt wird. Ein Custom Command dagegen tut gar nichts, bis ihn jemand aktiv per Slash-Command aufruft. Details zu Custom Commands stehen in GrumpyCommands.

---

Aktivierung

In configs/config.yml:

addons:
  triggers: true

Keine YAML-Konfigurationsdatei — Trigger liegen komplett in der Datenbank (TextTrigger-Tabelle). /trigger add/remove/list/info sind die einzige Schnittstelle.

---

Schritt-für-Schritt-Beispiel (auch für Einsteiger)

Ziel: Immer wenn jemand im Chat das Wort "serverip" schreibt, soll der Bot automatisch die Minecraft-Server-IP posten — ohne dass irgendjemand einen Befehl eingeben muss.

1. Slash-Command starten:

/trigger add

Discord öffnet nun ein Formular mit vier Pflichtfeldern. Diese trägst du so ein:

Feld	Eingabe	Erklärung
keyword	serverip	Das Stichwort, auf das reagiert werden soll. Wird automatisch klein geschrieben und getrimmt.
match-type	contains	Der Trigger soll auch feuern, wenn "serverip" nur irgendwo in der Nachricht vorkommt (z.B. "wie lautet die serverip?"). Bei exact müsste die ganze Nachricht exakt nur serverip lauten — das wäre hier zu streng.
type	text	Wir wollen eine einfache Text-Antwort, kein Embed.
response	Die Server-IP lautet: play.example.com (Version 1.21.x)	Der Text, den der Bot postet.

2. Abschicken. Der vollständige Aufruf sieht so aus:

/trigger add keyword: serverip match-type: contains type: text response: "Die Server-IP lautet: play.example.com (Version 1.21.x)"

3. Der Bot bestätigt (nur für dich sichtbar, ephemeral): ✅ Trigger "serverip" erstellt.

4. Testen: Schreib in irgendeinen Channel eine ganz normale Nachricht, z.B.:

Hey, was ist eigentlich die serverip hier?

Der Bot antwortet automatisch (als Reply auf diese Nachricht):

Die Server-IP lautet: play.example.com (Version 1.21.x)

Niemand musste /cmd oder sonst einen Befehl eingeben — das Stichwort im normalen Chat hat gereicht. Genau das ist der Kern eines Triggers.

5. Cooldown beachten: Schreibt jemand direkt danach nochmal "serverip", bleibt der Bot 15 Sekunden lang still (siehe Abschnitt Cooldown weiter unten) — so verhindert der Bot, dass der Chat mit wiederholten Antworten zugespammt wird.

---

Match-Typen: contains vs. exact

Match-Typ	Verhalten	Wann benutzen
contains	Feuert, wenn das Keyword irgendwo in der (kleingeschriebenen) Nachricht vorkommt	Der Normalfall — für Stichwörter, Fragen, beiläufige Erwähnungen
exact	Feuert nur, wenn die gesamte Nachricht (nach Trim + Kleinschreibung) exakt dem Keyword entspricht	Für kurze, eindeutige Kommandowörter, die nicht versehentlich in längeren Sätzen mitgetroffen werden sollen

Beispiele:

Keyword: "serverip", match-type: contains
→ "wie lautet die serverip?"        → feuert ✅
→ "SERVERIP bitte"                  → feuert ✅ (Groß/Klein egal)
→ "serverip"                        → feuert ✅

Keyword: "hi", match-type: exact
→ "hi"                              → feuert ✅
→ "hi zusammen"                     → feuert NICHT ❌ (nicht die ganze Nachricht)
→ "historisch gesehen..."           → feuert NICHT ❌

Keyword: "hi", match-type: contains
→ "historisch gesehen..."           → feuert ✅ (enthält "hi"!) — genau das will man bei kurzen
                                        Keywords oft NICHT, deshalb hier lieber exact wählen

Faustregel: Kurze, generische Wörter (2-3 Zeichen wie "hi", "ok") → exact, sonst drohen ungewollte Treffer mitten in anderen Wörtern. Längere, spezifischere Stichwörter (wie "serverip", "discord-link") → contains, damit sie auch in ganzen Sätzen erkannt werden.

---

Antwort-Typen

text

Plain-Text-Antwort mit Placeholder-Support (gleiche Placeholder wie bei Custom Commands, z.B. %user_mention%, %user_name%).

/trigger add keyword: regeln match-type: contains type: text response: "%user_mention%, bitte lies dir die Regeln in #regeln durch!"

embed

JSON-definiertes Embed — genau wie bei Custom Commands werden ausschließlich title, description und color aus dem JSON übernommen, alle anderen Felder werden ignoriert (Sicherheits-Constraint).

/trigger add keyword: discord match-type: exact type: embed response: '{"title":"Discord","description":"Wir sind hier: https://discord.gg/example","color":"#5865F2"}'

Ist das JSON ungültig oder kein Objekt, lehnt /trigger add die Erstellung sofort mit Fehlermeldung ab.

---

Warum es KEINEN role-toggle-Antworttyp gibt

Bei Custom Commands (/cc) gibt es role-toggle, bei Triggern bewusst nicht. Grund: Ein Trigger feuert passiv, ausgelöst durch reinen Chat-Text — niemand muss aktiv etwas aufrufen. Würde ein Trigger automatisch eine Rolle vergeben, könnte praktisch jede Nachricht, die zufällig das Keyword enthält, unbeabsichtigt Rollen verteilen oder entfernen. Das wäre eine klassische Privilegien-Eskalations-Lücke: Anders als bei /cmd, wo der User bewusst und gezielt einen Befehl ausführt, hat der User bei Triggern oft gar nicht die Absicht, irgendetwas "auszulösen" — er schreibt einfach eine normale Nachricht. Deshalb bietet /trigger add nur text und embed als Antwort-Typen an; für Self-Assign-Rollen bleibt weiterhin /cc add type: role-toggle der richtige Weg (siehe GrumpyCommands).

---

Cooldown

Jeder Trigger hat einen Cooldown von 15 Sekunden (Standardwert, aktuell nicht pro Trigger konfigurierbar). Solange der Cooldown läuft, feuert der Trigger nicht erneut — auch wenn das Keyword in der Zwischenzeit mehrfach vorkommt. Das verhindert, dass ein belebter Channel durch wiederholtes Erwähnen des Stichworts mit Bot-Antworten zugespammt wird.

Der Cooldown gilt pro Trigger serverweit, nicht pro User — feuert Trigger A, ist A für alle 15 Sekunden still, unabhängig davon, wer als nächstes das Keyword schreibt.

---

Server-Limit

Pro Server sind maximal 50 Trigger erlaubt (MAX_TRIGGERS_PER_GUILD im Code). Ist das Limit erreicht, lehnt /trigger add weitere Erstellungen mit einer Fehlermeldung ab, bis ein bestehender Trigger gelöscht wird.

---

Commands

Für alle User

Command	Funktion
/trigger list	Zeigt alle Trigger des Servers (Keyword, Match-Typ, Antwort-Typ, Verwendungszähler) als Embed. Lange Listen werden gekürzt und mit …und N weitere ergänzt.
/trigger info <keyword>	Details zu einem Trigger: Match-Typ, Antwort-Typ, Verwendungen, Ersteller, Response-Inhalt. Autocomplete schlägt vorhandene Keywords vor.

Für Admins (Manage Guild / "Server verwalten")

Command	Funktion
/trigger add <keyword> <match-type> <type> <response>	Neuen Trigger erstellen
/trigger remove <keyword>	Trigger löschen (Autocomplete für Keyword)

Aufrufbeispiele:

/trigger add keyword: serverip match-type: contains type: text response: "play.example.com"
/trigger remove keyword: serverip
/trigger list
/trigger info keyword: serverip

Berechtigung: add und remove erfordern Manage Guild. Ohne diese Berechtigung antwortet der Bot mit 🚫 Du brauchst die Berechtigung "Server verwalten". list und info sind für alle Server-Mitglieder nutzbar.

---

Sonstiges

• Keyword-Normalisierung: Beim Anlegen wird das Keyword automatisch getrimmt, kleingeschrieben und auf 200 Zeichen begrenzt.
• Eindeutig pro Server: Ein doppeltes Keyword wird mit ❌ Ein Trigger für "<keyword>" existiert bereits. abgelehnt.
• Mention-Safety: Alle Trigger-Antworten nutzen allowedMentions: { parse: [] } — kein @everyone/@here, selbst wenn im Response-Text enthalten.
• In-Memory-Cache: Trigger werden bei jeder Änderung neu in einen internen Cache geladen, damit das Matching pro eingehender Nachricht schnell bleibt, ohne bei jeder Nachricht die Datenbank abzufragen.
• Bot-Nachrichten ignoriert: Trigger feuern nie auf Nachrichten von Bots (auch nicht auf eigene).