Füge umfassende Dokumentation hinzu: Erstelle README.md mit Funktionen, Installationsanweisungen, Befehlen und Bot-Berechtigungen.
This commit is contained in:
165
README.md
Normal file
165
README.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user