LandsChunkInfo/README.md

# LandsChunkInfo – Anleitung

Dieses Plugin ist eine Erweiterung für das **Lands**-Plugin. Es zeigt Spielern:

- wie viele Chunks sie schon besitzen,
- wie viele noch frei sind,
- **wann wieder ein Chunk frei wird** (nach dem Unclaimen oder durch den Upkeep).

Du brauchst keine Programmierkenntnisse. Diese Anleitung erklärt alles Schritt für Schritt.

---

## 1. Was brauche ich?

| Was | Pflicht? | Wofür |
|---|---|---|
| Ein Minecraft-Server mit **Paper** (Version 1.21 bis 26) | Ja | Das Plugin läuft darauf |
| **Java 25** auf dem Server | Ja | Lands 8.8.0 braucht das ebenfalls |
| Das Plugin **Lands** (Version 8.8.0) | Ja | Ohne Lands startet unser Plugin nicht |
| **Vault** + ein Economy-Plugin (z. B. EssentialsX) | Nein | Nur für das Bezahlen mit Spielergeld (`skip`, `gift`) |
| **PlaceholderAPI** | Nein | Nur für Platzhalter in Scoreboard, Tab-Liste usw. |

Folia wird **nicht** unterstützt.

---

## 2. Installation (5 Schritte)

1. Stoppe den Server (oder lass ihn laufen, ein Neustart ist trotzdem später nötig).
2. Kopiere die Datei `LandsChunkInfo-1.0.0.jar` in den Ordner `plugins` deines Servers. Dort liegt auch die Lands-Jar.
3. Starte den Server neu.
4. Schau in die Konsole. Du solltest `[LandsChunkInfo] Enabling LandsChunkInfo` sehen. Steht dort ein roter Fehler, lies Abschnitt 9.
5. Im Ordner `plugins/LandsChunkInfo/` wurde jetzt eine Datei `config.yml` erstellt. Dort kannst du alles einstellen (Abschnitt 5).

Fertig. Spieler können ab sofort `/chunkinfo` benutzen.

---

## 3. Was können die Spieler? (Befehle)

Der Hauptbefehl heißt `/chunkinfo`. Es gehen auch die Kurzformen `/chunks` und `/chunkslots`.

### Übersicht anzeigen

| Befehl | Was passiert |
|---|---|
| `/chunkinfo` | Zeigt alle deine Lands: Chunks belegt, Chunks frei, gesperrte Slots, wann der nächste Chunk frei wird, Upkeep |
| `/chunkinfo MeinLand` | Zeigt nur dieses eine Land |
| `/chunkinfo top` | Zeigt die Lands mit den meisten Chunks |

**Beispiel einer Anzeige:**

```
Deine Chunks
Von dir geclaimt: 12 / 20
 MeinLand
Chunks: 12 / 20 | Frei: 6 | Gesperrt: 2
Nächster Chunk wieder frei in: 3Std 12Min (23.10. 14:30)
Sofort freischalten: /chunkinfo skip (Preis: 80,00)
Upkeep: 36,00 pro Zyklus, nächster Einzug in 2T 4Std
```

Was bedeuten die Wörter?

- **Frei** = So viele Chunks kannst du jetzt sofort claimen.
- **Gesperrt** = Du hast einen Chunk abgegeben (`/unclaim`). Dieser Platz ist für eine Weile blockiert. Nach der Wartezeit ist er wieder frei.
- **Upkeep** = Die regelmäßige Gebühr, die dein Land zahlen muss, damit es seine Chunks behält.

### Gesperrten Slot sofort freikaufen

Du willst nicht warten? Dann kauf den Slot frei.

| Befehl | Was passiert |
|---|---|
| `/chunkinfo skip` | Zeigt dir den Preis |
| `/chunkinfo skip confirm` | Kauft den Slot wirklich. Ohne `confirm` wird **nichts** bezahlt |
| `/chunkinfo gift MeinFreundLand` | Zeigt den Preis, um einen Slot in einem **fremden** Land freizukaufen |
| `/chunkinfo gift MeinFreundLand confirm` | Kauft den Slot für das fremde Land. Die Mitglieder werden benachrichtigt |

Der Preis wird günstiger, je kürzer die Wartezeit noch ist.

### Chunk vormerken (Warteschlange)

Der Chunk, auf dem du **gerade stehst**, ist frei, aber dein Land hat keinen freien Slot? Dann merk ihn vor. Sobald ein Slot frei wird, claimt das Plugin ihn **automatisch** für dich.

| Befehl | Was passiert |
|---|---|
| `/chunkinfo queue` | Merkt den Chunk vor, auf dem du stehst (für dein Land) |
| `/chunkinfo queue MeinLand` | Dasselbe, aber für ein bestimmtes Land |
| `/chunkinfo queue list` | Zeigt deine vorgemerkten Chunks |
| `/chunkinfo queue clear` | Löscht alle deine Vormerkungen |

Wichtig: **Du musst online sein**, damit der Chunk geclaimt wird.

### Fremden Chunk beobachten (Watchlist)

Ein Chunk gehört jemand anderem, und du willst ihn haben, falls er frei wird? Stell dich drauf:

| Befehl | Was passiert |
|---|---|
| `/chunkinfo watch` | Du bekommst eine Nachricht, sobald dieser Chunk frei wird |
| `/chunkinfo watch list` | Zeigt, was du beobachtest |
| `/chunkinfo watch clear` | Hört mit allem auf |

Tipp: Wenn die Nachricht kommt, nutze danach `/chunkinfo queue`, um ihn dir zu sichern.

### Chunk nur für kurze Zeit (Temp-Claim)

Du brauchst einen Chunk nur für ein paar Tage (z. B. für ein Event)? Stell dich in den Chunk (er muss zu **deinem eigenen** Land gehören):

| Befehl | Was passiert |
|---|---|
| `/chunkinfo temp 7` | Der Chunk wird nach 7 Tagen automatisch freigegeben |
| `/chunkinfo temp list` | Zeigt deine Temp-Chunks |
| `/chunkinfo temp cancel` | Nimmt dem Chunk, auf dem du stehst, das Ablaufdatum wieder weg |

Wenn ein Temp-Chunk abläuft, wird dadurch **kein** Slot gesperrt.

---

## 4. Die Platzhalter (optional)

Nur nötig, wenn du **PlaceholderAPI** hast und die Werte z. B. im Scoreboard oder in der Tab-Liste anzeigen willst. Die Werte beziehen sich auf das Hauptland des Spielers (sein eigenes Land, sonst das erste Land, in dem er vertraut ist).

| Platzhalter | Zeigt |
|---|---|
| `%chunkinfo_land%` | Name des Lands |
| `%chunkinfo_used%` | Belegte Chunks |
| `%chunkinfo_max%` | Maximale Chunks |
| `%chunkinfo_free%` | Freie Chunks |
| `%chunkinfo_locked%` | Gesperrte Slots |
| `%chunkinfo_next_free%` | Zeit, bis der nächste Slot frei wird (`-` wenn keiner gesperrt ist) |
| `%chunkinfo_upkeep%` | Upkeep-Kosten pro Zyklus |
| `%chunkinfo_upkeep_in%` | Zeit bis zum nächsten Upkeep |
| `%chunkinfo_top_1_name%` | Name des Lands auf Platz 1 (statt 1 geht jede Zahl) |
| `%chunkinfo_top_1_chunks%` | Chunks des Lands auf Platz 1 |

---

## 5. Einstellungen (config.yml)

Die Datei findest du unter `plugins/LandsChunkInfo/config.yml`. Öffne sie mit einem Texteditor (Notepad++ oder VS Code, **nicht** mit dem Windows-Notepad, wenn du auf Umlaute achtest). Nach einer Änderung gibst du im Spiel oder in der Konsole `/chunkinfo reload` ein.

**Wichtig:** Lass die Einrückungen (die Leerzeichen am Zeilenanfang) unverändert. Ändere nur die Werte hinter dem Doppelpunkt.

### Wartezeit nach dem Unclaimen

```yaml
unclaim-cooldown:
  enabled: true
  duration: 24h
  enforce: true
```

- `enabled` – `true` = Funktion an, `false` = aus.
- `duration` – Wie lange ein Slot nach `/unclaim` gesperrt bleibt. Schreibweise:
  - `30m` = 30 Minuten
  - `12h` = 12 Stunden
  - `2d` = 2 Tage
  - `1d12h` = 1 Tag und 12 Stunden
- `enforce` – `true` = Spieler können in dieser Zeit wirklich **nicht** neu claimen. `false` = es wird nur angezeigt, aber nichts blockiert.

### Upkeep-Zeitpunkt

```yaml
upkeep:
  anchor-date: ""
```

Das Plugin merkt sich automatisch, wann Lands das erste Mal Upkeep eingezogen hat, und rechnet danach weiter. **Bis dahin ist die Anzeige nur geschätzt.** Wenn du genau weißt, an welchem Tag zuletzt eingezogen wurde, trage das Datum ein, zum Beispiel `"2026-10-15"`.

### Slot freikaufen

```yaml
skip:
  enabled: true
  payment: PLAYER
  price-per-hour: 25.0
  min-price: 50.0
```

- `payment` – `PLAYER` = das Geld kommt vom Spieler (Vault nötig). `LAND` = das Geld kommt aus der Landkasse (nur der Besitzer darf das). `gift` bezahlt immer der Spieler selbst.
- `price-per-hour` – Preis pro verbleibender Stunde Wartezeit.
- `min-price` – Mindestpreis, auch wenn nur noch wenige Minuten fehlen.

Beispiel: Noch 10 Stunden Wartezeit, 25 pro Stunde ergibt 250.

### Warteschlange, Watchlist, Temp-Claims

```yaml
queue:
  max: 3
watch:
  max: 5
temp-claims:
  enabled: true
  max-days: 30
  max-per-land: 3
```

- `max` – Wie viele Einträge ein Spieler gleichzeitig haben darf.
- `max-days` – Längste erlaubte Dauer für einen Temp-Chunk.
- `max-per-land` – Wie viele Temp-Chunks ein Land gleichzeitig haben darf.

### Hinweis beim Einloggen

```yaml
join-reminder:
  enabled: true
  upkeep-warning-hours: 48
```

Beim Einloggen sagt das Plugin dem Spieler, wie viele Slots frei sind. Wenn das Guthaben des Lands nicht für den Upkeep reicht und der Einzug in weniger als `upkeep-warning-hours` Stunden ansteht, kommt zusätzlich eine Warnung (nur für den Besitzer).

### Texte ändern

Unter `messages:` stehen die Meldungen. Farben schreibst du mit `&`:

- `&a` = grün, `&c` = rot, `&e` = gelb, `&7` = grau

`%time%` wird im Spiel durch die Restzeit ersetzt. Lass es stehen.

---

## 6. Rechte (Permissions)

Rechte vergibst du mit einem Rechte-Plugin, z. B. LuckPerms.

| Recht | Wer bekommt es standardmäßig? | Was erlaubt es? |
|---|---|---|
| `landschunkinfo.use` | Alle | `/chunkinfo` und `top` benutzen |
| `landschunkinfo.skip` | Alle | Eigenen Slot freikaufen |
| `landschunkinfo.gift` | Alle | Slot in fremdem Land freikaufen |
| `landschunkinfo.queue` | Alle | Warteschlange benutzen |
| `landschunkinfo.watch` | Alle | Watchlist benutzen |
| `landschunkinfo.temp` | Alle | Temp-Claims benutzen |
| `landschunkinfo.bypass` | Nur OPs | Wartezeit nach dem Unclaimen gilt **nicht** |
| `landschunkinfo.admin` | Nur OPs | `/chunkinfo reload` |

**Beispiel:** Du willst, dass niemand außer Teammitgliedern Slots verschenken darf. Entziehe allen das Recht `landschunkinfo.gift` und gib es nur der Team-Gruppe.

---

## 7. Häufige Fragen

**Warum sieht ein Spieler „Gesperrt“, obwohl er nichts gemacht hat?**
Jemand aus seinem Land hat einen Chunk abgegeben. Die Sperre gilt für das **ganze Land**, nicht für einzelne Spieler.

**Warum wird bei manchen Unclaims nichts gesperrt?**
Gesperrt wird nur, wenn ein Spieler selbst `/unclaim` benutzt. Nicht gesperrt wird, wenn das Land gelöscht wird, Chunks durch den Upkeep verloren gehen oder ein Temp-Chunk abläuft. Spieler mit dem Recht `landschunkinfo.bypass` lösen ebenfalls keine Sperre aus.

**Die Upkeep-Zeit stimmt nicht.**
Lands verrät dem Plugin nicht, wann genau der Zyklus gestartet ist. Nach dem ersten echten Einzug passt die Anzeige. Alternativ trägst du in `upkeep.anchor-date` ein bekanntes Einzugsdatum ein.

**Muss ich das Plugin nach jeder Änderung neu starten?**
Nein. Für Änderungen an der `config.yml` reicht `/chunkinfo reload`. Nur beim Austausch der Jar-Datei brauchst du einen Neustart.

**Verlieren Spieler ihre Chunks, wenn ich das Plugin entferne?**
Nein. Das Plugin ändert keine Lands-Daten außer bei zwei Dingen: Wenn die Warteschlange einen Chunk claimt oder wenn ein Temp-Chunk abläuft. Entfernst du das Plugin, bleiben alle bestehenden Chunks gleich. Die gespeicherten Sperren und Listen liegen nur in `plugins/LandsChunkInfo/data.yml`.

**Kann ich einem Spieler mehr Chunk-Slots geben?**
Nein, das geht nur in Lands selbst (`player-limits.yml`). Dieses Plugin ändert keine Limits.

---

## 8. Datensicherung

Alles, was sich das Plugin merkt (Sperren, Warteschlange, Watchlist, Temp-Chunks, letzter Upkeep), steht in:

`plugins/LandsChunkInfo/data.yml`

Wenn du den Server umziehst oder ein Backup machst, kopiere diese Datei und die `config.yml` mit. **Bearbeite `data.yml` nicht von Hand, solange der Server läuft.** Das Plugin überschreibt die Datei sonst.

---

## 9. Wenn etwas nicht klappt

| Problem | Lösung |
|---|---|
| Plugin startet nicht, in der Konsole steht etwas mit „Lands“ | Lands fehlt oder ist nicht aktiv. Prüfe, ob die Lands-Jar im Ordner `plugins` liegt und startet |
| Fehler mit „Unsupported class file version“ oder „Java“ | Der Server läuft mit einem zu alten Java. Du brauchst **Java 25** |
| `/chunkinfo` sagt „Du bist in keinem Land Mitglied“ | Der Spieler hat kein Land und ist in keinem als vertrauenswürdig eingetragen. Das ist normal |
| `skip` oder `gift` meldet, Vault fehle | Installiere Vault und ein Economy-Plugin, oder stelle `skip.payment` auf `LAND` (dann geht nur `skip`, `gift` bleibt gesperrt) |
| Die Platzhalter zeigen sich als Text, z. B. `%chunkinfo_used%` | PlaceholderAPI fehlt oder wurde nach unserem Plugin geladen. Starte den Server neu |
| Änderungen an der `config.yml` wirken nicht | `/chunkinfo reload` ausführen. Falls es trotzdem nicht klappt: Auf Einrückungen und fehlende Anführungszeichen prüfen |
| Spieler können nach dem Unclaimen trotzdem sofort claimen | Prüfe `unclaim-cooldown.enforce`, das muss `true` sein. Und prüfe, ob der Spieler das Recht `landschunkinfo.bypass` hat (OPs haben es automatisch) |

Wenn du nicht weiterkommst: Kopiere die **roten Zeilen aus der Server-Konsole** (oder aus `logs/latest.log`) und gib sie weiter. Daraus lässt sich fast immer die Ursache erkennen.

---

## 10. Bekannte Grenzen

- Das Plugin wurde noch nicht auf einem echten Server getestet. Probiere es erst auf einem Testserver aus.
- Die Upkeep-Zeit ist bis zum ersten echten Einzug eine Schätzung.
- Die Warteschlange und die Watchlist arbeiten nur für Spieler, die **online** sind.
- Temp-Chunks laufen erst ab, wenn der Ersteller oder der Besitzer des Lands online ist.
- Lands-Limits (z. B. maximale Chunks) kann das Plugin nicht verändern.