166 lines
4.4 KiB
Markdown
166 lines
4.4 KiB
Markdown
# MuteCounter — Discord Bot
|
||
|
||
Ein Discord-Bot der Self-Mutes in Voice-Channels zählt, ein Leaderboard führt und Meilensteine feiert.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
| Feature | Beschreibung |
|
||
|---|---|
|
||
| **Mute-Tracking** | Zählt Mikrofon-Mutes (🎙️) und Deaf-Mutes (🔇) getrennt |
|
||
| **Leaderboard** | All-Time, wöchentlich und monatlich per `/mutescore` |
|
||
| **Nutzer-Fokus** | Rang eines bestimmten Nutzers mit Kontext anzeigen |
|
||
| **Persönliche Stats** | Rekordtag, Mute-Ratio, Tages-/Wochen-/Monatswerte |
|
||
| **Meilensteine** | Automatische Channel-Nachricht bei 10 / 25 / 50 / 100 / 250 / 500 / 1000 Mutes |
|
||
| **Rang-Rollen** | Automatisch zugewiesene Rollen je nach Mute-Anzahl |
|
||
| **Overtake-Alert** | Benachrichtigung wenn jemand auf dem Leaderboard überholt wird |
|
||
| **Weekly-Posting** | Automatische Wochenzusammenfassung jeden Montag |
|
||
| **Mute-Ratio** | Mutes pro Stunde Voice-Zeit (AFK-Channel ausgeschlossen) |
|
||
| **Persistenz** | Alle Daten werden in `data.json` gespeichert |
|
||
|
||
---
|
||
|
||
## Voraussetzungen
|
||
|
||
- Python 3.10 oder neuer
|
||
- Ein Discord-Bot-Token ([Discord Developer Portal](https://discord.com/developers/applications))
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
**1. Abhängigkeiten installieren**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
**2. Umgebungsvariablen konfigurieren**
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
Dann `.env` öffnen und die Werte eintragen:
|
||
```env
|
||
DISCORD_TOKEN=dein_bot_token_hier
|
||
MILESTONE_CHANNEL_ID=1234567890123456789 # optional
|
||
```
|
||
|
||
**3. Bot starten**
|
||
```bash
|
||
python bot.py
|
||
```
|
||
|
||
> Slash-Commands werden beim ersten Start synchronisiert. Es kann bis zu einer Stunde dauern, bis sie Discord-weit erscheinen.
|
||
|
||
---
|
||
|
||
## Konfiguration
|
||
|
||
| Variable | Pflicht | Beschreibung |
|
||
|---|---|---|
|
||
| `DISCORD_TOKEN` | ✅ | Bot-Token aus dem Developer Portal |
|
||
| `MILESTONE_CHANNEL_ID` | ❌ | Channel-ID für Meilensteine, Overtakes & Weekly-Posting. Fallback: Server-Systemchannel |
|
||
|
||
**Channel-ID kopieren:** Rechtsklick auf Channel → *ID kopieren* (Entwicklermodus muss aktiviert sein: Einstellungen → Erweitert → Entwicklermodus)
|
||
|
||
---
|
||
|
||
## Befehle
|
||
|
||
### `/mutescore`
|
||
Zeigt das Mute-Leaderboard.
|
||
|
||
| Parameter | Typ | Standard | Beschreibung |
|
||
|---|---|---|---|
|
||
| `period` | Auswahl | All-Time | `Gesamt`, `Diese Woche` oder `Diesen Monat` |
|
||
| `limit` | Zahl | 10 | Anzahl der angezeigten Plätze (1–25) |
|
||
| `user` | @Mention | — | Fokus-Ansicht für einen bestimmten Nutzer |
|
||
|
||
**Beispiele:**
|
||
```
|
||
/mutescore
|
||
/mutescore period:Diese Woche limit:5
|
||
/mutescore user:@Max
|
||
/mutescore user:@Max period:Diesen Monat
|
||
```
|
||
|
||
---
|
||
|
||
### `/mymutes`
|
||
Zeigt die eigenen Mute-Stats (nur für den Nutzer selbst sichtbar).
|
||
|
||
```
|
||
📊 All-Time 🎙️ 12x Mikro | 🔇 5x Deaf | 17x gesamt
|
||
📅 Diese Woche 4x
|
||
🗓️ Diesen Monat 11x
|
||
☀️ Heute 2x
|
||
🏆 Rekordtag 15.01.2026 mit 6x
|
||
⚡ Mute-Ratio 2.4 Mutes/Stunde (Voice-Zeit: 7h 5min)
|
||
🏷️ Rang 💯 Mute-Veteran
|
||
```
|
||
|
||
---
|
||
|
||
## Rang-Rollen
|
||
|
||
Rollen werden automatisch erstellt und zugewiesen. Bei einem Aufstieg wird die alte Rolle entfernt.
|
||
|
||
| Mutes | Rolle |
|
||
|---|---|
|
||
| 10 | 🔇 Stummer Gast |
|
||
| 25 | 😶 Gelegentlicher Muter |
|
||
| 50 | 🤫 Fortgeschrittener Schweiger |
|
||
| 100 | 💯 Mute-Veteran |
|
||
| 250 | 🏅 Schweige-Meister |
|
||
| 500 | 🎖️ Elite-Muter |
|
||
| 1000 | 👑 Mute-König |
|
||
|
||
---
|
||
|
||
## Bot-Berechtigungen
|
||
|
||
Folgende Berechtigungen werden benötigt:
|
||
|
||
| Berechtigung | Wozu |
|
||
|---|---|
|
||
| `View Channels` | Channels sehen |
|
||
| `Send Messages` | Nachrichten & Embeds senden |
|
||
| `Embed Links` | Embeds posten |
|
||
| `Manage Roles` | Rang-Rollen erstellen & vergeben |
|
||
| `Connect` | Voice-Channels sehen (für AFK-Erkennung) |
|
||
|
||
**Privileged Gateway Intents** (im Developer Portal aktivieren):
|
||
- `Server Members Intent`
|
||
- `Voice State Intent` (standardmäßig aktiv)
|
||
|
||
**Einlade-Scopes:** `bot` + `applications.commands`
|
||
|
||
---
|
||
|
||
## Datenspeicherung
|
||
|
||
Alle Daten werden lokal in `data.json` gespeichert.
|
||
|
||
```
|
||
MuteCounter/
|
||
├── bot.py
|
||
├── data.json # automatisch erstellt
|
||
├── .env # nicht in Git einchecken!
|
||
├── .env.example
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
> `data.json` und `.env` sollten **nicht** in ein öffentliches Repository eingecheckt werden.
|
||
|
||
---
|
||
|
||
## Mute-Typen
|
||
|
||
| Aktion in Discord | Typ | Symbol |
|
||
|---|---|---|
|
||
| Mikrofon-Button drücken | `mic` | 🎙️ |
|
||
| Deaf-Button drücken (taubstellen) | `deaf` | 🔇 |
|
||
|
||
Wenn sich jemand taubstellt, wird nur der Deaf-Counter erhöht (nicht doppelt gezählt).
|