# Teleport-System

Alle Teleports des Servers laufen über eine gemeinsame Engine: [Homes](homes.md), [Warps](warps.md), [TPA](tpa.md), Spawn, `/back` und [RTP](rtp.md) bekommen automatisch Sicherheitsprüfung der Zielposition, Kampf-Sperre, Warmup, Cooldown, den [gemeinsamen Teleport-Cooldown](#gemeinsamer-teleport-cooldown) und Kosten. Admin-Teleports wirken sofort und überspringen alle diese Prüfungen.

## Commands

| Command | Syntax | Permission | Default | Beschreibung |
|---|---|---|---|---|
| `/back` | `/back` | `back.use` | `true` | Teleportiert zur letzten Position vor Teleport/Tod |
| `/dback` | `/dback` | `dback.use` | `true` | Teleportiert zur letzten Todesposition |
| `/tp` | `/tp <spieler> [spieler2]` | `teleport.tp` | op | Admin: zu einem Spieler oder Spieler zu Spieler |
| `/tphere` | `/tphere <spieler>` | `teleport.tphere` | op | Admin: Spieler zu dir |
| `/tppos` | `/tppos <x> <y> <z> [welt]` | `teleport.tppos` | op | Admin: zu Koordinaten |
| `/tpall` | `/tpall` | `teleport.tpall` | op | Admin: alle Spieler zu dir |

## Weitere Permissions

| Permission | Default | Beschreibung |
|---|---|---|
| `back.ondeath` | `true` | Todesposition wird als `/back`-Ziel gespeichert |
| `teleport.bypass.safety` | false | Überspringt die Sicherheitsprüfung der Zielposition |
| `teleport.bypass.combat` | false | Teleportiert trotz Kampf-Sperre |
| `warmup.bypass.<command>` | `false` | Überspringt den Warmup des jeweiligen Befehls |
| `cooldown.bypass.<command>` | `false` | Überspringt den Cooldown des jeweiligen Befehls |
| `cooldown.bypass.teleport` | `false` | Überspringt den gemeinsamen Teleport-Cooldown (die Cooldowns der einzelnen Befehle gelten weiter). Steckt in `cooldown.bypass.*`, nicht in `rtp.bypass.cooldown` |
| `cooldown.teleport.<sekunden>` | `false` | Kürzerer gemeinsamer Teleport-Cooldown für eine Gruppe, z. B. `cooldown.teleport.30`; bei mehreren gilt der kleinste Wert |
| `cost.bypass.<command>` | `false` | Der jeweilige Befehl kostet nichts |

> **Tipp:** Nach erfolgreichem `/back` bzw. `/dback` ist die jeweilige Position verbraucht, das verhindert Hin- und Herspringen zwischen zwei Punkten. `/dback` hat eigene Schlüssel `dback` für Warmup/Cooldown/Kosten (Standard: 30 Minuten Cooldown, `/back` 8 Minuten).

> **Hinweis:** Nach einem Tod im Void führt `/back` bzw. `/dback` zum nächsten sicheren Block über der Todesposition (Säulensuche bis zur Oberfläche). Gibt es keinen Boden, schlägt der Teleport wie gewohnt als unsicher fehl und die Kosten werden zurückerstattet.

> **Tipp:** Scheitert ein Teleport nach der Abbuchung noch (z. B. keine sichere Zielposition gefunden), werden die Kosten automatisch zurückerstattet.

## Konfiguration (modules/teleport.yml)

```yaml
# Schaltet das Teleport-Modul ein oder aus.
enabled: true

teleport:
  safety-check:
    # Prüft vor jedem regulären Teleport, ob die Zielposition sicher ist
    # (fester Boden, freier Platz, kein Gefahren-Block wie Lava oder Kaktus).
    # Ist sie unsicher, wird im Umkreis bis search-radius (Blöcke) nach einer
    # sicheren Stelle gesucht; ohne Fund schlägt der Teleport fehl.
    enabled: true
    search-radius: 5
  combat-tag:
    # Wer im PvP getroffen wird, gilt für duration Sekunden als "im Kampf"
    # (Angreifer und Opfer). Solange sind reguläre Teleports blockiert.
    # Admin-Teleports sind nie betroffen.
    enabled: true
    duration: 10
  back:
    # Eine neue Back-Position wird nur gespeichert, wenn sie mindestens
    # min-distance Blöcke von der aktuellen entfernt ist (ein Weltwechsel
    # speichert immer). Todespositionen für /dback speichern immer.
    min-distance: 5
    # In diesen Welten wird keine Back-Position gespeichert oder genutzt.
    world-blacklist: []
  global-cooldown:
    # Gemeinsame Wartezeit in Sekunden nach JEDEM regulären Teleport, bevor
    # der nächste möglich ist, egal mit welchem Befehl. Die Cooldowns der
    # einzelnen Befehle gelten zusätzlich. 0 schaltet ihn ab.
    duration: 60
    # Befehle, die weder blockiert werden noch den Cooldown starten.
    exempt:
      - dback
      - world

cooldown:
  # Wartezeit in Sekunden zwischen zwei Nutzungen, pro Spieler und Befehl.
  # 480 = 8 Minuten, 1800 = 30 Minuten.
  commands:
    back: 480
    dback: 1800

cost:
  # Economy-Kosten pro Nutzung. 0 = kostenlos. Abgebucht wird erst
  # unmittelbar vor dem Sprung, bei Fehlschlag gibt es den Betrag zurück.
  commands:
    back: 0
    dback: 0

warmup:
  # Countdown vor dem Sprung. Bewegung bricht ab (Umschauen zählt nicht),
  # ein zweiter Befehl während des Countdowns wird abgelehnt.
  commands:
    back:
      duration: 3
    dback:
      duration: 3
      # true = auch jeder Schaden bricht den Warmup ab. Fehlt der Wert,
      # gilt warmup.default.cancel-on-damage aus der config.yml.
      cancel-on-damage: false
```

## Warmup, Cooldown und Kosten (global)

Die Standardwerte für alle Befehle stehen in der `config.yml`; jedes Modul überschreibt sie pro Befehl in seiner eigenen `modules/*.yml` (wie oben bei `back` gezeigt).

```yaml
# config.yml
warmup:
  default:
    # Countdown in Sekunden. 0 deaktiviert das Warmup.
    duration: 3
    # true = ein echter Schritt bricht das Warmup ab (Umschauen nicht).
    cancel-on-move: true
    # true = jeder Schaden bricht das Warmup ab, nicht nur PvP-Treffer.
    cancel-on-damage: false
    # Anzeige des Countdowns: actionbar, bossbar, both oder none.
    # Die Bossbar wechselt mit dem Fortschritt die Farbe (grün/gelb/rot).
    display: actionbar
    # Partikel-Kreis auf Brusthöhe während des Countdowns.
    particles:
      enabled: true
      type: PORTAL
      count: 10
      radius: 0.5
  commands: {}

cooldown:
  # Fallback in Sekunden für Befehle ohne eigenen Wert. Cooldowns sind
  # zeitstempelbasiert (lag-unabhängig), gelten pro Spieler und
  # überleben einen Relog, nicht aber einen Server-Neustart.
  default: 0
  commands:
    pay: 1

cost:
  # Core-eigene Kosten; Modul-Kosten liegen in modules/*.yml.
  commands: {}
```

**Abbruch des Warmups:** Der Warmup wird abgebrochen bei Bewegung (Blockwechsel, solange `cancel-on-move` aktiv ist), Ausloggen, fremdem Teleport und Tod. Optional (`warmup.default.cancel-on-damage`, pro Befehl `warmup.commands.<befehl>.cancel-on-damage`, Standard `false`) auch bei jedem Schaden. PvP-Schaden bricht ohnehin über die Kampf-Sperre (`combat-tag`) ab.

## Gemeinsamer Teleport-Cooldown

Nach jedem erfolgreichen regulären Teleport wartet der Spieler `teleport.global-cooldown.duration` Sekunden (Standard 60), bevor er sich erneut teleportieren kann, egal mit welchem Befehl. So lässt sich nicht von `/home` über `/spawn` und `/warp` zu `/tpa` springen, nur weil jeder Befehl seinen eigenen Cooldown hat.

- **Betroffen:** `/home`, `/spawn`, `/warp` (Befehl und Menü), `/tpa` und `/tpahere` (nur wer sich bewegt), `/rtp`, `/back`, Team-Home, Team-Warp und Welt-Abkürzungen wie `/shopping_district`.
- **Nicht betroffen:** Admin-Teleports (`/tp`, `/tphere`, `/tppos`, `/tpall`, `/homeof`, `/rtp player`), Jail, `/claim trapped`, der erste Spawn, Respawn und Portale. Der Rückweg einer Welt-Abkürzung (dieselbe Abkürzung ein zweites Mal) ist frei, damit man eine falsch betretene Welt sofort wieder verlassen kann. `/dback` und der Admin-Befehl `/world` stehen standardmäßig in `exempt`.
- **Zusammen mit den Befehls-Cooldowns:** Beide gelten, die längere Restzeit zählt, und nur diese wird angezeigt. Nach `/home` ist `/home` 3 Minuten gesperrt, alle anderen Teleports 60 Sekunden.
- **Start:** Erst nach einem erfolgreichen Teleport. Ein abgebrochener Warmup, ein unsicheres Ziel oder fehlendes Geld starten nichts.
- **TPA:** Wer im Cooldown steckt, kann keine `/tpa` senden. Bei `/tpaccept` wird vorher geprüft, ob der Spieler, der sich bewegen würde, noch warten muss. Dann bekommen beide eine Meldung, und die Anfrage bleibt offen. Endet die Wartezeit erst nach dem Ablauf der Anfrage, wird sie gleich abgebrochen.
- **RTP:** Die Prüfung läuft vor der Ortssuche.

**Cooldowns:** Cooldowns gelten pro Spieler-UUID und überleben einen Relog. Sie werden nicht über einen Server-Neustart hinweg gespeichert. Abgelaufene Einträge werden automatisch aufgeräumt.

> **Tipp:** Fehlt eine Option in einem `warmup.commands.<befehl>`-Block, greift automatisch der `warmup.default`-Wert aus der `config.yml`.

## Komplette Beispiel-Config

So könnte eine angepasste `modules/teleport.yml` auf einem Survival-Server aussehen:

```yaml
enabled: true

teleport:
  safety-check:
    enabled: true
    search-radius: 8
  combat-tag:
    enabled: true
    duration: 15
  back:
    min-distance: 10
    world-blacklist:
      - event_world
      - build_contest

cooldown:
  commands:
    back: 30

cost:
  commands:
    back: 25.0

warmup:
  commands:
    back:
      duration: 5
      cancel-on-damage: true
```