# ⚽ Fußball Plugin — Vollständiges Minecraft Fußball-Minigame

Ein professionelles Fußball-Plugin für Spigot/Paper 1.21+

---

## 📦 Installation

1. **Java 21+** und **Spigot/Paper 1.21.x** benötigt
2. Plugin bauen: `mvn package` → `target/Fussball.jar`
3. JAR in den `/plugins/` Ordner deines Servers kopieren
4. Server (neu)starten
5. *(Optional)* [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) installieren für `%fussball_...%` Platzhalter

---

## 🎮 Features

| Feature | Beschreibung |
|---|---|
| ⚽ Echter Ball | ArmorStand mit Fußball-Textur, echten Physics & Reibung |
| 👥 Teams | Automatische Team-Zuweisung mit Auto-Balance (Rot vs. Blau) |
| 🥅 Tor-Erkennung | Region-basierte Tore mit Trajectory-Check |
| 🎉 Tor-Effekte | Feuerwerk, Titel, Action-Bar Tor-Replay, Sound |
| 📊 Scoreboard | Live-Spielstand, Zeit, Halbzeit-Anzeige, Team-Farbnamen |
| 🔴 BossBar | Timer mit Farbwechsel (grün→gelb→rot) + Spielstand |
| ⏸ Halbzeit | 30s Pause nach der 1. Halbzeit, danach 2. Halbzeit |
| ⏰ Verlängerung | 10 Minuten extra bei Unentschieden nach regulärer Zeit |
| 🥊 Elfmeterschießen | 5 Runden pro Team, Early-Termination, Sudden-Death |
| 💪 Aufladbarer Schuss | Shift halten = Power aufbauen (0–100%), Action-Bar zeigt Ladestand |
| 💬 Team-Chat | Nachrichten nur ans eigene Team, Zuschauer sehen alles |
| 👀 Zuschauer-Modus | Spiele zuschauen im Spectator-Mode mit BossBar & Scoreboard |
| 🏆 MVP-System | Bester Torschütze wird am Ende gekrönt |
| 📈 Persistente Stats | Tore, Schüsse, Siege, Niederlagen, Siegquote — serverübergreifend gespeichert |
| 🔢 Warteschlange | Automatische Queue wenn Arena voll |
| 🏷 PlaceholderAPI | `%fussball_goals%`, `%fussball_wins%` etc. für andere Plugins |
| 🚪 Schilder | Join-Schilder mit Live-Status für jede Arena |
| 🛡 Anti-Grief | Kein Block-Abbauen/-Platzieren, kein Item-Drop/-Pickup im Spiel |
| 💊 God-Mode | Spieler sterben nicht, Hunger eingefroren, Respawn an Team-Spawn |
| 🔧 Debug-Befehl | Region-Visualisierung, Ball-Position, Aus-Seite für Admins |

---

## 🔧 Arena Setup (Schritt für Schritt)

### 1. Arena erstellen
```
/fb create StadionXL
```

### 2. Grundpositionen setzen
Gehe jeweils an die gewünschte Stelle und führe den Befehl aus:

```
/fb setup StadionXL lobby       → Lobby-Wartebereich (Spieler landen hier beim Joinen/Verlassen)
/fb setup StadionXL center      → Mittelpunkt des Spielfeldes
/fb setup StadionXL ballspawn   → Wo der Ball erscheint (Anstoss-Punkt, Mitte)
/fb setup StadionXL redspawn    → Startposition rotes Team
/fb setup StadionXL bluespawn   → Startposition blaues Team
```

### 3. Tore definieren (je 2 diagonal gegenüberliegende Ecken)
```
# Rotes Tor
/fb setup StadionXL redgoalmin    → Untere Ecke des roten Tors
/fb setup StadionXL redgoalmax    → Obere gegenüberliegende Ecke

# Blaues Tor
/fb setup StadionXL bluegoalmin   → Untere Ecke des blauen Tors
/fb setup StadionXL bluegoalmax   → Obere gegenüberliegende Ecke
```

### 4. Spielfeld-Grenzen setzen *(optional, aber empfohlen)*
Ohne Feldgrenzen gibt es keine Aus-Erkennung (Einwurf/Ecke/Abstoß).
```
/fb setup StadionXL fieldmin    → Eine Ecke des Spielfelds
/fb setup StadionXL fieldmax    → Die gegenüberliegende Ecke
```

### 5. Spieler-Einstellungen anpassen *(optional)*
```
/fb setup StadionXL minplayers 2    → Mindestanzahl zum Starten (Standard: 2)
/fb setup StadionXL maxplayers 10   → Maximale Spielerzahl (Standard: 10)
/fb setup StadionXL duration 300    → Spielzeit in Sekunden, 1. + 2. Halbzeit zusammen (Standard: 300)
```

### 6. Setup überprüfen
```
/fb setup StadionXL info
```
Alle Pflichtfelder müssen **§a✔** zeigen. Erst dann ist die Arena spielbereit.

---

## 📋 Alle Commands

### Spieler-Commands
| Command | Beschreibung |
|---|---|
| `/fb join <arena>` | Einem Spiel beitreten (bei voller Arena → Warteschlange) |
| `/fb leave` | Spiel verlassen / Zuschauen beenden / Warteschlange verlassen |
| `/fb spectate <arena>` | Einem laufenden Spiel als Zuschauer beiwohnen |
| `/fb list` | Alle Arenen mit Status und Spieleranzahl anzeigen |
| `/fb stats [spieler]` | Eigene oder fremde Statistiken anzeigen |
| `/fb top [goals\|wins]` | Bestenliste der Top-Torschützen oder Top-Sieger |
| `/fb`, `/soccer` | Aliase für `/fussball` |

### Admin-Commands *(Berechtigung: `fussball.admin`)*
| Command | Beschreibung |
|---|---|
| `/fb create <name>` | Neue Arena erstellen |
| `/fb delete <name>` | Arena löschen |
| `/fb setup <arena> <option>` | Arena konfigurieren (siehe Setup-Guide) |
| `/fb setup <arena> info` | Alle gesetzten Positionen anzeigen |
| `/fb stop <arena>` | Laufendes Spiel sofort beenden |
| `/fb debug <arena>` | Tor-/Feld-Regionen und Ball-Position debuggen |

---

## 🎮 Spielablauf

```
Spieler joinen per Schild oder /fb join
    → Countdown startet (10 Sek.)
    → Spieler teleportieren zu Team-Spawns
    → Fußball erscheint in der Mitte

── 1. HALBZEIT ──────────────────────────────────────────
    Spieler rennen gegen den Ball → automatischer Kick
    Shift halten → Schuss lädt auf → loslassen = Powerschuss
    Ball ins Tor → Punkt! (Feuerwerk + Pause + Neuaufstellung)
    Bei Aus → Einwurf / Ecke / Abstoß je nach Situation

── HALBZEIT-PAUSE (30 Sek.) ─────────────────────────────
    Spielstand wird angezeigt, Spieler bleiben auf dem Feld

── 2. HALBZEIT ──────────────────────────────────────────
    Spielzeit läuft ab...

── BEI GLEICHSTAND: VERLÄNGERUNG (10 Min.) ──────────────
    Wer zuerst trifft, gewinnt (Golden Goal)
    Bei weiterem Gleichstand...

── ELFMETER-SCHIEßEN ────────────────────────────────────
    5 Schüsse pro Team (abwechselnd)
    Schütze hat 15 Sekunden pro Versuch
    Early-Termination wenn Ergebnis feststeht
    Dann: Sudden Death (je 1 Schuss) bis Entscheidung

── SPIELENDE ────────────────────────────────────────────
    Sieger + MVP werden bekannt gegeben
    Statistiken werden gespeichert
    Alle zurück zur Lobby
```

---

## 💪 Aufladbarer Schuss

| Aktion | Effekt |
|---|---|
| Rechtsklick auf Ball | Normaler Schuss |
| Linksklick auf Ball | Normaler Schuss |
| **Shift halten** (max 1.5s) | Schuss lädt auf |
| Shift loslassen | Schuss mit aufgebauter Power |
| 100% Ladung erreicht | Auto-Fire |

Die Action-Bar zeigt den Ladefortschritt:
```
⚽ Schuss-Power: ████████░░ 80%
```
Ab 70% Ladung erscheinen Feuer-Partikel am Ball. Volle Ladung = 3.8× normale Kraft + mehr Loft.

---

## 💬 Team-Chat

Spieler im Spiel schreiben automatisch nur ans eigene Team:
```
§c[ROT] §fSpielerName§7: Ich stehe frei links!
```
- **`!Nachricht`** → Global-Broadcast an alle Spieler im Spiel (nur Admins)
- Zuschauer sehen alle Team-Chats mit `[Zuschauer]`-Label

---

## 🚪 Join-Schilder erstellen

1. Schild platzieren
2. In die erste Zeile `[Fussball]` schreiben
3. In die zweite Zeile den Arena-Namen schreiben
4. Rechtsklick auf das Schild → Spiel beitreten

Das Schild zeigt automatisch den aktuellen Status:
```
[⚽]
StadionXL
§c● 4/10
Klick zum Joinen
```

Farb-Legende: `§a●` = Wartet · `§e●` = Startet · `§c●` = Läuft · `§d●` = Elfmeter · `§7●` = Endet

---

## 📈 Statistiken & Bestenliste

```
/fb stats               → Eigene Statistiken
/fb stats Notch         → Statistiken von "Notch"
/fb top goals           → Top 10 Torschützen
/fb top wins            → Top 10 nach Siegen
```

Gespeicherte Werte pro Spieler:
- ⚽ Tore · 👟 Schüsse · 🏆 Siege · ❌ Niederlagen · ➖ Unentschieden · 📊 Gespielte Spiele · 📈 Siegquote %

Alle Daten werden in `plugins/Fussball/stats.yml` dauerhaft gespeichert.

---

## 🏷 PlaceholderAPI

Wenn PlaceholderAPI installiert ist, sind folgende Platzhalter verfügbar:

| Platzhalter | Wert |
|---|---|
| `%fussball_goals%` | Tore gesamt |
| `%fussball_kicks%` | Schüsse gesamt |
| `%fussball_wins%` | Siege gesamt |
| `%fussball_losses%` | Niederlagen gesamt |
| `%fussball_draws%` | Unentschieden gesamt |
| `%fussball_games%` | Gespielte Spiele |
| `%fussball_winrate%` | Siegquote (z.B. `67.5`) |
| `%fussball_ingame%` | `true` / `false` |
| `%fussball_arena%` | Name der aktuellen Arena oder `–` |
| `%fussball_score%` | Aktueller Spielstand z.B. `2 : 1` oder `–` |

---

## 🔑 Berechtigungen

| Permission | Beschreibung | Standard |
|---|---|---|
| `fussball.admin` | Alle Admin-Commands | OP |
| `fussball.play` | Spielen, Zuschauen, Stats | Alle |

---

## 📁 Dateistruktur

```
plugins/Fussball/
├── config.yml      → Plugin-Einstellungen (Ball-Power, Defaults)
├── arenas.yml      → Gespeicherte Arenen (auto-generiert)
├── signs.yml       → Gespeicherte Join-Schilder (auto-generiert)
└── stats.yml       → Spieler-Statistiken (auto-generiert)
```

---

## 🏟 Tipps für ein gutes Spielfeld

- **Feldgröße:** Mindestens **30×20 Blöcke** empfohlen (größer = mehr Spaß)
- **Tore:** Ca. **5 Blöcke breit, 3 Blöcke hoch** (genug Platz für den ArmorStand-Ball)
- **Boden:** Gras, Terrakotta oder Smaragd-Blöcke für Optik
- **Begrenzung:** Zäune, Mauern oder Glas als Spielfeld-Rand
- **fieldmin/fieldmax immer setzen!** Sonst gibt es keinen Aus-Befehl (Einwurf/Ecke/Abstoß)
- **Lobby außerhalb** des Spielfelds platzieren, damit Spieler nach dem Spiel nicht auf dem Feld stehen

---

## ⚙ Kompatibilität

| Anforderung | Version |
|---|---|
| Spigot / Paper | **1.21.x** |
| Java | **21+** |
| PlaceholderAPI | optional, jede Version |

Mehrere Arenen gleichzeitig möglich. Jede Arena läuft komplett unabhängig.

---

## 🐛 Bekannte Eigenheiten

- Der Ball ist ein **ArmorStand** – er kann durch enge Durchgänge (< 1 Block) stecken bleiben. Tore daher mindestens **2 Blöcke breit** bauen.
- Spieler müssen **Adventure-Mode** haben – Commands die den Spielmodus ändern (z.B. durch andere Plugins) können das Spiel stören.
- Die Halbzeit teilt die `duration`-Einstellung in zwei Hälften. Wer 5 Minuten Gesamtspielzeit will, setzt `duration 300`.

---

*Erstellt mit ❤️ von M_Viper — viel Spaß beim Fußballspielen!*