LandsChunkInfo/README.md

# LandsChunkInfo – Anleitung (Version 1.0.7)

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

- **Chunk-Übersicht:** wie viele Chunks ein Land belegt, wie viele frei und wie viele gesperrt sind.
- **Wartezeit nach `/unclaim`:** Der Slot bleibt für eine einstellbare Zeit gesperrt. Die Spieler sehen, **wann wieder ein Chunk frei wird**.
- **Spielzeit-Anzeige:** wie viel Online-Zeit noch fehlt, bis das Limit durch Lands' Spielzeit-Belohnung um einen Chunk steigt.
- **Upkeep-Anzeige:** wann das Land das nächste Mal zahlen muss.
- **Slot freikaufen** (`skip`, `gift`), **Auto-Claim-Warteschlange** und **Watchlist**.
- **PvP-Regionen:** Bereiche (z. B. eine Arena), in denen Spieler kämpfen dürfen, auch wenn sie im selben Land Mitglied sind.
- **Platzhalter** für PlaceholderAPI.

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 dieses Plugin nicht |
| **Vault** + ein Economy-Plugin (z. B. EssentialsX) | Nein | Nur zum Bezahlen mit Spielergeld (`skip`, `gift`) |
| **PlaceholderAPI** | Nein | Nur für Platzhalter in Scoreboard, Tab-Liste usw. |

Folia wird **nicht** unterstützt.

---

## 2. Installation und Update

1. Stoppe den Server.
2. Kopiere `LandsChunkInfo-1.0.7.jar` in den Ordner `plugins` deines Servers (dort liegt auch die Lands-Jar).
   **Bei einem Update:** Lösche zuerst die alte `LandsChunkInfo-*.jar`. Es darf nur **eine** Version im Ordner liegen.
3. Starte den Server.
4. Schau in die Konsole. Du solltest `[LandsChunkInfo] Enabling LandsChunkInfo` sehen. Steht dort ein roter Fehler, lies Abschnitt 11.
5. Beim ersten Start wird `plugins/LandsChunkInfo/config.yml` erstellt. Dort stellst du alles ein (Abschnitt 7).

**Wichtig:** Nach dem Austausch der Jar-Datei ist immer ein **Neustart** nötig. `/reload` reicht nicht und kann Fehler verursachen.

Deine Dateien in `plugins/LandsChunkInfo/` (`config.yml`, `data.yml`, `pvp-regions.yml`) bleiben bei einem Update erhalten.

---

## 3. Der Befehl

Der Hauptbefehl heißt **`/chunks`**. Es gibt die Kurzform `/chunkslots`.

> **Hinweis:** Der Name `/chunks` wird bewusst nicht benutzt, weil WorldEdit/FastAsyncWorldEdit einen eigenen Befehl `/chunks` hat. Der würde sonst mit diesem Plugin kollidieren (Fehler „Too many arguments“).

---

## 4. Was können die Spieler?

### Übersicht anzeigen

| Befehl | Was passiert |
|---|---|
| `/chunks` | Zeigt alle deine Lands: Chunks belegt, frei, gesperrt, wann der nächste Chunk frei wird, Upkeep |
| `/chunks MeinLand` | Zeigt nur dieses eine Land |
| `/chunks 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)
Danach: 20Std 5Min
Sofort freischalten: /chunks skip (Preis: 80,00)
Upkeep: 36,00 pro Zyklus, nächster Einzug in 2T 4Std
```

Wenn du in Lands Spielzeit-Belohnungen eingerichtet hast (siehe unten), steht über den Lands zusätzlich:

```
Nächster Chunk durch Spielzeit: 2Std 10Min Online-Zeit (Bonus bisher: 4/20)
```

Was bedeuten die Wörter?

- **Frei** = So viele Chunks kann das Land jetzt sofort claimen.
- **Gesperrt** = Jemand hat 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 das Land zahlen muss, damit es seine Chunks behält.
- Wenn das Land-Guthaben für den Upkeep nicht reicht, steht eine rote Warnung dabei (und, wenn Lands beim Upkeep Chunks abzieht, wie viele verloren gehen würden).
- Wenn Lands Inaktivität einstellt, steht dort auch, ob der Besitzer online ist oder wann das Land als inaktiv gilt.

### Spielzeit bis zum nächsten Chunk

Lands kann das Chunk-Limit mit der Spielzeit wachsen lassen. Das stellst du in `plugins/Lands/player-limits.yml` im Abschnitt `time-rewards` ein, zum Beispiel:

```yaml
time-rewards:
  player_chunks:
    time: 2h
    max: 20
```

Dann bekommt jeder Spieler alle 2 Stunden Spielzeit einen Chunk mehr, höchstens 20. Dieses Plugin zeigt in `/chunks` an, wie lange der Spieler noch online sein muss:

- `player_chunks` = **Nächster Chunk durch Spielzeit** (Chunks, die ein Spieler insgesamt claimen darf).
- `land_size` = **Nächster Land-Chunk durch Spielzeit** (maximale Größe seiner Lands).

Die Zeile erscheint nur, wenn `time` größer als `0s` ist und das `max` noch nicht erreicht wurde. Gerechnet wird mit der Spielzeit-Statistik des Servers, genau wie bei Lands. Hat Lands eine andere Einstellung, zeigt die Anzeige dasselbe wie Lands. Das Plugin ändert an den Limits nichts.

### Gesperrten Slot sofort freikaufen

| Befehl | Was passiert |
|---|---|
| `/chunks skip` | Zeigt den Preis für den nächsten gesperrten Slot deines Lands |
| `/chunks skip confirm` | Kauft den Slot wirklich. Ohne `confirm` wird **nichts** bezahlt |
| `/chunks skip MeinLand confirm` | Dasselbe für ein bestimmtes eigenes Land |
| `/chunks gift FremdesLand` | Zeigt den Preis, um einen Slot in einem **fremden** Land freizukaufen |
| `/chunks gift FremdesLand confirm` | Kauft den Slot. Die online Mitglieder des Lands werden benachrichtigt |

Der Preis wird günstiger, je kürzer die Wartezeit noch ist. Es wird immer der Slot freigekauft, der am frühesten frei würde.

### 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 |
|---|---|
| `/chunks queue` | Merkt den Chunk vor, auf dem du stehst (für dein Hauptland) |
| `/chunks queue MeinLand` | Dasselbe, aber für ein bestimmtes Land |
| `/chunks queue list` | Zeigt deine vorgemerkten Chunks |
| `/chunks queue clear` | Löscht alle deine Vormerkungen |

Wichtig: **Du musst online sein**, damit der Chunk geclaimt wird. Ist der Chunk inzwischen von jemand anderem geclaimt, wird die Vormerkung gelöscht.

### 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 |
|---|---|
| `/chunks watch` | Du bekommst eine Nachricht, sobald dieser Chunk frei wird |
| `/chunks watch list` | Zeigt, was du beobachtest |
| `/chunks watch clear` | Hört mit allem auf |

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

### Hinweis beim Einloggen

Beim Einloggen (kurz nach dem Join) sagt das Plugin dem Spieler, wie viele Slots in seinen Lands frei sind und wann der nächste gesperrte Slot frei wird. Der Besitzer bekommt zusätzlich eine Warnung, wenn das Land-Guthaben nicht für den Upkeep reicht und der Einzug bald ansteht.

---

## 5. PvP-Regionen (für Admins)

### Wozu?

Lands verbietet PvP in der **Wildnis** zwischen Spielern, die im selben Land Mitglied sind (Meldung: „Du kannst diesen Spieler nicht in der Wildnis angreifen, weil er Mitglied in einem deiner Länder ist“). Mit einer PvP-Region kannst du einen Bereich festlegen, in dem trotzdem gekämpft werden darf, z. B. eine Arena.

### Region anlegen

Du brauchst das Recht `landschunkinfo.admin` (Standard: OPs).

1. Stell dich an die erste Ecke der Arena: `/chunks pvp pos1`
2. Stell dich an die gegenüberliegende Ecke: `/chunks pvp pos2`
3. Lege die Region an: `/chunks pvp create arena`

| Befehl | Was passiert |
|---|---|
| `/chunks pvp pos1` | Setzt die erste Ecke an deiner Position |
| `/chunks pvp pos2` | Setzt die zweite Ecke an deiner Position |
| `/chunks pvp create <Name>` | Legt die Region aus den beiden Ecken an |
| `/chunks pvp delete <Name>` | Löscht die Region |
| `/chunks pvp list` | Zeigt alle Regionen |

### Wie funktioniert das?

- Die Regionen sind **Rechtecke über die ganze Höhe**. Beide Ecken müssen in derselben Welt liegen.
- Solange ein Spieler in einer PvP-Region steht, bekommt er automatisch das Lands-Recht `lands.bypass.attack_player`. Lands prüft den Angriff dann nicht, und die rote Meldung bleibt aus. Verlässt er die Region, wird das Recht wieder entzogen.
- Falls Lands einen Schlag trotzdem abbricht, wird er freigegeben, wenn **Angreifer und Opfer beide** in der Region stehen. Das gilt auch für Pfeile und andere Projektile.
- Der Rückstoß wird in der Region ebenfalls freigegeben.
- **Außerhalb** der Region ändert sich nichts. Dort gelten weiter die Regeln von Lands.
- Die Regionen werden in `plugins/LandsChunkInfo/pvp-regions.yml` gespeichert.

### Wichtig für die Server-Einrichtung

Die PvP-Region von diesem Plugin ist eine **zusätzliche** Region. Sie ersetzt keine WorldGuard-Region. Wenn du PvP sonst überall verbieten willst, regelst du das weiterhin in WorldGuard (z. B. `pvp deny` für die ganze Welt und `pvp allow` für die Arena). Lege die Region von diesem Plugin am besten genauso groß wie die WorldGuard-Arena an.

Alternative ohne dieses Plugin: In der Lands-Config (`plugins/Lands/config.yml`) gibt es unter `combat:` die Option `ally-wilderness`. Steht sie auf `true`, dürfen Spieler mit gemeinsamem Land überall in der Wildnis kämpfen. Nach einer Änderung ist ein Neustart nötig.

---

## 6. 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 (`-` ohne Land) |
| `%chunkinfo_used%` | Belegte Chunks |
| `%chunkinfo_max%` | Maximale Chunks (oder `unbegrenzt`) |
| `%chunkinfo_free%` | Freie Chunks (oder `unbegrenzt`) |
| `%chunkinfo_locked%` | Gesperrte Slots |
| `%chunkinfo_next_free%` | Zeit, bis der nächste Slot frei wird (`-` wenn keiner gesperrt ist) |
| `%chunkinfo_next_playtime%` | Online-Zeit bis zum nächsten Chunk durch Spielzeit (`-` wenn nicht eingerichtet oder Maximum erreicht) |
| `%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 |

---

## 7. Einstellungen (config.yml)

Die Datei findest du unter `plugins/LandsChunkInfo/config.yml`. Öffne sie mit einem Texteditor (Notepad++ oder VS Code). Nach einer Änderung gibst du im Spiel oder in der Konsole `/chunks reload` ein (braucht das Recht `landschunkinfo.admin`).

**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` = Das Land kann in dieser Zeit wirklich **nicht** neu claimen, wenn alle Plätze belegt oder gesperrt sind. `false` = es wird nur angezeigt, aber nichts blockiert.

### Upkeep-Zeitpunkt

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

Das Plugin liest den Rhythmus aus der Lands-Config und merkt sich automatisch, wann Lands das erste Mal Upkeep eingezogen hat. **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, Top-Liste

```yaml
queue:
  max: 3
watch:
  max: 5
top:
  size: 10
```

- `max` – Wie viele Einträge ein Spieler gleichzeitig haben darf.
- `top.size` – Wie viele Lands in `/chunks top` stehen.

### Hinweis beim Einloggen

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

Mit `enabled: false` schaltest du den Hinweis ab. `upkeep-warning-hours` legt fest, ab wie vielen Stunden vor dem Einzug die Upkeep-Warnung kommt.

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

---

## 8. Rechte (Permissions)

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

| Recht | Wer bekommt es standardmäßig? | Was erlaubt es? |
|---|---|---|
| `landschunkinfo.use` | Alle | `/chunks`, `top` und den Hinweis beim Einloggen |
| `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.bypass` | Nur OPs | Wartezeit nach dem Unclaimen gilt **nicht** |
| `landschunkinfo.admin` | Nur OPs | `/chunks reload` und `/chunks pvp ...` |

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

---

## 9. 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 oder Chunks durch den Upkeep verloren gehen. Spieler mit dem Recht `landschunkinfo.bypass` lösen ebenfalls keine Sperre aus.

**Wie sehen Spieler, wie lange sie auf einen Chunk warten müssen?**
Mit `/chunks`. Dort steht „Nächster Chunk wieder frei in: …“.

**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 den Server neu starten?**
Für Änderungen an der `config.yml` reicht `/chunks reload`. Beim Austausch der Jar-Datei brauchst du einen Neustart (kein `/reload`).

**Verlieren Spieler ihre Chunks, wenn ich das Plugin entferne?**
Nein. Das Plugin ändert keine Lands-Daten außer bei einer Sache: Wenn die Warteschlange einen Chunk claimt. 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.

---

## 10. Datensicherung

Alles, was sich das Plugin merkt, steht in diesen Dateien in `plugins/LandsChunkInfo/`:

| Datei | Inhalt |
|---|---|
| `config.yml` | Deine Einstellungen |
| `data.yml` | Sperren, Warteschlange, Watchlist, letzter Upkeep |
| `pvp-regions.yml` | Die PvP-Regionen |

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

---

## 11. 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` zeigt „Too many arguments“ oder die Ausgabe von WorldEdit | Das ist der Befehl von WorldEdit/FAWE, nicht von diesem Plugin. Benutze `/chunks` oder `/chunkslots` |
| `/chunks` 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 diesem Plugin geladen. Starte den Server neu |
| Änderungen an der `config.yml` wirken nicht | `/chunks 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) |
| In der PvP-Region kommt trotzdem die Lands-Meldung oder kein Schaden | Prüfe mit `/chunks pvp list`, ob die Region existiert und ob **beide** Spieler darin stehen. Die Region ist ein Rechteck: am Rand zählt der Block, auf dem man steht |
| Mitglieder desselben Lands bekommen in der Arena keinen Rückstoß | Das Plugin gibt den Rückstoß frei, wenn Lands ihn blockiert. Hilft das nicht, kommt es von einem anderen Plugin (z. B. Team- oder Friendly-Fire-Plugin) |
| Nach dem Update ist die alte Version aktiv | Es liegen zwei Jar-Dateien in `plugins`. Lösche die alte und starte neu |

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.

---

## 12. Bekannte Grenzen

- Die PvP-Regionen funktionieren auf einem echten Server. Die übrigen Funktionen (Sperren, Skip, Queue, Watch) wurden dort noch nicht ausführlich getestet. Probiere neue Versionen 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.
- Lands-Limits (z. B. maximale Chunks) kann das Plugin nicht verändern.
- PvP-Regionen sind einfache Rechtecke ohne Höhenbegrenzung und keine WorldGuard-Regionen.
- Die rote Lands-Meldung zum PvP in der Wildnis kann das Plugin nicht umschreiben. Sie wird in der Arena nur vermieden, weil Lands den Angriff dort nicht mehr prüft.