MClogger/README.md

# MCLogger

**Minecraft 1.20–1.21 · Paper + Velocity · MariaDB · Flask-Admin**  
Autor: **SimolZimol**

Umfassendes Logging-System für Minecraft-Netzwerke. Alle relevanten Events werden asynchron in einer MariaDB-Datenbank gespeichert und über ein modernes Flask-Webinterface auswertbar.

---

## Projektstruktur

```
Log/
├── database/
│   └── schema.sql              ← MariaDB-Schema (einmalig ausführen)
│
├── paper-plugin/               ← Maven-Projekt für Paper 1.20-1.21
│   ├── pom.xml
│   └── src/main/
│       ├── java/de/simolzimol/mclogger/paper/
│       │   ├── PaperLoggerPlugin.java
│       │   ├── database/DatabaseManager.java
│       │   └── listeners/
│       │       ├── PlayerSessionListener.java
│       │       ├── PlayerChatCommandListener.java
│       │       ├── PlayerDeathListener.java
│       │       ├── PlayerMiscListener.java
│       │       ├── BlockListener.java
│       │       ├── EntityListener.java
│       │       ├── InventoryListener.java
│       │       └── WorldListener.java
│       └── resources/
│           ├── plugin.yml
│           └── config.yml
│
├── velocity-plugin/            ← Maven-Projekt für Velocity 3.x
│   ├── pom.xml
│   └── src/main/
│       ├── java/de/simolzimol/mclogger/velocity/
│       │   ├── VelocityLoggerPlugin.java
│       │   ├── database/VelocityDatabaseManager.java
│       │   └── listeners/VelocityEventListener.java
│       └── resources/
│           └── velocity-config.yml
│
└── web/                        ← Python Flask Admin-Interface
    ├── app.py
    ├── config.py
    ├── requirements.txt
    ├── templates/
    │   ├── base.html
    │   ├── login.html
    │   ├── dashboard.html
    │   ├── players.html
    │   ├── player_detail.html
    │   ├── chat.html
    │   ├── commands.html
    │   ├── blocks.html
    │   ├── deaths.html
    │   ├── proxy.html
    │   ├── sessions.html
    │   ├── server_events.html
    │   └── _pagination.html
    └── static/
        ├── css/style.css
        └── js/main.js
```

---

## Was wird geloggt?

### Paper-Server
| Kategorie | Events |
|-----------|--------|
| **Sessions** | Login, Logout, Kick (+ IP, Client-Version, Sprache) |
| **Chat** | Alle Chat-Nachrichten mit Welt und Server |
| **Commands** | Alle Spieler-Befehle mit Position |
| **Tode** | Ursache, Mörder, verlorene Items, XP-Level |
| **Respawn** | Bett / Ankerpunkt / Normalrespawn |
| **Teleport** | Alle Ursachen (Portal, Command, Plugin usw.) |
| **Gamemode** | Wechsel mit Ursache |
| **Level/XP** | Level-Änderungen |
| **Blöcke** | Break, Place, Ignite, Burn, Explode + Werkzeug, SilkTouch |
| **Schilder** | Alle Sign-Änderungen mit Inhalt |
| **Entities** | Spawn, Tod, Schaden (durch Spieler), Zähmen, Züchten, Explosion |
| **PvP** | Schaden zwischen Spielern |
| **Inventar** | Item aufheben/fallenlassen, Crafting, Verzauberung, Amboss, Handel |
| **Welt** | Wetter, Donner, Portal, Baum-/Pilzwachstum, Welt-Load/Unload |
| **Server** | Start, Stop, Player-Join, Player-Quit, Kick |
| **Diverses** | Bett betreten/verlassen, Hand-Item-Wechsel, Angeln, Schlafen, Entity-Interaktion, Welt-Wechsel |

### Velocity-Proxy
| Kategorie | Events |
|-----------|--------|
| **Verbindungen** | Login (+ IP, Protocol-Version, Client-Brand, Ping) |
| **Disconnect** | Grund + Sitzungsdauer |
| **Server-Wechsel** | Von → Nach-Server |
| **Chat** | Proxy-Level-Chat |
| **Commands** | Proxy-Level-Commands |
| **Proxy** | Start / Stop |

---

## Voraussetzungen

- **Java 17+**
- **Maven 3.8+**
- **MariaDB 10.6+** / MySQL 8+
- **Paper 1.20–1.21**
- **Velocity 3.x**
- **Python 3.10+**

---

## 1. Datenbank einrichten

```sql
-- Als root in MariaDB:
SOURCE /pfad/zu/database/schema.sql;

-- Benutzer anlegen:
CREATE USER 'mclogger'@'%' IDENTIFIED BY 'sicheres_passwort';
GRANT ALL PRIVILEGES ON mclogger.* TO 'mclogger'@'%';
FLUSH PRIVILEGES;
```

---

## 2. Paper-Plugin bauen & installieren

```bash
cd paper-plugin
mvn clean package -q
cp target/mclogger-paper-1.0.0.jar /dein/paper-server/plugins/
```

Konfiguration bearbeiten (`plugins/MCLogger/config.yml`):

```yaml
server:
  name: "survival-01"    # eindeutiger Name

database:
  host: "localhost"
  port: 3306
  database: "mclogger"
  username: "mclogger"
  password: "sicheres_passwort"
```

Server neu starten.

---

## 3. Velocity-Plugin bauen & installieren

```bash
cd velocity-plugin
mvn clean package -q
cp target/mclogger-velocity-1.0.0.jar /dein/velocity-proxy/plugins/
```

Konfiguration bearbeiten (`plugins/mclogger-velocity/velocity-config.yml`):

```yaml
proxy:
  name: "proxy-01"

database:
  host: "localhost"
  port: 3306
  database: "mclogger"
  username: "mclogger"
  password: "sicheres_passwort"
```

Proxy neu starten.

---

## 4. Flask-Webinterface starten

```bash
cd web

# Python-Umgebung (empfohlen)
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # Linux/Mac

pip install -r requirements.txt

# Umgebungsvariablen setzen (oder config.py direkt bearbeiten)
set MCLOGGER_DB_HOST=localhost
set MCLOGGER_DB_PASSWORD=sicheres_passwort
set MCLOGGER_ADMIN_PASSWORD=admin_passwort
set MCLOGGER_SECRET_KEY=zufaelliger_32_zeichen_schluessel

python app.py
```

Webinterface öffnen: **http://localhost:5000**

### Für Produktion (Linux mit Gunicorn)

```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

Oder als systemd-Service:

```ini
[Unit]
Description=MCLogger Web

[Service]
WorkingDirectory=/opt/mclogger/web
Environment=MCLOGGER_DB_HOST=localhost
Environment=MCLOGGER_DB_PASSWORD=sicheres_passwort
Environment=MCLOGGER_ADMIN_PASSWORD=admin_passwort
Environment=MCLOGGER_SECRET_KEY=...
ExecStart=/opt/mclogger/web/venv/bin/gunicorn -w 2 -b 127.0.0.1:5000 app:app
Restart=always

[Install]
WantedBy=multi-user.target
```

---

## Webinterface-Features

| Seite | Beschreibung |
|-------|-------------|
| **Dashboard** | Live-Statistiken, Online-Spieler, Aktivitäts-Charts, Top-Playtime |
| **Spieler** | Suchbare Spielerliste mit Profil-Details |
| **Spielerprofil** | Sessions, Chat, Commands, Tode, Teleports, Stats, Proxy-Events in Tabs |
| **Sessions** | Alle Login-/Logout-Sitzungen mit Filterfunktion |
| **Chat** | Volltext-Suche in allen Chat-Nachrichten |
| **Commands** | Alle ausgeführten Befehle |
| **Block-Events** | Break/Place/Ignite usw. mit Positions-Info |
| **Tode** | Tode mit Ursache, Mörder und Todes-Meldung |
| **Proxy-Events** | Login, Disconnect, Server-Wechsel usw. |
| **Server-Events** | Start/Stop und reine Server-Ereignisse |

---

## Konfigurationsvariablen (Umgebungsvariablen)

| Variable | Standard | Beschreibung |
|----------|----------|-------------|
| `MCLOGGER_DB_HOST` | `localhost` | MariaDB-Host |
| `MCLOGGER_DB_PORT` | `3306` | MariaDB-Port |
| `MCLOGGER_DB_USER` | `mclogger` | DB-Benutzer |
| `MCLOGGER_DB_PASSWORD` | *(leer)* | DB-Passwort |
| `MCLOGGER_DB_NAME` | `mclogger` | Datenbankname |
| `MCLOGGER_HOST` | `0.0.0.0` | Webserver-Bind |
| `MCLOGGER_PORT` | `5000` | Webserver-Port |
| `MCLOGGER_ADMIN_USER` | `admin` | Admin-Login |
| `MCLOGGER_ADMIN_PASSWORD` | *(leer)* | Admin-Passwort |
| `MCLOGGER_SECRET_KEY` | *(unsicher)* | Flask Session-Key |

---

## Performance-Hinweise

- Alle Datenbank-Writes erfolgen **asynchron** → kein Tick-Lag
- HikariCP Connection-Pool voreingestellt auf 10 (Paper) / 5 (Velocity)
- Entity-Spawn-Logging ist standardmäßig **deaktiviert** (sehr viele Events)
- Block-Events können bei Farms sehr viele Einträge erzeugen → ggf. `blocks-break-only: true`
- Ein regelmäßiges DB-Backup empfiehlt sich (Events wachsen schnell)
- MariaDB: Index-Tuning für `timestamp`-Spalten ist bereits im Schema enthalten

---

## Lizenz

MIT – Frei verwendbar, SimolZimol als Autor nennen.