Modulsystem (Cogs)

ArcBot ist in einer modularen Architektur aufgebaut. Jede Funktionalität ist ein eigenständiges Modul (Cog), das unabhängig pro Server ein- und ausgeschaltet werden kann.

Was ist ein Cog?

Cog (Kurzform von "cogwheel" — Zahnrad) ist ein eigenständiges Bot-Modul, das Folgendes enthält:

• Slash-Befehle (z.B. /ban, /poll)
• Event-Listener (z.B. Beitritt eines Mitglieds)
• Zyklische Aufgaben (z.B. Prüfung abgelaufener Umfragen)
• In der Datenbank gespeicherte Konfiguration

Verfügbare Module

Administration

Modul	Beschreibung
Settings	Servereinstellungen (Sprache, Farbe, Dashboard Users) — immer aktiviert
Moderation	Ban, Kick, Mute, Warn, Clear, Setnick, Role

Community

Modul	Beschreibung
Welcome	Willkommens- und Abschiedsnachrichten
Reaction Roles	Self-Assign-Rollen über Buttons, Dropdown, Reaktionen
Suggestions	Vorschlagssystem mit Abstimmung
Polls	Umfragen mit Buttons und Timer
Duel Reminder	Tägliche Erinnerungen an Duellstrategien
Schedule Events	Geplante Ereignisse mit Erinnerungen

Werkzeuge

Modul	Beschreibung
Logs	Konfigurierbare Aktionsprotokollierung
Translation	Nachrichtenübersetzung (DeepL) und Audio-Transkription (Groq Whisper)
Message Builder	Erstellung und Versand von Embeds aus Vorlagen

Dark War Survival

Modul	Beschreibung
Alliances	Allianz-Verwaltung mit Rängen R1–R5
Presidents	Server-Präsidentensystem
Armory	Waffenkammer-Rotation mit Allianz-Zuweisungen

Module ein- und ausschalten

Über das Dashboard

1. Öffnen Sie Dashboard → Ihr Server
2. Finden Sie im Modulraster die entsprechende Kachel
3. Klicken Sie auf den Schalter (Toggle)
4. Fertig — die Änderung ist sofort wirksam

Was passiert nach der Aktivierung?

1. Die Konfiguration wird in der Datenbank gespeichert (enabled_cogs)
2. Der Bot erkennt die Änderung innerhalb von 5 Sekunden (Config Polling)
3. Die mit dem Modul verbundenen Befehle werden mit der Discord-API synchronisiert
4. Die Befehle erscheinen im Slash-Menü des Servers

Was passiert nach der Deaktivierung?

1. Das Modul wird aus enabled_cogs entfernt
2. Der Bot erkennt die Änderung innerhalb von 5 Sekunden
3. Die Befehle verschwinden aus dem Slash-Menü
4. Events (z.B. on_member_join für Welcome) reagieren nicht mehr
5. Die Modulkonfiguration wird nicht gelöscht — nach erneuter Aktivierung bleiben alle Einstellungen erhalten

tipp

Das Deaktivieren eines Moduls löscht nicht dessen Konfiguration. Sie können ein Modul sicher "vorübergehend" deaktivieren und es mit den gleichen Einstellungen wieder aktivieren.

Config Polling — Wie erkennt der Bot Änderungen?

ArcBot verwendet einen Polling-Mechanismus zur Konfigurationssynchronisierung:

1. Alle 5 Sekunden prüft der Bot in der Datenbank, ob sich die Spalte updated_at einer Konfiguration geändert hat
2. Bei erkannter Änderung wird der Cache im Speicher aktualisiert
3. Wenn sich die Liste enabled_cogs geändert hat, wird das Ereignis on_config_update ausgelöst
4. Dieses Ereignis bewirkt die Neusynchronisierung der Befehle für den jeweiligen Server

Dashboard → Benutzer klickt Toggle
    ↓
API → Aktualisiert `enabled_cogs` + `updated_at` in DB
    ↓ (max 5 Sekunden)
Bot → Config Polling erkennt Änderung von `updated_at`
    ↓
Bot → Aktualisiert Cache, löst `on_config_update` aus
    ↓
Bot → Synchronisiert Befehle für den Server
    ↓
Discord → Befehle erscheinen / verschwinden im Slash-Menü

Propagationszeit

Zwischen dem Klick auf den Toggle im Dashboard und dem Erscheinen des Befehls auf dem Server vergehen in der Regel 5–10 Sekunden. Dies ist die Zeit für: DB-Speicherung + Polling + Sync mit Discord-API.

Modul "Settings" — Pseudo-Cog

Die Kachel Settings im Dashboard ist besonders:

• Hat keinen Schalter — ist immer aktiviert
• Enthält keine Slash-Befehle
• Verwaltet Servereinstellungen: Sprache, Standard-Embed-Farbe, Liste der dashboard_users

Schutz vor Ausführung deaktivierter Befehle

Selbst wenn ein Befehl nach der Deaktivierung des Moduls im Discord-Cache verbleiben sollte, blockiert der Decorator @guild_cog_enabled dessen Ausführung:

1. Prüft enabled_cogs aus dem ConfigManager-Cache
2. Wenn das Modul nicht aktiviert ist → CheckFailure mit übersetzter Meldung
3. Der Benutzer sieht eine ephemerale Nachricht "Dieses Modul ist deaktiviert"

Modulkonfiguration

Jedes Modul speichert seine Konfiguration in der Spalte cog_settings (JSONB) der Tabelle guild_configs:

{
  "moderation": {
    "moderation_roles": ["123456789"],
    "warning_threshold": 3,
    "dm_on_action": true,
    "auto_delete_warnings_days": 0
  },
  "welcome": {
    "welcome": { "enabled": true, "channel_id": "...", "type": "embed", ... },
    "goodbye": { "enabled": true, "channel_id": "...", ... }
  },
  "logs": {
    "moderation": { "enabled": true, "channel_id": "...", "color": "#5865F2" },
    "welcome": { "enabled": false, "channel_id": null, "color": "#22C55E" }
  }
}

Konfiguration bearbeiten

1. Klicken Sie im Dashboard auf Edit bei der Modulkachel
2. Ändern Sie die Einstellungen
3. Die UnsavedBar erscheint am unteren Bildschirmrand
4. Klicken Sie auf Save zum Speichern oder Cancel zum Rückgängigmachen

warnung

Schließen Sie die Seite nicht ohne zu speichern! Das Dashboard warnt Sie mit einer blinkenden Leiste, aber die Änderungen gehen verloren.

Von Modulen benötigte Discord-Berechtigungen

Jedes Modul deklariert eine Liste von Discord-Berechtigungen, die es für seinen Betrieb benötigt:

Modul	Benötigte Bot-Berechtigungen
Moderation	ban_members, kick_members, moderate_members, manage_messages, manage_nicknames, manage_roles
Welcome	send_messages, embed_links
Logs	send_messages, embed_links
Reaction Roles	manage_roles, send_messages, add_reactions
Suggestions	send_messages, embed_links, create_public_threads, add_reactions
Polls	send_messages, embed_links
Message Builder	send_messages, embed_links
Translation	— (erfordert DeepL API-Schlüssel)
Alliances	manage_roles
Presidents	manage_roles
Armory	manage_roles
Duel Reminder	send_messages
Schedule Events	send_messages, manage_messages

tipp

Wenn der Bot nicht über die erforderliche Berechtigung verfügt, endet die Aktion mit dem Fehler "Missing permission". Stellen Sie sicher, dass die Bot-Rolle die entsprechenden Berechtigungen auf den Kanälen hat, auf denen sie agieren soll.