Fussball/README.md

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

Ein professionelles Fußball-Plugin für Spigot/Paper 1.21+ mit echtem Ball-Physics, Spielregeln und persistenten Statistiken.

---

## 📦 Installation

1. **Java 21+** und **Spigot/Paper 1.21.x** wird 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, Physik & Reibung |
| 👥 Teams | Automatische Team-Zuweisung mit Auto-Balance (Rot vs. Blau) |
| 🙋 Teamwahl | Spieler können per `/fb team rot|blau` ihr Wunsch-Team wählen (vor Spielstart) |
| 👕 Team-Rüstung | Farbige Leder-Rüstung mit **Trikot-Nummer** (#1, #2, …) auf dem Brustpanzer |
| 🥅 Tor-Erkennung | Region-basierte Tore mit Trajectory-Check (Schritt-für-Schritt Bahnverfolgung) |
| 🎉 Tor-Effekte | Feuerwerk, Titel, Action-Bar Tor-Replay, Sound |
| 🎶 Stadionatmosphäre | Jubel-Sounds & mehrfache Feuerwerke beim Tor; Enttäuschungs-Sound für das andere Team |
| 📊 Scoreboard | Live-Spielstand, Zeit, Halbzeit-Anzeige, Ballbesitz, farbige Spielernamen über Kopf |
| 🔴 BossBar | Timer mit Farbwechsel (grün→gelb→rot) + Spielstand, Nachspielzeit in Sekunden |
| ⏸ Halbzeit | 30s Pause nach der 1. Halbzeit + Seitenwechsel, danach 2. Halbzeit |
| ⏰ Verlängerung | 10 Minuten extra bei Gleichstand (Golden Goal – wer zuerst trifft gewinnt) |
| 🥊 Elfmeterschießen | 5 Runden pro Team, Early-Termination, Sudden Death |
| 💪 Aufladbarer Schuss | Shift halten = Power aufbauen (0–100%), Action-Bar zeigt Ladestand |
| 🔁 Aus-Erkennung | Einwurf / Ecke / Abstoß je nach Situation und letzter Berührung |
| ⭕ Anstoß-Kreis | Gegner werden beim Anstoß aus dem Kreis (9,15m) herausgeschoben |
| 🚩 Abseits | Automatische Abseits-Erkennung mit Freistoß-Folge |
| 🤲 Torwart-Mechanik | Ball halten, fallen lassen oder werfen; Rückpass-Regel wird durchgesetzt |
| ✋ Handball | Kauernder Spieler berührt Ball auf Armhöhe = Freistoß/Elfmeter |
| ⚠️ Foul-Erkennung | PvP-Angriffe = Foul; Gelbe/Rote Karte; Foul im Strafraum = Elfmeter |
| 🎯 Freistoß | Mindestabstand für Gegner wird aktiv durchgesetzt (Schubsen) |
| ⬇ Drop Ball | Admin kann per `/fb dropball` einen Schiedsrichterball ausführen |
| 🦾 Kopfball | Automatische Erkennung wenn Spieler in der Luft den Ball auf Kopfhöhe berührt |
| 📏 Kurz-/Langpass | Pässe über 20 Blöcke werden als Langpass in der Action-Bar angezeigt |
| 📏 Eigentor-Erkennung | Wird separat gewertet und in Statistik gespeichert |
| 🏅 Assist-Erkennung | Vorlage (zweite Berührung vor dem Tor) wird automatisch erkannt |
| ⏱ Nachspielzeit | Akkumuliert bei Toren, Fouls, Karten und Aus-Situationen; Anzeige in Sekunden |
| 📈 Ballbesitz | Live-Tracking im Scoreboard + Anzeige im Matchbericht am Spielende |
| 🏟 Strafraum | Auto-berechnet aus Tor-Koordinaten oder manuell setzbar |
| 📋 Matchbericht | Tore, Karten, Fouls, Abseits, Ballbesitz und MVP am Spielende |
| 🏆 MVP-System | Bester Torschütze wird nach dem Spiel bekannt gegeben |
| 📈 Persistente Stats | Tore, Eigentore, Vorlagen, Schüsse, Siege, Niederlagen, Siegquote |
| 📋 Match-History | Letzte 50 Spiele dauerhaft gespeichert, abrufbar per `/fb history` |
| 🔢 Warteschlange | Automatische Queue wenn Arena voll; nächster Spieler rückt nach |
| 👀 Zuschauer-Modus | Sichtbarer Zuschauer-Bereich außerhalb des Feldes mit BossBar und Scoreboard |
| 💬 Team-Chat | Nachrichten nur ans eigene Team; Admins können global broadcasten |
| 🚪 Schilder | Join-Schilder und Zuschauer-Schilder mit Live-Status |
| 🏷 PlaceholderAPI | `%fussball_goals%`, `%fussball_wins%` etc. für andere Plugins |
| 🛡 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 (auch Anstoß-Kreis-Zentrum)
/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
/fb setup StadionXL spectatorspawn → Zuschauer-Spawn (optionaler fester Standpunkt für Zuschauer)
```

### 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
```

> **Hinweis:** Tor-Erkennung prüft X, Y und Z (3D). Die Tore müssen mindestens so hoch sein wie der Ball (ArmorStand-Helm) fliegen kann – mindestens 2 Blöcke Höhe empfohlen.

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

### 5. Strafräume setzen *(optional)*
Wenn nicht gesetzt, werden die Strafräume **automatisch** aus den Tor-Koordinaten berechnet (Tiefe und Rand sind in `config.yml` einstellbar). Für mehr Kontrolle können sie manuell gesetzt werden:
```
/fb setup StadionXL redpenaltymin    → Untere Ecke des roten Strafraums
/fb setup StadionXL redpenaltymax    → Obere gegenüberliegende Ecke
/fb setup StadionXL bluepenaltymin   → Untere Ecke des blauen Strafraums
/fb setup StadionXL bluepenaltymax   → Obere gegenüberliegende Ecke
```

### 6. Elfmeter-Punkte setzen *(optional)*
Wenn nicht gesetzt, wird `ballspawn` als Elfmeter-Ausführungsort verwendet. Für realistische Strafstoß-Positionen:
```
/fb setup StadionXL redpenaltyspot    → Elfmeter-Punkt vor dem roten Tor
/fb setup StadionXL bluepenaltyspot   → Elfmeter-Punkt vor dem blauen Tor
```

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

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

**Pflichtfelder:** `lobby`, `center`, `ballspawn`, `redspawn`, `bluespawn`, `redgoalmin`, `redgoalmax`, `bluegoalmin`, `bluegoalmax`

**Optionale Felder:** `fieldmin`/`fieldmax` (Aus-Erkennung), `redpenaltymin/max` und `bluepenaltymin/max` (Strafraum), `redpenaltyspot`/`bluepenaltyspot` (Elfmeter-Punkte), `spectatorspawn` (fester Zuschauer-Standpunkt)

---

## 📋 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 spec <arena>` | Alias für `spectate` |
| `/fb team rot\|blau` | Wunsch-Team wählen (nur vor Spielstart, wird nach Möglichkeit berücksichtigt) |
| `/fb list` | Alle Arenen mit Status und Spieleranzahl anzeigen |
| `/fb stats [spieler]` | Eigene oder fremde Statistiken anzeigen (inkl. laufendes Spiel) |
| `/fb top goals` | Top 10 Torschützen |
| `/fb top wins` | Top 10 nach Siegen (inkl. Siegquote %) |
| `/fb top kicks` | Top 10 nach Anzahl Schüssen |
| `/fb history [n]` | Letzte n Spiele anzeigen (Standard: 5, max. 20) |
| `/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 und Status anzeigen |
| `/fb stop <arena>` | Laufendes Spiel sofort beenden |
| `/fb setgk <arena> <spieler>` | Torwart eines laufenden Spiels manuell neu zuweisen |
| `/fb dropball <arena>` | Schiedsrichterball – Ball neutral spawnen, beide Teams dürfen spielen |
| `/fb debug <arena>` | Tor-/Feld-Regionen, Ball-Position und Aus-Seite debuggen |

Alle Commands unterstützen **Tab-Completion** für Arena-Namen und Optionen.

---

## 🎮 Spielablauf

```
Spieler joinen per Schild oder /fb join  →  optional /fb team rot|blau vor Spielstart
    → Countdown startet (10 Sek.) – bricht ab bei zu wenig Spielern
    → Spieler teleportieren zu Team-Spawns (Trikot mit Nummer #1, #2, …)
    → 5-Sekunden-Countdown mit Positions-Aufforderung
    → Fußball erscheint in der Mitte, Schonfrist von 3s

── 1. HALBZEIT ──────────────────────────────────────────
    Spieler laufen gegen den Ball → automatischer Kick
    Shift halten → Schuss lädt auf → loslassen = Powerschuss
    Langpässe (>20 Blöcke) werden in der Action-Bar angezeigt
    Anstoß nach Tor: Gegner bleiben außerhalb des Anstoß-Kreises (9,15m, 10s)
    Ball ins Tor → Punkt! (Feuerwerk + Jubel-Sounds + Pause + Anstoß)
    Bei Aus → Einwurf / Ecke / Abstoß je nach Situation
    Fouls, Karten, Abseits, Handball, Freistöße laufen automatisch

── HALBZEIT-PAUSE (30 Sek.) ─────────────────────────────
    Spielstand + Ballbesitz wird angezeigt
    Seiten werden getauscht (Teams spielen in die andere Richtung)

── 2. HALBZEIT ──────────────────────────────────────────
    Weitere 5-Sekunden-Countdown, dann Anstoß
    Spielzeit läuft ab...

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

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

── SPIELENDE ────────────────────────────────────────────
    Matchbericht mit minutengenauen Ereignissen + Ballbesitz
    Sieger + MVP werden bekannt gegeben
    Ergebnis wird in matchhistory.yml gespeichert
    Alle zurück zur Lobby (nach 5 Sek.)
```

---

## 💪 Aufladbarer Schuss

| Aktion | Effekt |
|---|---|
| Rechtsklick auf Ball | Normaler Schuss |
| Linksklick auf Ball | Normaler Schuss |
| Sprinten + Rechtsklick | Schuss mit 1,8× Kraft |
| **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. Voller Schuss = 3,8× Kraft + mehr Loft + höherer Ton.

**Power-Schwellwert-Übersicht:**
- < 40% → grüne Balken
- 40–80% → gelbe Balken
- > 80% → rote Balken + Feuer-Partikel bei 70%+

---

## 🤲 Torwart-System

Der erste Spieler jedes Teams wird automatisch als Torwart bestimmt und erhält ein spezielles andersfarbiges Trikot (Orange/Hellblau). Admins können den Torwart jederzeit mit `/fb setgk <arena> <spieler>` manuell neu zuweisen.

**Torwart-Aktionen:**

| Aktion | Effekt |
|---|---|
| Rechtsklick auf Ball (nah am Tor) | Ball halten – Ball folgt dem TW |
| Zweiter Rechtsklick (Ball gehalten) | Ball werfen |
| Shift loslassen (Ball gehalten) | Ball werfen |

**Regeln:**
- Ball kann nur innerhalb von **2 Blöcken um das eigene Tor** gehalten werden
- Ball kann nur in der **eigenen Hälfte** gehalten werden
- **Rückpass-Regel**: Hat ein Mitspieler den Ball direkt mit dem Fuß zugespielt (kein Kopfball), darf der Torwart den Ball **nicht** mit den Händen nehmen

---

## 🚩 Spielregeln

### Aus-Erkennung
Das Plugin unterscheidet automatisch zwischen den drei Aus-Situationen:

| Situation | Bedingung | Folge |
|---|---|---|
| **Einwurf** | Ball verlässt die Seitenlinie | Gegnerisches Team hat den Einwurf |
| **Ecke** | Verteidigendes Team spielt Ball über die eigene Grundlinie | Angreifendes Team bekommt Ecke |
| **Abstoß** | Angreifendes Team spielt Ball über die gegnerische Grundlinie | Verteidigendes Team bekommt Abstoß |

### Abseits
Automatische Abseits-Erkennung bei jedem Schuss. Ein Spieler steht im Abseits wenn:
- Er sich in der gegnerischen Hälfte befindet
- Er hinter dem vorletzten Verteidiger steht
- Er weiter in Richtung gegnerisches Tor steht als der Ball beim Schuss

### Anstoß-Kreis
Nach jedem Tor müssen Gegner für **10 Sekunden** außerhalb des Anstoß-Kreises (Radius: 9,15 Blöcke, konfigurierbar) bleiben. Wer zu nah kommt, wird automatisch herausgeschoben.

### Handball
Kauert ein Spieler (`Shift`) und berührt den Ball auf Armhöhe (0,5–1,5 Blöcke), gilt dies als **Handspiel**:
- Im offenen Feld → Freistoß für das gegnerische Team
- Im Strafraum → Elfmeter für das gegnerische Team
- Ein-/Ausschaltbar per `gameplay.handball-enabled`

### Fouls & Karten
Trifft ein Spieler den Gegner (Angriff oder Projektil), wird dies als Foul gewertet:

| Situation | Folge |
|---|---|
| Normales Foul | Gelbe Karte + Freistoß für das gefoulte Team |
| 2. Gelbe Karte | Gelb-Rot → Disqualifikation |
| Grobes Foulspiel (hoher Schaden ≥ 8♥) | Sofortige Rote Karte + Disqualifikation |
| Foul im Strafraum | Elfmeter für das gefoulte Team |

### Kurz-/Langpass
Wird ein Pass über mehr als **20 Blöcke** (konfigurierbar) an einen Mitspieler gespielt, erscheint in der Action-Bar eine Meldung:
```
⚽ Langpass von Hans zu Fritz (34 Blöcke)
```

### Drop Ball (Schiedsrichterball)
Ein Admin kann mit `/fb dropball <arena>` das Spiel neutral fortsetzen. Der Ball wird an der Adminposition (oder Feldmitte) gespawnt – beide Teams dürfen sofort spielen.

---

## 📈 Ballbesitz

Das Plugin trackt automatisch, welches Team den Ball zuletzt berührt hat, und berechnet daraus den prozentualen Ballbesitz:

- **Scoreboard:** Live-Anzeige `§cR 58% │ §942% B`
- **Matchbericht:** Anzeige am Spielende z. B. `Ballbesitz: 62% (Rot) vs 38% (Blau)`
- **Match-History:** Wird zusammen mit dem Ergebnis gespeichert

---

## ⏱ Nachspielzeit

Nachspielzeit wird automatisch in folgenden Situationen angesammelt und nach der regulären Spielzeit angehängt. Die Anzeige erfolgt nun in **Sekunden** (z. B. `+45s` oder `+1:30`) statt gerundeten Minuten:

| Ereignis | Sekunden |
|---|---|
| Tor | +30s (konfigurierbar) |
| Gelb-Rote / Rote Karte | +15s |
| Foul / Handball | +5s |
| Ball im Aus | +3s |
| Drop Ball | +5s |

---

## 📋 Match-History

Nach jedem Spiel wird das Ergebnis automatisch in `matchhistory.yml` gespeichert (max. 50 Einträge):

```
/fb history        → Letzte 5 Spiele anzeigen
/fb history 10     → Letzte 10 Spiele anzeigen
```

**Anzeige-Format:**
```
#1 [28.02.2026 14:22] StadionXL  3:1 │ §cRot │ Besitz 62% / 38%
#2 [28.02.2026 13:55] StadionXL  2:2 (Elfm. §c4§8:§93) │ §9Blau │ Besitz 49% / 51%
```

Gespeicherte Werte pro Spiel: Arena, Datum, Ergebnis, Sieger, Spielzeit, Ballbesitz, Elfmeter-Ergebnis, Tor-Events.

---

## 💬 Team-Chat

Spieler im Spiel schreiben automatisch nur ans eigene Team:
```
§c[ROT] §fSpielerName§7: Ich stehe frei links!
§9[BLAU] §fAndereSpieler§7: Auf mich!
```

- **`!Nachricht`** → Global-Broadcast an alle Spieler im Spiel (nur Admins, benötigt `fussball.admin`)
- Zuschauer sehen alle Team-Chats mit `[Zuschauer]`-Label
- Kompatibel mit Chat-Formatter-Plugins (EssentialsChat, CMI etc.) – keine Doppelnachrichten

---

## 🚪 Join-Schilder erstellen

**Join-Schild:**
1. Schild platzieren
2. Zeile 1: `[Fussball]` (benötigt `fussball.admin`)
3. Zeile 2: Arena-Name
4. Rechtsklick → Spiel beitreten

**Zuschauer-Schild:**
1. Schild platzieren
2. Zeile 1: `[FussballSpec]` (benötigt `fussball.admin`)
3. Zeile 2: Arena-Name
4. Rechtsklick → als Zuschauer beitreten

Das Schild wird automatisch formatiert und mit Live-Status aktualisiert:

| Symbol | Bedeutung |
|---|---|
| `§a●` grün | Arena wartet auf Spieler |
| `§e●` gelb | Countdown läuft |
| `§c●` rot | Spiel läuft / Tor-Pause |
| `§6●` orange | Halbzeit / Verlängerung / Elfmeter |
| `§7●` grau | Spiel wird beendet |

---

## 📈 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 (inkl. Siegquote)
/fb top kicks           → Top 10 nach Anzahl Schüssen
/fb history [n]         → Letzte n Spiele
```

**Gespeicherte Werte pro Spieler:**

| Wert | Beschreibung |
|---|---|
| ⚽ Tore | Erzielte Tore gesamt |
| 🅾 Eigentore | Eigentore (separat gewertet) |
| 🎯 Vorlagen | Assists (Ballberührung direkt vor dem Tor) |
| 👟 Schüsse | Alle Ball-Berührungen (Kicks, Kopfbälle etc.) |
| 🏆 Siege | Gewonnene Spiele |
| ❌ Niederlagen | Verlorene Spiele |
| ➖ Unentschieden | Unentschiedene Spiele |
| 📊 Gespielte Spiele | Gesamtanzahl Spiele |
| 📈 Siegquote | Siege / Spiele × 100 % |

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_owngoals%` | Eigentore gesamt |
| `%fussball_assists%` | Assists 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 `–` |
| `%fussball_team%` | Team des Spielers (`Rot` / `Blau` / `–`) |
| `%fussball_injurytime%` | Aktuelle Nachspielzeit in Sekunden (0 = keine) |

---

## 🔑 Berechtigungen

| Permission | Beschreibung | Standard |
|---|---|---|
| `fussball.admin` | Alle Admin-Commands (create, delete, setup, stop, setgk, dropball, debug, Schilder, Global-Chat) | OP |
| `fussball.play` | Spielen, Zuschauen, Stats anzeigen | Alle |

---

## ⚙ config.yml – Alle Einstellungen

```yaml
defaults:
  min-players: 2          # Mindestspielerzahl für den Start
  max-players: 10         # Maximale Spielerzahl pro Arena
  game-duration: 300      # Gesamtspielzeit in Sekunden (beide Halbzeiten zusammen)

ball:
  kick-power: 1.1
  sprint-kick-power: 1.8
  kick-vertical: 0.3
  charged-min-power: 1.3
  charged-max-power: 3.8

gameplay:
  offside-enabled: true
  foul-detection-enabled: true
  handball-enabled: true          # Handspiel-Erkennung (Shift + Ball auf Armhöhe)
  freekick-distance: 5.0
  freekick-duration: 600
  goalkeeper-hold-range: 2.5
  goalkeeper-throw-power: 1.8
  out-of-bounds-tolerance: 2.0
  out-of-bounds-countdown: 5
  kickoff-circle-radius: 9.15     # Anstoß-Kreis Radius (FIFA: 9,15m)
  long-pass-distance: 20.0        # Ab wann ein Pass als „Langpass" gilt (Blöcke)
  penalty-area-depth: 16
  penalty-area-margin: 6
  header-range: 1.8
  header-min-height: 0.8
  header-max-height: 2.3
  header-power: 1.3
  header-cooldown: 10
  afk-warn-seconds: 20
  afk-kick-seconds: 40
  afk-move-threshold: 0.5
  injury-time-enabled: true
  injury-time-per-goal: 30
  injury-time-per-card: 15
  injury-time-per-foul: 5
  injury-time-per-out: 3

atmosphere:
  enabled: true
  goal-fireworks: 5               # Feuerwerke pro Tor (0 = deaktiviert)
```

Alle `messages`-Einträge sind ebenfalls vollständig anpassbar. Platzhalter: `{player}`, `{team}`, `{score}`, `{time}`, `{reason}`, `{n}`, `{max}`.

---

## 📁 Dateistruktur

```
plugins/Fussball/
├── config.yml          → Plugin-Einstellungen, Ball-Power, Nachrichten
├── arenas.yml          → Gespeicherte Arenen (auto-generiert)
├── signs.yml           → Gespeicherte Join-/Zuschauer-Schilder (auto-generiert)
├── stats.yml           → Spieler-Statistiken (auto-generiert)
├── matchhistory.yml    → Letzte 50 Spiele (auto-generiert)
└── holograms.yml       → Statistik-Hologramme (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** – mindestens **2 Blöcke breit** da der Ball sonst stecken bleiben kann
- **Tortiefe:** Mindestens **2 Blöcke tief** damit Tor-Erkennung sauber funktioniert
- **`fieldmin/fieldmax` immer setzen!** Sonst gibt es weder Aus-Erkennung noch Spieler-Feldgrenzenkontrolle
- **`center` genau in die Feldmitte setzen** – wird für den Anstoß-Kreis verwendet
- **`ballspawn` genau in die Mitte** – er ist gleichzeitig der Anstoßpunkt und der Spawn nach einem Tor
- **`redpenaltyspot` / `bluepenaltyspot` setzen** für realistische Elfmeter-Positionen ca. 11 Meter vor dem jeweiligen Tor

---

## 📣 Matchbericht

Nach jedem Spiel wird automatisch ein Matchbericht ausgegeben:
- **Endergebnis** und ggf. Elfmeter-Ergebnis
- **Ballbesitz** beider Teams in Prozent
- **Tore** (mit Torschütze, ggf. Vorlage und Eigentor-Markierung)
- **Karten** (Gelb, Gelb-Rot, Rot mit Grund)
- **Fouls** (Fouler → Opfer)
- **Abseits-Situationen**
- **MVP** (Spieler mit den meisten Toren)

---

## 🐛 Bekannte Eigenheiten

- Der Ball ist ein **ArmorStand** – er kann in engen Durchgängen (< 1 Block) stecken bleiben. Ein automatischer Respawn greift nach 4 Sekunden falls der Ball verschwindet.
- Die Halbzeit teilt die `duration`-Einstellung in zwei gleiche Hälften. `duration: 300` = 2× 2:30 Minuten.
- **Abseits** erfordert `fieldmin`/`fieldmax` **nicht**, aber die Feld-Achse wird aus den Tor-Koordinaten berechnet.
- **Handball** erkennt kauernde Spieler (`Shift`) die den Ball auf Armhöhe berühren. Bei Torwarten greift stattdessen die Torwart-Halte-Mechanik.
- **Strafraum-Elfmeter:** Ohne gesetzte `redpenaltyspot`/`bluepenaltyspot` wird der Elfmeter vom `ballspawn`-Punkt ausgeführt.

---

**Copyright © 2026 - M_Viper - Alle Rechte vorbehalten**

Die unbefugte Vervielfältigung, Verbreitung oder Weitergabe dieses Plugins ist strafbar und wird rechtlich verfolgt.