# 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).