# Teleport System

All teleports on the server run through one shared engine: [Homes](homes.html), [Warps](warps.html), [TPA](tpa.html), spawn, `/back` and [RTP](rtp.html) automatically get destination safety checks, combat lock, warmup, cooldown and costs. Admin teleports act instantly and skip all of these checks.

## Commands

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/back` | `/back` | `back.use` | `true` | Teleports to the last position before a teleport/death |
| `/dback` | `/dback` | `dback.use` | `true` | Teleports to the last death position |
| `/tp` | `/tp <player> [player2]` | `teleport.tp` | `false` | Admin: to a player, or player to player |
| `/tphere` | `/tphere <player>` | `teleport.tphere` | `false` | Admin: player to you |
| `/tppos` | `/tppos <x> <y> <z> [world]` | `teleport.tppos` | `false` | Admin: to coordinates |
| `/tpall` | `/tpall` | `teleport.tpall` | `false` | Admin: all players to you |

## Additional permissions

| Permission | Default | Description |
|---|---|---|
| `back.ondeath` | `true` | Death position is stored as the `/back` target |
| `teleport.bypass.safety` | `false` | Skips the destination safety check |
| `teleport.bypass.combat` | `false` | Teleports despite the combat lock |
| `warmup.bypass.<command>` | `false` | Skips the warmup of that command |
| `cooldown.bypass.<command>` | `false` | Skips the cooldown of that command |
| `cost.bypass.<command>` | `false` | That command costs nothing |

> **Tip:** After a successful `/back` or `/dback` the position is consumed, which prevents bouncing back and forth between two points. `/dback` uses the same key `back` as `/back` for warmup/cooldown/costs.

> **Tip:** If a teleport still fails after the charge (for example no safe destination found), the cost is refunded automatically.

## Configuration (modules/teleport.yml)

```yaml
# Enables or disables the teleport module.
enabled: true

teleport:
  safety-check:
    # Checks before every regular teleport whether the destination is safe
    # (solid ground, free space, no hazard block like lava or cactus).
    # If unsafe, a safe spot is searched within search-radius blocks;
    # without a find, the teleport fails.
    enabled: true
    search-radius: 5
  combat-tag:
    # Whoever gets hit in PvP counts as "in combat" for duration seconds
    # (attacker and victim). Regular teleports are blocked during that time.
    # Admin teleports are never affected.
    enabled: true
    duration: 10
  back:
    # A new back position is only stored when it is at least min-distance
    # blocks away from the current one (a world change always stores).
    # Death positions for /dback always store.
    min-distance: 5
    # No back position is stored or used in these worlds.
    world-blacklist: []

cooldown:
  # Wait time in seconds between two uses, per player and command.
  commands:
    back: 5

cost:
  # Economy cost per use. 0 = free. Charged right before the jump,
  # refunded if the teleport fails afterwards.
  commands:
    back: 0

warmup:
  # Countdown before the jump. Moving cancels it (looking around does not),
  # a second command during the countdown is rejected.
  commands:
    back:
      duration: 3
```

## Warmup, cooldown and cost (global)

The defaults for all commands live in `config.yml`; each module overrides them per command in its own `modules/*.yml` (as shown above for `back`).

```yaml
# config.yml
warmup:
  default:
    # Countdown in seconds. 0 disables the warmup.
    duration: 3
    # true = an actual step cancels the warmup (looking around does not).
    cancel-on-move: true
    # Countdown display: actionbar, bossbar, both or none.
    # The boss bar changes color with progress (green/yellow/red).
    display: actionbar
    # Particle circle at chest height during the countdown.
    particles:
      enabled: true
      type: PORTAL
      count: 10
      radius: 0.5
  commands: {}

cooldown:
  # Fallback in seconds for commands without their own value. Cooldowns are
  # timestamp based (lag independent) and reset on relog.
  default: 0
  commands:
    pay: 1

cost:
  # Core-only costs; module costs live in modules/*.yml.
  commands: {}
```

> **Tip:** If an option is missing in a `warmup.commands.<command>` block, the `warmup.default` value from `config.yml` applies automatically.

## Complete example config

This is what a customized `modules/teleport.yml` could look like on a survival server:

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