# 🎄 Adventskalender – Event-Kalender & Geburtstage für Minecraft

Ein Plugin für deinen Minecraft-Server, das Spielern jeden Tag ein Geschenk gibt.
Es hat **drei Kalender** und ein **Geburtstags-Geschenk**:

| Was | Wann | Türchen |
|---|---|---|
| 🎄 **Adventskalender** | ab 1. Dezember | 24 |
| 🎃 **Halloween-Kalender** | ab 1. Oktober | 31 |
| 🐰 **Oster-Kalender** | 13 Tage vor Ostersonntag bis Ostersonntag | 14 |
| 🎂 **Geburtstags-Geschenk** | am Geburtstag des Spielers + 2 Tage danach | 1 pro Jahr |

Du musst **nichts programmieren**. Plugin hineinkopieren, Server starten, fertig.
Alles Weitere (Belohnungen, Texte, Zeiten) kannst du in normalen Textdateien ändern.

Zusätzlich bringt das Plugin eine **ganze Weihnachtswelt** mit: Schnee, Santa-Event, Cracker, Magic Tree, Schneemänner, Plätzchen, Countdown, Wichteln, Adventskranz, Schneeball-Spiel, Deko-Menü, Login-Serie, Quiz, Wunschzettel und einen Weihnachtsmarkt mit Portalen. Details stehen in [Kapitel 18](#18-weihnachts-module).

---

## Inhaltsverzeichnis

1. [Was brauche ich?](#1-was-brauche-ich)
2. [Installation in 5 Schritten](#2-installation-in-5-schritten)
3. [So benutzen Spieler das Plugin](#3-so-benutzen-spieler-das-plugin)
4. [Befehle für Admins](#4-befehle-für-admins)
5. [Rechte (Permissions)](#5-rechte-permissions)
6. [Die Dateien des Plugins](#6-die-dateien-des-plugins)
7. [Belohnungen ändern](#7-belohnungen-ändern)
8. [Kalender ein- und ausschalten oder anpassen](#8-kalender-ein--und-ausschalten-oder-anpassen)
9. [Geburtstage einstellen](#9-geburtstage-einstellen)
10. [Texte und Sprache ändern](#10-texte-und-sprache-ändern)
11. [Alles testen, ohne auf den Dezember zu warten](#11-alles-testen-ohne-auf-den-dezember-zu-warten)
12. [Jeder darf nur einmal – oder der ganze Server nur einmal?](#12-jeder-darf-nur-einmal--oder-der-ganze-server-nur-einmal)
13. [Mehrere Server mit einer Datenbank (MySQL)](#13-mehrere-server-mit-einer-datenbank-mysql)
14. [Platzhalter für Scoreboards, Hologramme & Co.](#14-platzhalter-für-scoreboards-hologramme--co)
15. [Plugin aktualisieren](#15-plugin-aktualisieren)
16. [Probleme und ihre Lösung](#16-probleme-und-ihre-lösung)
17. [Häufige Fragen](#17-häufige-fragen)
18. [Weihnachts-Module](#18-weihnachts-module)

---

## 1. Was brauche ich?

- Einen Minecraft-Server mit **Spigot** oder **Paper** (oder einem Fork davon) ab **Version 1.20**.
- **Java 21** auf dem Server. Ältere Java-Versionen starten das Plugin nicht.
- Optional: das Plugin **PlaceholderAPI**, wenn du Werte des Kalenders und der Weihnachts-Module auf Scoreboards oder Hologrammen anzeigen willst.
- Optional: **WorldGuard**, wenn Schnee nur in bestimmten Regionen fallen soll.
- Optional: eine **MySQL-Datenbank**, wenn mehrere Server (z. B. mit BungeeCord) sich die Daten teilen sollen. Für einen einzelnen Server brauchst du das **nicht**.

> Hinweis: Das Plugin wird gegen die Spigot-API 1.21.10 gebaut und läuft auf Paper 26.2 und Minecraft 26.3. Für Santa als Spielermodell brauchst du Minecraft 1.21.9 oder neuer. Teste das Plugin vor dem Einsatz auf deinem Live-Server kurz aus und mach vorher eine Sicherung.

---

## 2. Installation in 5 Schritten

1. **Server ausschalten** (oder einfach weitermachen, wenn du später neu startest).
2. Die Datei **`adventskalender-1.0.3.jar`** in den Ordner **`plugins`** deines Servers kopieren.
3. **Server starten.**
4. Das Plugin legt automatisch den Ordner **`plugins/Adventskalender`** an. Darin liegen jetzt die Dateien `config.yml`, `messages_de.yml`, `messages_en.yml`, `christmas.yml` und `christmas_messages_de.yml` (bzw. `_en`).
5. **Fertig.** Im Spiel `/ak` eingeben und der Kalender geht auf.

Wenn du in der Konsole die Meldung **„Adventskalender erfolgreich gestartet!“** siehst, hat alles geklappt.

---

## 3. So benutzen Spieler das Plugin

### Kalender öffnen

| Befehl | Was passiert |
|---|---|
| `/ak` | Öffnet den Kalender, der gerade läuft. Läuft keiner, wird der Adventskalender gezeigt (mit gesperrten Türchen). |
| `/ak halloween` | Öffnet den Halloween-Kalender |
| `/ak easter` | Öffnet den Oster-Kalender |
| `/ak advent` | Öffnet den Adventskalender |

Statt `/ak` funktionieren auch `/adventskalender`, `/advent` und `/kalender`.

### Türchen öffnen

- Die **Köpfe (Advent) bzw. Items (Halloween, Ostern)** in der Mitte des Menüs sind die Türchen. Die rot-grünen Glasscheiben am Rand sind nur Dekoration.
- Ein Türchen kannst du nur öffnen, wenn der **Tag erreicht** ist. Der 5. Dezember schaltet z. B. Türchen 1 bis 5 frei, Türchen 6 bleibt zu.
- **Klick auf ein Türchen** = du bekommst das Geschenk. Passt es nicht ins Inventar, fällt es vor deine Füße.
- Ein geöffnetes Türchen **glitzert** und kann nicht nochmal geöffnet werden.
- Hast du einen Tag **verpasst**, ist das kein Problem: Du kannst alte Türchen jederzeit nachholen, solange der Kalender läuft.

### Geburtstags-Geschenk

| Befehl | Was passiert |
|---|---|
| `/ak birthday set 15.03` | Trägt deinen Geburtstag ein (Tag.Monat, **ohne Jahr**) |
| `/ak birthday` | Zeigt deinen eingetragenen Geburtstag |
| `/ak birthday claim` | Holt dein Geschenk ab |

- Du kannst das Geschenk **am Geburtstag und bis zu 2 Tage danach** abholen (Familie, Freunde, Feier – du hast Zeit).
- Es gibt **ein Geschenk pro Jahr**.
- Wenn du dich an deinem Geburtstag (oder danach) einloggst, bekommst du eine **anklickbare Nachricht**. Ein Klick darauf holt das Geschenk ab.
- Dein Geburtstag kann **nur einmal** eingetragen werden. Hast du dich vertippt, muss ein Admin das ändern (siehe unten).

---

## 4. Befehle für Admins

Alle Admin-Befehle beginnen mit `/ak admin`. Du brauchst dafür das Recht `adventskalender.admin` (Operatoren haben es automatisch).

Die Teile in `[eckigen Klammern]` sind **optional**. Lässt du `[event]` weg, gilt der Befehl für **alle** Kalender.
Gültige Namen für `[event]`: `advent`, `halloween`, `easter`.

| Befehl | Was er macht |
|---|---|
| `/ak admin reload` | Lädt Config und Sprachdateien neu, ohne Neustart |
| `/ak admin test [event] <Tag>` | Tut so, als wäre heute der gewählte Tag (siehe [Testen](#11-alles-testen-ohne-auf-den-dezember-zu-warten)) |
| `/ak admin test [event] reset` | Beendet den Test, das echte Datum gilt wieder |
| `/ak admin reset [event] <Spieler>` | Löscht **alle** geöffneten Türchen eines Spielers |
| `/ak admin reset [event] global` | Löscht **alle** Daten aller Spieler (**Vorsicht!**) |
| `/ak admin resetday [event] <Spieler> <Tag>` | Macht **ein** Türchen für einen Spieler wieder zu |
| `/ak admin resetday [event] global <Tag>` | Macht ein Türchen im Server-weiten Modus wieder frei |
| `/ak admin birthday set <Spieler> <TT.MM>` | Trägt den Geburtstag eines Spielers ein oder ändert ihn |
| `/ak admin birthday remove <Spieler>` | Löscht den Geburtstag eines Spielers |
| `/ak admin birthday reset <Spieler>` | Erlaubt dem Spieler, das Geburtstagsgeschenk **nochmal** abzuholen (zum Testen oder bei Problemen) |

**Beispiele:**

```
/ak admin test halloween 15           (Halloween-Kalender: so tun, als wäre der 15. Tag)
/ak admin test reset                  (alle Tests beenden)
/ak admin resetday advent Steve 3     (Steve darf Türchen 3 im Advent nochmal öffnen)
/ak admin reset halloween Steve       (Steves Halloween-Daten löschen)
/ak admin birthday set Steve 24.12    (Steves Geburtstag auf den 24.12. setzen)
```

> Mit **Tab** vervollständigt Minecraft die Namen und Zahlen für dich.

---

## 5. Rechte (Permissions)

Rechte vergibst du mit einem Rechte-Plugin (z. B. LuckPerms).

| Recht | Wofür | Standard |
|---|---|---|
| `adventskalender.use` | Kalender öffnen und benutzen | **alle Spieler** |
| `adventskalender.birthday` | Geburtstag eintragen und Geschenk abholen | **alle Spieler** |
| `adventskalender.admin` | Alle Admin-Befehle und Update-Hinweis beim Beitritt | nur Operatoren |

Die Rechte der Weihnachts-Module (`xmas.use`, `xmas.admin`, `christmasplus.*`) stehen in [Kapitel 18](#rechte-der-weihnachts-module).

---

## 6. Die Dateien des Plugins

Alles liegt in `plugins/Adventskalender/`:

| Datei | Wofür |
|---|---|
| `config.yml` | **Einstellungen und Belohnungen.** Hier änderst du, was es zu gewinnen gibt und wann die Kalender laufen. |
| `messages_de.yml` | Alle **deutschen Texte** (Titel, Nachrichten, Namen der Geschenke) |
| `messages_en.yml` | Alle **englischen Texte** |
| `christmas.yml` | **Einstellungen der Weihnachts-Module** (Schnee, Santa, Baum, Quiz, Markt, Portale und mehr) |
| `christmas_messages_de.yml` / `christmas_messages_en.yml` | **Texte der Weihnachts-Module** |
| `data.yml` | Hier speichert das Plugin, **wer was geöffnet hat** und die Geburtstage. Diese Datei **nicht löschen**, sonst fangen alle von vorne an. |
| `trees.yml`, `wichteln.yml`, `wishes.yml`, `portals.yml` u. a. | Daten der Weihnachts-Module (siehe [Kapitel 18](#gut-zu-wissen)). Nicht löschen. |

### So bearbeitest du die Dateien richtig

1. Öffne die Datei mit einem **Texteditor** (Notepad++, VS Code oder der Editor deines Hosters). **Nicht** mit Word.
2. Ändere nur die Werte, **nicht** die Einrückung am Zeilenanfang. Die Leerzeichen am Anfang sind wichtig!
3. Benutze **Leerzeichen**, keine Tabulatortaste.
4. Speichern und im Spiel `/ak admin reload` eingeben.
5. Wenn der Server nach einem Fehler die Datei nicht mehr lesen kann: Zeile prüfen, die du zuletzt geändert hast (fehlendes Leerzeichen, fehlende Anführungszeichen).

---

## 7. Belohnungen ändern

Jedes Türchen hat in der `config.yml` einen Eintrag. Beispiel Advent, Tag 3:

```yaml
rewards:
  3:
    material: DIAMOND_SWORD
    amount: 1
    enchantments:
      - type: SHARPNESS
        level: 4
      - type: UNBREAKING
        level: 2
```

**Das bedeutet:**

- `3:` – die Nummer des Türchens
- `material:` – welches Item es gibt (siehe unten)
- `amount:` – wie viele Stück
- `enchantments:` – Verzauberungen. Möchtest du keine, schreibe `enchantments: []`

### Wo stehen die Belohnungen der anderen Kalender?

- **Advent:** ganz oben unter `rewards:`
- **Halloween:** weiter unten unter `events:` → `halloween:` → `rewards:`
- **Ostern:** weiter unten unter `events:` → `easter:` → `rewards:`
- **Geburtstag:** ganz unten unter `birthday:` → `rewards:`

### Item-Namen (`material`)

Es sind die englischen Minecraft-Namen in **GROSSBUCHSTABEN** mit Unterstrich statt Leerzeichen.
Beispiele: `DIAMOND`, `GOLDEN_APPLE`, `NETHERITE_INGOT`, `ELYTRA`, `FIREWORK_ROCKET`.
Eine Liste findest du, wenn du im Internet nach „Spigot Material list“ suchst.

### Verzauberungen (`type`)

Auch hier die englischen Namen: `SHARPNESS`, `UNBREAKING`, `PROTECTION`, `EFFICIENCY`, `FORTUNE`, `LOOTING`, `MENDING` usw.
`level` ist die Stufe (z. B. `5` für Schärfe V).

### Wenn du etwas falsch schreibst

Das Plugin gibt dann eine **Warnung in der Konsole** aus (z. B. „Ungültiges Material …“). Der Spieler bekommt die Meldung, dass das Geschenk falsch eingestellt ist, und das **Türchen bleibt zu**. Er verliert also nichts. Korrigiere den Fehler und lade mit `/ak admin reload` neu.

### Eigener Name und eigene Beschreibung der Geschenke

Der Name und der Beschreibungstext, die im Menü über einem Türchen stehen, kommen **nicht** aus der `config.yml`, sondern aus der Sprachdatei. Siehe [Texte und Sprache ändern](#10-texte-und-sprache-ändern).

---

## 8. Kalender ein- und ausschalten oder anpassen

In der `config.yml` ganz unten gibt es den Bereich `events:`. Dort steht jeder Kalender mit seinen Einstellungen:

```yaml
events:
  halloween:
    enabled: true
    days: 31
    start: "10-01"
    grace_days: 0
    closed_material: PUMPKIN
    opened_material: JACK_O_LANTERN
```

| Einstellung | Bedeutung |
|---|---|
| `enabled` | `true` = Kalender an, `false` = Kalender aus (die Daten bleiben erhalten) |
| `days` | Wie viele Türchen der Kalender hat (1 bis 36) |
| `start` | Wann der Kalender beginnt. Format `Monat-Tag`, z. B. `"10-01"` für den 1. Oktober |
| `grace_days` | Wie viele Tage der Kalender nach dem letzten Türchen noch offen bleibt, damit man verpasste Türchen nachholen kann |
| `closed_material` | Item für ein **geschlossenes** Türchen |
| `opened_material` | Item für ein **geöffnetes** Türchen |

### Zeitpunkt für Ostern

Ostern liegt jedes Jahr woanders. Deshalb gibt es dort eine Sonderschreibweise:

```yaml
start: "easter-13"
```

Das heißt: **13 Tage vor Ostersonntag**. Das Plugin rechnet das Datum **jedes Jahr automatisch** aus, du musst nie wieder etwas ändern.
Weitere Beispiele: `easter+1` = Ostermontag, `easter-2` = Karfreitag.

### Eigene Köpfe statt Items (für Fortgeschrittene)

Möchtest du für Halloween oder Ostern hübsche Kopf-Texturen, kannst du bei einem Kalender zusätzlich diese Zeilen einfügen:

```yaml
    closed_texture: "http://textures.minecraft.net/texture/DEINE_TEXTUR"
    opened_texture: "http://textures.minecraft.net/texture/DEINE_TEXTUR"
```

Passende Texturen findest du auf Seiten wie *minecraft-heads.com* (dort den Wert „Minecraft-URL“ kopieren).

### Zeitzone

Das Plugin richtet sich nach der Uhrzeit des Servers. Wenn dein Server in einem anderen Land steht und die Türchen zu früh oder zu spät aufgehen, trage deine Zeitzone ein:

```yaml
general:
  timezone: "Europe/Berlin"
```

---

## 9. Geburtstage einstellen

Alles steht unten in der `config.yml` im Bereich `birthday:`:

```yaml
birthday:
  enabled: true
  grace_days: 2
  allow_change: false
  broadcast: true
  commands: []
  rewards:
    1:
      material: CAKE
      amount: 1
      enchantments: []
```

| Einstellung | Bedeutung |
|---|---|
| `enabled` | `false` schaltet die Geburtstags-Funktion komplett ab |
| `grace_days` | Wie viele Tage **nach** dem Geburtstag das Geschenk noch abholbar ist (Standard 2) |
| `allow_change` | `false` = Spieler können ihren Geburtstag nur **einmal** eintragen, Änderungen macht nur ein Admin. `true` = Spieler dürfen selbst ändern (siehe Hinweis) |
| `broadcast` | `true` = der ganze Server sieht „Steve feiert Geburtstag – alles Gute!“, wenn das Geschenk abgeholt wird |
| `commands` | Zusätzliche Befehle, die der Server ausführt (siehe unten) |
| `rewards` | Die Geschenke. Funktioniert genau wie bei den Kalendern, du kannst beliebig viele Einträge anlegen (1, 2, 3, …) |

> **Warum ist `allow_change` standardmäßig aus?**
> Wäre es an, könnte ein Spieler sein Datum jeden Tag umstellen und sich ständig Geschenke holen. Auch mit `true` kann er pro Jahr nur **einmal** abholen.

### Geld oder andere Belohnungen per Befehl

Wenn du z. B. ein Wirtschafts-Plugin hast, kannst du Geld verschenken:

```yaml
  commands:
    - "eco give %player% 500"
    - "give %player% minecraft:cake 1"
```

`%player%` wird automatisch durch den Namen des Spielers ersetzt. Ohne Schrägstrich am Anfang schreiben.

### Wichtige Hinweise

- Das **Jahr** wird nie gespeichert, nur Tag und Monat. Das Plugin weiß also nie, wie alt jemand ist.
- Wer am **29. Februar** Geburtstag hat, feiert in Jahren ohne Schalttag am **28. Februar**.
- Wer am **31. Dezember** Geburtstag hat, kann bis in den Januar abholen. Das funktioniert korrekt.

---

## 10. Texte und Sprache ändern

### Sprache umstellen

In der `config.yml` ganz oben:

```yaml
general:
  language: "de"
```

`"de"` = Deutsch, `"en"` = Englisch. Danach `/ak admin reload`.

### Eigene Texte

Öffne `messages_de.yml` (oder `messages_en.yml`). Dort stehen alle Texte. Farben schreibst du mit `&`:

| Code | Farbe | Code | Farbe |
|---|---|---|---|
| `&0` | Schwarz | `&8` | Dunkelgrau |
| `&1` | Dunkelblau | `&9` | Blau |
| `&2` | Dunkelgrün | `&a` | Grün |
| `&3` | Türkis | `&b` | Hellblau |
| `&4` | Dunkelrot | `&c` | Rot |
| `&5` | Lila | `&d` | Pink |
| `&6` | Gold | `&e` | Gelb |
| `&7` | Grau | `&f` | Weiß |

Formatierung: `&l` = **fett**, `&o` = *kursiv*, `&n` = unterstrichen, `&r` = zurücksetzen.

### Platzhalter in Texten

Diese Platzhalter dürfen in den Texten stehen und werden automatisch ersetzt:

- `%day%` – die Nummer des Tages
- `%date%` – das Datum eines gesperrten Türchens
- `%player%` – der Spielername
- `%event%` – der Name des Kalenders
- `%days%` – die Anzahl Tage (bei Geburtstagen)

### Namen und Beschreibung der Geschenke im Menü

Beispiel für den Adventskalender in `messages_de.yml`:

```yaml
rewards:
  day_3:
    name: "&cTag 3: Schwert des Helden"
    lore: ["&7Ein mächtiges Schwert, um Monster zu jagen."]
```

- `name` ist die Überschrift des Türchens.
- `lore` sind die Zeilen darunter. Mehrere Zeilen schreibst du so: `["Zeile 1", "Zeile 2"]`.

Für Halloween und Ostern stehen die Texte weiter unten in der Datei unter `events:` → `halloween:` bzw. `easter:`.
Wenn du ein Geschenk in der `config.yml` änderst, solltest du hier den Namen anpassen, sonst steht „Schwert des Helden“, obwohl es jetzt Diamanten gibt.

> Wenn du neue Texte vermisst („Key error: …“ im Spiel), siehe [Plugin aktualisieren](#15-plugin-aktualisieren).

---

## 11. Alles testen, ohne auf den Dezember zu warten

Du musst nicht bis zum 1. Dezember warten, um alles auszuprobieren:

1. `/ak admin test advent 10` – der Adventskalender denkt jetzt, es sei der 10. Dezember.
2. `/ak advent` – öffne ihn und probiere die Türchen 1 bis 10 aus.
3. Zum Zurücksetzen deiner Test-Türchen: `/ak admin reset advent DEINNAME`
4. Test beenden: `/ak admin test reset`

Genauso für `halloween` und `easter`. Den Test-Tag **vergisst** das Plugin beim nächsten Neustart. Du kannst also nichts „vergessen auszuschalten“.

**Geburtstag testen:**

1. `/ak admin birthday set DEINNAME TT.MM` – statt TT.MM das **heutige** Datum eintragen (z. B. `24.12`)
2. `/ak birthday claim` – du bekommst das Geschenk
3. Nochmal testen: `/ak admin birthday reset DEINNAME`

---

## 12. Jeder darf nur einmal – oder der ganze Server nur einmal?

Es gibt zwei Betriebsarten:

- **Normal (Standard):** Jeder Spieler hat seinen **eigenen** Kalender. Jeder darf jedes Türchen einmal öffnen.
- **Global:** Jedes Türchen darf **nur ein einziger Spieler** auf dem ganzen Server öffnen. Wer zuerst klickt, gewinnt.

Umstellen in der `config.yml`:

```yaml
calendar:
  use_global_calendar: false     # true = Global-Modus
```

Du kannst das auch nur für **einen** Kalender ändern, indem du bei diesem im Bereich `events:` die Zeile `global: true` oder `global: false` einfügst.

---

## 13. Mehrere Server mit einer Datenbank (MySQL)

Nur nötig, wenn du z. B. ein BungeeCord-Netzwerk hast und alle Server dieselben Daten benutzen sollen. Für **einen** Server einfach ignorieren.

In der `config.yml`:

```yaml
mysql:
  enable: true
  host: "localhost"
  port: 3306
  database: "adventskalender"
  user: "root"
  password: "DEIN_PASSWORT"
```

- Die Datenbank (`adventskalender`) musst du vorher selbst anlegen. Die Tabellen darin erstellt das Plugin allein.
- Danach den Server **neu starten** (oder `/ak admin reload`).
- In der Konsole muss stehen: **„MySQL-Verbindung erfolgreich hergestellt!“**
- Klappt es nicht, benutzt das Plugin automatisch die `data.yml` als Notlösung und schreibt eine Warnung in die Konsole.
- Sollte die Datenbank später kurz ausfallen, bekommen Spieler eine Meldung und es wird **nichts** vergeben. Sobald die Datenbank wieder da ist, geht alles weiter.
- Alle Kalender und Geburtstage werden in der Datenbank gespeichert. Daten aus einer älteren Version werden dabei automatisch übernommen.

> **Wichtig:** Daten aus der `data.yml` werden **nicht automatisch** in die Datenbank kopiert. Schaltest du MySQL ein, fangen die Spieler dort bei null an.

---

## 14. Platzhalter für Scoreboards, Hologramme & Co.

Wenn das Plugin **PlaceholderAPI** installiert ist, kannst du diese Werte überall anzeigen, wo PlaceholderAPI funktioniert:

### Für das gerade laufende Kalender-Event

| Platzhalter | Zeigt |
|---|---|
| `%ak_event%` | Name des laufenden Kalenders (`advent`, `halloween`, `easter`) |
| `%ak_day%` | Welcher Tag des Kalenders heute ist (0 = Kalender läuft nicht) |
| `%ak_claimed%` | Wie viele Türchen der Spieler schon geöffnet hat |
| `%ak_remaining%` | Wie viele Türchen noch offen sind |
| `%ak_has_claimed_today%` | „Ja“ oder „Nein“: Hat der Spieler das heutige Türchen schon geöffnet? |
| `%ak_is_global%` | „Global“ oder „Spieler-basiert“ |

### Für einen bestimmten Kalender

Schreibe den Namen des Kalenders vor den Platzhalter:

- `%ak_halloween_claimed%`
- `%ak_easter_day%`
- `%ak_advent_remaining%`

### Geburtstag

| Platzhalter | Zeigt |
|---|---|
| `%ak_birthday%` | Eingetragenes Datum (z. B. `15.03.`) oder `-` |
| `%ak_birthday_active%` | „Ja“, wenn der Spieler gerade sein Geschenk abholen kann, sonst „Nein“ |

### Weihnachts-Module

Countdown, Advent, Bäume, Schneeball-Punkte, Login-Serie und Wichtel-Partner haben eigene Platzhalter mit dem Präfix `xmas`, zum Beispiel `%xmas_days_left%`. Die ganze Liste steht in [Kapitel 18](#platzhalter-für-die-weihnachts-module).

---

## 15. Plugin aktualisieren

1. Server **ausschalten**.
2. Die **alte `.jar`-Datei** aus dem `plugins`-Ordner löschen.
3. Die **neue `.jar`-Datei** hineinkopieren.
4. Server starten.

Deine **Daten** (`data.yml`) und deine **Einstellungen** bleiben erhalten.

### Neue Einstellungen sichtbar machen

Deine alte `config.yml` und die Sprachdateien werden bei einem Update **nicht überschrieben**. Neue Funktionen laufen trotzdem mit den Standardwerten, du siehst die neuen Einstellungen aber nicht in der Datei. Willst du sie sehen und ändern:

1. Server ausschalten.
2. `config.yml` umbenennen, z. B. in `config_alt.yml`. (Dasselbe mit den `messages_...yml`-Dateien und, falls nötig, mit `christmas.yml` und `christmas_messages_...yml`.)
3. Server starten. Das Plugin erstellt eine frische, vollständige Datei.
4. Deine Änderungen aus `config_alt.yml` in die neue Datei übertragen.

Die `data.yml` bleibt dabei **immer unangetastet**.

> **Beim Update auf 1.0.3:** Die Dateien `christmas.yml` und `christmas_messages_...yml` werden beim ersten Start neu angelegt. Fehlende Einstellungen und Texte ergänzt das Plugin später selbst mit den Standardwerten. Texte, die du **geändert** hast, bleiben erhalten. Neue Wörter oder Korrekturen in den Standardtexten siehst du nur, wenn du die Textdatei umbenennst und neu erzeugen lässt.

### Update-Hinweis

Erscheint eine neue Version auf SpigotMC, schreibt das Plugin eine Warnung in die Konsole. Admins bekommen beim Einloggen eine klickbare Nachricht mit dem Download-Link.

---

## 16. Probleme und ihre Lösung

| Problem | Lösung |
|---|---|
| **Plugin startet nicht** | Prüfe die Java-Version (**Java 21** nötig) und ob es Spigot/Paper ab 1.20 ist. Die genaue Fehlermeldung steht in der Server-Konsole. |
| **`/ak` tut nichts / „Unbekannter Befehl“** | Plugin wurde nicht geladen. Schau in die Konsole oder tippe `/plugins` und prüfe, ob „Adventskalender“ grün ist. |
| **„Dafür hast du keine Berechtigung“** | Der Spieler hat `adventskalender.use` (bzw. `adventskalender.admin`) nicht. Rechte prüfen. |
| **Alle Türchen sind gesperrt** | Es ist gerade nicht die Zeit des Kalenders. Prüfe das Datum oder teste mit `/ak admin test`. |
| **Im Menü steht „Key error: …“** | In deiner Sprachdatei fehlt ein Text. Siehe [Plugin aktualisieren](#15-plugin-aktualisieren), neue Sprachdatei erzeugen lassen. |
| **Ein Türchen lässt sich nicht öffnen, Meldung „falsch konfiguriert“** | In der `config.yml` ist bei diesem Tag ein Item- oder Verzauberungsname falsch geschrieben. Die Konsole sagt dir genau, wo. |
| **Eine Verzauberung fehlt am Geschenk** | Der Name in `type:` ist falsch (englisch und GROSS schreiben). Die Konsole zeigt eine Warnung. |
| **Kopf zeigt Steve statt Weihnachtsmotiv** | Der Server konnte die Textur nicht laden (Internet-/Mojang-Problem). Neustart versuchen. Bei Halloween/Ostern gibt es Items statt Köpfen, das ist normal. |
| **Meldung „Die Datenbank ist gerade nicht erreichbar“** | Nur mit MySQL. Prüfe Zugangsdaten und ob die Datenbank läuft. |
| **Nach dem Reload stimmt etwas nicht** | Server einmal komplett neu starten. |
| **Ein Spieler hat sich beim Geburtstag vertippt** | `/ak admin birthday set <Spieler> <TT.MM>` |
| **Spieler hat sein Geburtstagsgeschenk verloren / Fehler beim Abholen** | `/ak admin birthday reset <Spieler>`, dann darf er nochmal abholen. |
| **Kalender geht zur falschen Uhrzeit auf** | Zeitzone in der `config.yml` einstellen (siehe [Zeitzone](#zeitzone)). |

Hilft nichts davon: Kopiere die **Fehlermeldung aus der Konsole** (nicht nur „geht nicht“) und frage auf der Seite des Plugins bei SpigotMC nach.

---

## 17. Häufige Fragen

**Kann ich Geschenke für jeden Tag selbst festlegen?**
Ja, siehe [Belohnungen ändern](#7-belohnungen-ändern).

**Kann ich einen Kalender ausschalten, den ich nicht will?**
Ja: In der `config.yml` bei `events:` den Eintrag `enabled: false` setzen.

**Kann ich mehr als 24, 31 oder 14 Türchen haben?**
Ja, bis zu 36 pro Kalender (Einstellung `days`). Du musst dann aber auch für jedes neue Türchen eine Belohnung eintragen und im Sprachfile einen Namen vergeben.

**Was passiert, wenn der Kalender vorbei ist?**
Er bleibt noch `grace_days` Tage offen (Advent: bis zum 31.12., Ostern: 7 Tage), danach sind alle Türchen gesperrt, bis er im nächsten Jahr wieder startet.

**Gehen die Türchen jedes Jahr von vorne los?**
Nein. Das Plugin merkt sich dauerhaft, was jemand geöffnet hat. Soll im nächsten Jahr wieder alles neu sein, benutze `/ak admin reset global` (oder `/ak admin reset advent global` nur für den Advent). **Achtung:** Das löscht die Daten für **alle**.

**Sehen alle Spieler, wann ich Geburtstag habe?**
Nein. Das Datum sieht nur der Spieler selbst (und Admins in der Datenbank/Datei). Im Chat steht beim Abholen nur „Spieler feiert Geburtstag“, ohne Datum.

**Funktioniert das Plugin mit Bedrock-Spielern (Geyser)?**
Das wurde nicht getestet.

**Ich habe `data.yml` gelöscht, was jetzt?**
Dann haben alle Spieler wieder alle Türchen und Geburtstage sind weg. Spiele vorher eine Sicherung ein, wenn du eine hast. Mach vor Änderungen am Server grundsätzlich eine Sicherheitskopie des Plugin-Ordners.

---

## 18. Weihnachts-Module

Ab Version 1.0.3 bringt das Plugin zusätzlich viele Weihnachts-Funktionen mit. Du brauchst dafür **keine weiteren Plugins** (kein Christmas+, kein X-Mas, kein Lib's Disguises).

**Wichtig zu wissen:**

- Alle Einstellungen stehen in **`plugins/Adventskalender/christmas.yml`**.
- Alle Texte stehen in **`christmas_messages_de.yml`** (Deutsch) und **`christmas_messages_en.yml`** (Englisch). Welche benutzt wird, hängt von `general.language` in der `config.yml` ab.
- Mit `/ak admin reload` oder `/xmas reload` lädst du alles neu, ohne den Server neu zu starten.
- Befehle: **`/christmas`** (Kurzformen `/xmas`, `/ch`, `/chr`, `/christmasplus`) und **`/cracker`**.
- Items schreibst du überall so: `MATERIAL:Anzahl`, zum Beispiel `DIAMOND:2`. Zusätzlich gehen `cookie:<id>:<Anzahl>`, `cracker:<id>:<Anzahl>`, `crystal:<Anzahl>` und `present:<Anzahl>` (Geschenk-Kopf).
- Mit `/xmas help` zeigt dir das Plugin im Spiel alle Befehle.

| Funktion | Kurz erklärt |
|---|---|
| [Schnee](#schnee) | Schneefall-Partikel, jeder schaltet ihn selbst um |
| [Santa-Event](#santa-claus-event) | Santa fliegt ein, landet und wirft Geschenke |
| [Cracker](#cracker) | Items, die man öffnet und eine Belohnung bekommt |
| [Magic Tree](#magic-tree) | Ein Baum, der mit Items wächst und Geschenke gibt |
| [Schneemänner](#schneemänner) | Deko-Schneemänner und selbst gebaute, die Geschenke geben |
| [Plätzchen](#plätzchen-und-lebkuchen) | Essbare Items mit Effekten |
| [Countdown](#countdown-bis-heiligabend) | Bossbar und Nachricht „Noch X Tage“ |
| [Wichteln](#wichteln) | Zufällig ziehen, Geschenke verteilen |
| [Adventskranz](#adventskranz) | Vier Kerzen, die an den Adventssonntagen angehen |
| [Schneeball-Spiel](#schneeball-spiel) | Arena mit Punkten und Belohnungen |
| [Deko-Menü](#deko-menü) | Deko per Klick aufstellen |
| [Login-Serie](#login-serie) | Belohnungen für tägliches Einloggen |
| [Weihnachtsgruß](#weihnachtsgruß-und-neujahr) | Chat-Gruß und Feuerwerk an besonderen Tagen |
| [Kamin-Socken](#kamin-socken) | Socke aufhängen, am 25.12. liegt etwas darin |
| [Nikolausmütze](#nikolausmütze) | Rote Mütze als Item |
| [Quiz](#weihnachtsquiz) | Frage im Chat, der Schnellste gewinnt |
| [Wunschzettel](#wunschzettel) | Spieler wünschen sich etwas, Admins erfüllen es |
| [Weihnachtsmarkt und Portale](#weihnachtsmarkt-und-portale) | Händler-Stände und Portale dorthin |

### Schnee

- `/xmas snow` schaltet den Schnee **für dich selbst** an oder aus.
- Einstellungen unter `snow:`: Stärke (`level` 1 bis 5), Welten sperren (`disable-in-worlds`), Standard an/aus (`default-on`).
- **Schnee-Blacklist für Welten (Admin):** `/xmas snow world add <Welt>` sperrt den Schnee in einer Welt, `/xmas snow world remove <Welt>` hebt die Sperre auf, `/xmas snow world list` zeigt die gesperrten Welten. Die Liste steht in `snow.disable-in-worlds` und wird dauerhaft gespeichert, die Wirkung ist sofort.
- Mit `enable-only-in-regions: true` und einer Liste unter `regions:` gibt es Schnee nur in bestimmten **WorldGuard**-Regionen. Dafür muss WorldGuard installiert sein.
- Bei vielen Spielern kannst du `display-task-interval` erhöhen (z. B. 10), dann gibt es weniger Last.

### Santa-Claus-Event

| Befehl | Was er macht |
|---|---|
| `/xmas santa start [Zeit] [Welt x y z]` | Santa an deiner Stelle oder an den Koordinaten starten |
| `/xmas santa start [Zeit] random` | Santa an einem zufälligen, festgelegten Ort starten |
| `/xmas santa stop` | Santa beenden |
| `/xmas santa teleport` | Zu Santa teleportieren |

Zeit geht als `300`, `30s`, `5m` oder `1h`. Ohne Angabe gilt `santa.duration`.

- **Anflug:** Santa kommt mit Schlitten und zwei Rentieren (Rudolph, Blitzen) eingeflogen und wirft Geschenke ab, bevor er landet. Abschalten mit `sleigh.enable: false`.
- **Melodie:** Wenn Santa kommt, spielt eine Weihnachtsmelodie mit Glocken (Notenblock-Klänge, keine Dateien nötig). Einstellbar unter `santa.melody` (`enable`, `volume`, `tempo`, `everyone`).
- **Geschenke:** `drop-interval` (Sekunden), `drop-chance` (in %), `radius` und die Liste `gifts`. Cracker gibst du als `cracker:cracker:1` an.
- **Spazieren:** Mit `walk-radius` läuft Santa herum und hinterlässt eine Schneespur (`snow-trail`), die wieder verschwindet.
  Er läuft flüssig mit sanften Drehungen, `walk-speed` stellt das Tempo ein. Beim Laufen schwingen Beine und Arme, beim Stehenbleiben winkt er (`walk-animation`, `wave`).
- **Aussehen:** Ab **Minecraft 1.21.9** ist Santa ein Spielermodell, davor ein Rüstungsständer. Einen eigenen Skin trägst du bei `skin-url` (Textur-Adresse von `textures.minecraft.net`) oder `skin-player` (Spielername) ein. Mit `model: ARMOR_STAND` erzwingst du den Rüstungsständer.
- **Zufällige Orte:** Unter `locations:` trägst du Welt und Koordinaten ein (siehe Beispiel in der Datei).

### Cracker

| Befehl | Recht |
|---|---|
| `/cracker list` | `christmasplus.cracker.list` |
| `/cracker get [id] [Anzahl]` | `christmasplus.cracker.get` (mehr als 1 zusätzlich `christmasplus.cracker.get.multiple`) |
| `/cracker give <Spieler> [id] [Anzahl]` | `christmasplus.cracker.give` |

Rechtsklick öffnet einen Cracker. Die Belohnungen stehen unter `crackers.<id>.rewards`. Jeder Eintrag hat eine `chance` (Gewicht) und `item`, `command` (Befehl, `%player%` wird ersetzt) oder `permission`.

```yaml
crackers:
  cracker:
    material: FIREWORK_STAR
    name: "&c&lWeihnachts-Cracker"
    rewards:
      - { chance: 40, item: "COOKIE:8" }
      - { chance: 10, command: "give %player% diamond 3" }
```

### Magic Tree

So funktioniert der Baum:

1. **Kristall besorgen:** Du bekommst ihn mit `/xmas give <Spieler> [Anzahl]`, oder du stellst ihn in der **Werkbank** her: **Diamanten oben, links, rechts und unten, in der Mitte ein Smaragd**. Abschalten mit `magic-tree.crystal-recipe: false`.
2. **Pflanzen:** Rechtsklick mit dem Kristall auf einen **Setzling**.
3. **Füttern:** Wirf die Items, die der Baum braucht, **neben den Baum**. Er nimmt sie auf (nur vom Besitzer). Mit Rechtsklick auf den Baum siehst du, was noch fehlt.
4. **Wachsen:** Sind alle Items da, kommt eine Meldung und ein Ring leuchtet am Boden. Rechtsklick auf den Baum, dann wächst er eine Stufe.
5. **Stufen:** Setzling, kleiner Baum, Baum, Magic Tree. Items und Wartezeiten stehen unter `magic-tree.levels`.
6. **Geschenke ab Stufe:** `magic-tree.presents-from-level` legt fest, ab welcher Stufe Geschenke entstehen (`SAPLING`, `SMALL_TREE`, `TREE` oder `MAGIC_TREE`, Standard `SMALL_TREE`). Darunter gibt es keine Geschenke. Ab dieser Stufe gilt der `gift-cooldown` der Stufe, bei `-1` der Wert `default-gift-cooldown` (Standard 300 Sekunden).
7. **Deko-Köpfe am Baum:** Statt Beton-, Gold- und Seelaternen-Blöcken hängen Köpfe im Baum (`magic-tree.ornaments.mode: heads`, zufällig gedreht). Die Texturen stehen unter `ornaments.heads`: entweder eine URL von textures.minecraft.net oder der „Value“ von minecraft-heads.com. Mit `mode: blocks` gibt es wieder die alten Blöcke. Wie viel Schmuck hängt, stellst du mit `ornaments.per-ring` (Stück pro Ring, Standard 3) und `ornaments.every-nth-layer` (nur jede n-te Ebene, Standard 2) ein. Schon gebaute Bäume behalten ihren Schmuck, bis sie die nächste Stufe erreichen.
6. **Geschenke:** Ab dem kleinen Baum erscheinen Geschenk-Köpfe rund um den Baum. Rechtsklick oder Abbauen öffnet sie.

Standard-Kosten:

| Von → nach | Items |
|---|---|
| Setzling → kleiner Baum | 1 Diamant, 10 Redstone, 1 Enderperle |
| Kleiner Baum → Baum | 3 Diamanten, 5 Goldbarren, 10 Blaze-Pulver, 30 Schneebälle |
| Baum → Magic Tree | 5 Diamanten, 3 Smaragde, 8 Goldnuggets, 16 Glowstone-Staub |

Weitere Dinge:

- **Abbauen:** Den Stamm **zweimal** abbauen. Dabei geht der Fortschritt verloren.
- **Schutz:** Bäume und Geschenke sind vor Kolben, Explosionen, Feuer und Laubzerfall geschützt.
- **Limit:** `tree-limit` Bäume pro Spieler.
- **Glück:** Mit `luck.enabled: true` kann ein Geschenk leer sein (`luck.chance` in %).
- **Eigene Geschenke:** `/xmas addhand` fügt das Item in deiner Hand hinzu (gespeichert in `gifts.yml`). `/xmas gifts` lässt sofort Geschenke unter allen Bäumen erscheinen.
- **Event beenden:** `/xmas end` oder automatisch am Datum `holiday-ends.date`. Danach geben Bäume keine Geschenke mehr, Spieler können sie abbauen und bekommen ihre Items zurück (`resource-back`).
- **Partikel:** Spirale, leuchtende Ringe, Lichter, fallende Schneeflocken und ein Stern. Die Stärke stellst du mit `magic-tree.particles.intensity` ein (0,2 bis 5,0, Standard 2,0), abschalten mit `particles.enable: false`.

### Schneemänner

- **Deko-Schneemann (Admin):** `/xmas snowman spawn [stand|walk] [Name]` stellt einen unverwundbaren Schneemann auf: `stand` = steht still, `walk` = läuft im Umkreis um seinen Startpunkt herum (`snowman.deco.walk-radius`, Standard 8 Blöcke). Ohne Angabe gilt `snowman.deco.walk` (Standard `false` = stehend). `/xmas snowman remove` entfernt den nächsten. Die Schnee-Spur laufender Schneemänner verschwindet nach `snowman.trail-fade-seconds` Sekunden wieder (`snowman.trail`: `fade`, `none` oder `keep`).
- **Selbst gebaute:** Wer einen Schneemann baut (zwei Schneeblöcke und ein Kürbis), bekommt einen Namen wie „Steves Schneemann“. Er wirft alle `gift-interval` Sekunden ein kleines Geschenk ab. Es zählen die ältesten `max-per-player` Schneemänner eines Spielers.
- Einstellungen unter `snowman:`.

### Plätzchen und Lebkuchen

Drei Sorten sind eingebaut: `zimtstern` (Tempo), `lebkuchen` (Regeneration) und `bratapfel` (Absorption).

- `/xmas cookie list` zeigt alle Sorten, `/xmas cookie give <Spieler> <id> [Anzahl]` verteilt sie.
- Als Belohnung schreibst du `cookie:zimtstern:2` in Cracker, Santa-Geschenke, Kalender-Geschenke und so weiter.
- Eigene Sorten legst du unter `cookies:` an. Effekte im Format `"effekt:Sekunden:Stufe"`, zum Beispiel `"speed:30:1"`.

### Countdown bis Heiligabend

- Beim Join erscheint „Noch X Tage bis Heiligabend“, dazu eine **Bossbar**. `/xmas countdown` schaltet die Leiste für dich um.
- Einstellungen unter `countdown:`: Zieldatum (`target`, Monat-Tag), ab wie vielen Tagen vorher die Anzeige beginnt (`show-days-before`, Standard 60), Bossbar und Join-Nachricht.
- Für Scoreboards und Hologramme gibt es Platzhalter, siehe [Platzhalter](#platzhalter-für-die-weihnachts-module).

### Wichteln

| Befehl | Wer | Was |
|---|---|---|
| `/xmas wichteln open` | Admin | Wichteln eröffnen, alle werden informiert |
| `/xmas wichteln join` / `leave` | Spieler | Mitmachen / austreten |
| `/xmas wichteln draw` | Admin | Zufällig ziehen (mindestens 3 Teilnehmer, niemand zieht sich selbst) |
| `/xmas wichteln who` | Spieler | Wen du beschenkst |
| `/xmas wichteln gift` | Spieler | Item in der Hand als Geschenk ablegen (ein anderes Item ersetzt es) |
| `/xmas wichteln deliver` | Admin | Alle Geschenke verteilen |
| `/xmas wichteln status` | alle | Phase und Teilnehmerzahl |
| `/xmas wichteln reset` | Admin | Alles zurücksetzen |

Wer beim Verteilen offline ist, bekommt das Geschenk beim nächsten Join. Mit `wichteln.reveal-giver: true` sieht der Empfänger, von wem es kommt.

### Adventskranz

- `/xmas wreath create` baut einen Kranz an der Stelle, auf die du schaust. `/xmas wreath remove` entfernt ihn.
- An den **vier Adventssonntagen** gehen die Kerzen nacheinander an (die dritte ist rosa), mit einer Meldung an alle. Bis zum Datum `wreath.burn-until` (Standard 26.12.) brennen sie.
- Der Kranz ist vor Abbauen geschützt (außer für Admins).

### Schneeball-Spiel

1. Stell dich in die Mitte der Fläche und gib `/xmas snowball arena <Radius>` ein.
2. `/xmas snowball start [Zeit]` startet eine Runde. `/xmas snowball stop` beendet sie.
3. In der Arena bekommt jeder **nur während einer laufenden Runde** immer mindestens 16 Schneebälle (`refill-amount`).
4. Wer einen anderen Spieler in der Arena trifft, bekommt Punkte (`points-per-hit`). Die Punkte stehen in der Actionbar.
5. Am Ende bekommen die **Top 3** ihre Belohnung (`snowball.rewards`). `/xmas snowball top` zeigt die Rangliste.

### Deko-Menü

`/xmas deco` (Admin) öffnet ein Menü: Geschenk, Zuckerstange, Laternenpfahl, Weihnachtsbaum, Kranz, Schneemann, Lichterkette und Schneehaufen. Ein Klick stellt die Deko dort auf, wohin du schaust. `/xmas deco undo` macht die letzte rückgängig.

### Login-Serie

Wer an mehreren Tagen hintereinander einloggt, bekommt steigende Belohnungen. Die Serie zählt im Zeitraum `from` bis `until` (Standard 1.12. bis 31.12.). Nach `cycle` Tagen (Standard 7) beginnen die Belohnungen von vorn. Die Belohnungen stehen unter `login-streak.rewards`.

### Weihnachtsgruß und Neujahr

Am 24.12., 25.12., 31.12. und 1.1. gibt es einmal pro Tag einen Gruß im Chat. Wer an diesem Tag joint, bekommt ihn ebenfalls. Dazu gibt es auf Wunsch ein kleines **Feuerwerk** über dem Spieler (ohne Schaden). Einstellungen unter `greetings:`: Welcher Tag welchen Text bekommt, `join-fireworks`, `fireworks-on-broadcast`.

### Kamin-Socken

- `/xmas stocking` hängt ab dem 1.12. (`hang-from`) eine Socke auf.
- Ab dem 25.12. (`open-on`) bekommt jeder mit aufgehängter Socke automatisch sein Geschenk, oder er holt es mit demselben Befehl ab. Bis `until` (31.12.).
- Die Belohnungen stehen unter `stocking.rewards`.
- **Socke an die Wand hängen:** `/xmas stocking place` hängt eine rote Socke an die Wand, auf die du schaust (höchstens `stocking.max-placed-per-player`, Standard 3). `/xmas stocking remove` entfernt die nächste eigene.
- **Santas Socken-Flug:** Am Weihnachtstag und dem Tag danach (`stocking-flight.from` / `until`, Standard 24.12. bis 25.12.) fliegt Santa von aufgestellter Socke zu aufgestellter Socke und legt unter jeder ein Geschenk ab. Das Geschenk öffnest du mit Rechtsklick; standardmäßig nur der Besitzer der Socke (`owner-only`). Der Besitzer bekommt eine Nachricht mit den Koordinaten, wenn er online ist.
- Einstellungen unter `stocking-flight`: `enable` (an/aus), `interval-minutes` (Abstand zwischen Flügen), `max-stockings-per-flight`, `speed`, `rewards` (leer = `stocking.rewards`).
- Admins können den Flug mit `/xmas stocking flight` sofort testen (auch außerhalb des Zeitraums). Es fliegen nur Socken in geladenen Chunks.

### Nikolausmütze

Eine rote Mütze als Item. Beim Join (in der Weihnachtszeit) erscheint ein **anklickbares Angebot** im Chat. `/xmas hat` gibt sie dir direkt. Mit `santa-hat.auto-equip: true` wird sie automatisch aufgesetzt. Zeitraum: `santa-hat.from` bis `until`.

### Weihnachtsquiz

- `/xmas quiz start [Nr]` stellt eine Frage im Chat (ohne Nummer eine zufällige). Wer **zuerst richtig antwortet**, gewinnt die Belohnung. Die Antwort tippt man einfach in den Chat und sie ist dann für andere nicht sichtbar.
- `/xmas quiz skip` beendet eine laufende Frage, `/xmas quiz count` zeigt die Zahl der Fragen.
- Groß- und Kleinschreibung und Umlaute (ä oder ae) sind egal.
- Mit `quiz.auto.enable: true` kommt alle `interval-minutes` Minuten automatisch eine Frage, wenn mindestens `min-players` Spieler online sind.
- Eigene Fragen trägst du unter `quiz.questions` ein:

```yaml
quiz:
  questions:
    - { q: "Wie viele Kerzen hat ein Adventskranz?", a: ["4", "vier"] }
    - { q: "Frage?", a: ["Antwort"], reward: [ { item: "DIAMOND:1" } ] }
```

### Wunschzettel

- **Spieler:** `/xmas wish <Text>` schreibt einen Wunsch (maximal `max-open-per-player` offene, `max-length` Zeichen). `/xmas wish list` zeigt sie, `/xmas wish clear` löscht sie.
- **Admins:** `/xmas wishes` öffnet das Menü mit allen offenen Wünschen.
  - **Linksklick** mit einem Item in der Hand: Wunsch erfüllt, das Item geht als Geschenk an den Spieler.
  - **Linksklick ohne Item:** Es passiert nichts, du bekommst einen Hinweis.
  - **Shift + Linksklick:** Wunsch ohne Geschenk erfüllen.
  - **Rechtsklick:** Wunsch löschen.
- Ist der Spieler offline, bekommt er Geschenk und Meldung beim nächsten Join. Admins werden bei einem neuen Wunsch benachrichtigt.

### Weihnachtsmarkt und Portale

**Marktplatz und Stände (Admin):**

| Befehl | Was er macht |
|---|---|
| `/xmas market set` | **Marktplatz** an deiner Stelle festlegen (Ziel der Portale) |
| `/xmas market unset` | Marktplatz aufheben, Portale führen dann nirgendwohin |
| `/xmas market tp` | Zum Marktplatz teleportieren |
| `/xmas market spawn <id>` | Marktstand aufstellen (mitgeliefert: `plaetzchen`, `deko`, `gluehwein`) |
| `/xmas market remove` | Nächsten Stand entfernen |
| `/xmas market list` | Stand-IDs anzeigen |
| `/xmas market santa set` | **Santa** an deiner Stelle auf den Markt stellen (zum Beispiel vor einen Thron oder Sessel) |
| `/xmas market santa remove` | Markt-Santa wieder entfernen |
| `/xmas market santa reset` | Tagesgeschenke für alle zurücksetzen (zum Testen) |

Ein Stand ist ein Händler (Villager), bei dem Spieler Items tauschen. Die Angebote stehen unter `market.stalls.<id>.trades`. Nach einer Änderung lädst du mit `/xmas reload` neu.

```yaml
market:
  stalls:
    plaetzchen:
      name: "&6Plätzchen-Stand"
      profession: BUTCHER
      trades:
        - { give: "cookie:zimtstern:2", price: ["EMERALD:1"] }
```

**Leben auf dem Markt:** Alles bezieht sich auf den Marktplatz (`market.radius`, Standard 45 Blöcke).

- **Begrüßung:** Wer den Markt betritt, bekommt einen Titel („Weihnachtsmarkt“) mit Glockenklang (`market.welcome.enable`).
- **Musik:** Im Markt spielen leise Weihnachtsmelodien mit Glocken, dazwischen sind Pausen (`market.music`: `enable`, `volume`, `tempo`, `pause-seconds`).
- **Schnee nur im Markt:** Mit `market.snow-only-in-market: true` fällt der Schnee nur im Markt. Das gilt erst, wenn ein Marktplatz gesetzt ist.
- **Santa auf dem Markt:** `/xmas market santa set` stellt Santa an deine Stelle. Er dreht sich zu Spielern in der Nähe und winkt. Jeder Spieler bekommt per Rechtsklick **einmal pro Tag** ein Geschenk (`market.santa.rewards`). Die Tagesgrenze wird in `market-life.yml` gespeichert. Santa erscheint nur, solange Spieler in der Nähe sind, und kommt nach einem Neustart von selbst wieder.
- **Wichtel:** Kleine Wichtel-Figuren laufen zwischen den Ständen herum (`market.elves`: `count`, `radius`, `speed`, `names`, eigener Skin möglich). Sie sind nur da, solange Spieler im Markt sind.
- **Glühwein-Stand:** `/xmas market spawn gluehwein` stellt einen Stand mit Glühwein, Kinderpunsch und heißer Schokolade auf. Beim Trinken gibt es Effekte (Regeneration, Feuerresistenz, Tempo, Absorption) und Dampf-Partikel. Die Getränke stehen unter `cookies` und lassen sich wie Plätzchen verschenken (`cookie:gluehwein:2`).

**Portale (Spieler):** Sie funktionieren **nur, wenn ein Admin den Marktplatz festgelegt hat**.

- `/xmas portal create`: Schau auf den Boden und gib den Befehl ein. Das Plugin baut einen Torbogen aus **Schneeblöcken** (10 Stück, werden verbraucht, Admins zahlen nichts). Er braucht 5 Blöcke Breite und Höhe sowie festen Boden.
- Pro Spieler ist ein Portal erlaubt (`portal.limit-per-player`).
- Wer in der Öffnung steht und `teleport-delay-seconds` (Standard 3) wartet, landet auf dem Markt. Danach gilt eine Pause (`cooldown-seconds`).
- `/xmas market back` oder der Klick-Text im Chat führt zurück vor das Portal.
- `/xmas portal remove` baut das Portal ab (der Besitzer bekommt die Schneeblöcke zurück), `/xmas portal info` zeigt Kosten und Anzahl.
- Portale sind vor Abbauen, Kolben und Explosionen geschützt.

### Zusätze für den Adventskalender

Unter `rewards.<Tag>` in der `config.yml` sind zusätzlich möglich: `commands`, `permissions`, `multiple` (mehrere Geschenke), `random` (Zufallsgeschenk mit Gewichtung), `cracker`, `crystal` und `groups` (extra Geschenke für Gruppen wie Donor, über ein Recht).

```yaml
rewards:
  3:
    material: DIAMOND
    amount: 2
    multiple: ["COOKIE:8", "GOLD_INGOT:3"]
    random:
      - { chance: 50, item: "EMERALD:2" }
      - { chance: 50, command: "give %player% apple 5" }
    groups:
      donor:
        permission: "christmasplus.donor"
        multiple: ["DIAMOND:3"]
```

- `/ac test` schaltet für dich den Testmodus um (alle Tage öffnen), Recht `christmasplus.adventcalendar.test`.
- `/ac reset <Spieler> <Tag|all>` setzt zurück, Recht `christmasplus.adventcalendar.reset`.
- Mit `calendar-extras.restrict-past-days: true` sind vergangene Tage nur mit `christmasplus.adventcalendar.claimpast` öffenbar.
- Mit `calendar-extras.broadcast-claim: true` sehen alle, wer ein Türchen geöffnet hat.
- Für `permissions` als Belohnung trägst du in der `christmas.yml` bei `permission-command` einen Befehl ein, z. B. für LuckPerms `lp user %player% permission set %permission% true`.

### Platzhalter für die Weihnachts-Module

Mit **PlaceholderAPI** (Präfix `xmas`):

| Platzhalter | Zeigt |
|---|---|
| `%xmas_days_left%` | Tage bis Heiligabend |
| `%xmas_countdown%` | Der Countdown-Text |
| `%xmas_advent%` | Aktueller Advent (0 bis 4) |
| `%xmas_trees%` | Magic Trees des Spielers |
| `%xmas_snowball_points%` | Punkte im Schneeball-Spiel |
| `%xmas_snowball_rank%` | Platz im Schneeball-Spiel |
| `%xmas_streak%` | Aktuelle Login-Serie |
| `%xmas_streak_best%` | Beste Login-Serie |
| `%xmas_wichteln%` | Name des Wichtel-Partners |

### Rechte der Weihnachts-Module

| Recht | Wofür | Standard |
|---|---|---|
| `xmas.use` | Bäume pflanzen, Portale bauen, Wichteln, Wunschzettel | alle |
| `xmas.admin` | Alle Admin-Befehle der Weihnachts-Module | Operatoren |
| `christmasplus.christmas.snow` | `/xmas snow` | alle |
| `christmasplus.christmas.santa` | Santa-Befehle | Operatoren |
| `christmasplus.christmas.reload` | `/xmas reload` | Operatoren |
| `christmasplus.cracker.list` / `get` / `get.multiple` / `give` | Cracker-Befehle | Operatoren |
| `christmasplus.adventcalendar.test` | `/ac test` | Operatoren |
| `christmasplus.adventcalendar.reset` | `/ac reset` | Operatoren |
| `christmasplus.adventcalendar.claimpast` | Vergangene Tage öffnen | alle |

### Gut zu wissen

- Die Weihnachts-Module nutzen eigene Daten-Dateien im Plugin-Ordner (`trees.yml`, `gifts.yml`, `wichteln.yml`, `wreaths.yml`, `snowball.yml`, `streaks.yml`, `stockings.yml`, `wishes.yml`, `market.yml`, `portals.yml`, `greetings.yml`). Diese nicht löschen, wenn die Daten erhalten bleiben sollen.
- **Bäume, Wichteln und Co. werden lokal gespeichert**, nicht in MySQL. Mehrere Server teilen sich diese Daten nicht.
- Das Plugin ist gegen die Spigot-API **1.21.10** gebaut. Auf Servern unter 1.20 wurde es nicht getestet.
- Das Spielermodell für Santa braucht Minecraft **1.21.9** oder neuer, sonst nutzt das Plugin einen Rüstungsständer.
- Quizfragen, Cracker- und Plätzchen-Namen stehen in der `christmas.yml` auf Deutsch und lassen sich dort ändern.

---

*Autor: M_Viper • Frohe Weihnachten, schaurig-schönes Halloween, frohe Ostern und alles Gute zum Geburtstag! 🎄🎃🐰🎂*