# RTP (Random Teleport)

RTP searches for a safe random position, respecting the world border, biome filters and (if installed) claims/regions. For the plain `/rtp`, a prepared position from the queue is usually ready, so the jump happens without delay. `/rtp` runs through the [teleport engine](teleport.html), animals travel along via [mob teleport](mobteleport.html).

## Commands

| Subcommand | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| (none) | `/rtp` (alias `/randomtp`, `/wild`) | `rtp.use` | `true` | Random teleport in the current (or forced) world |
| `help` | `/rtp help` | `rtp.use` | `true` | Subcommands filtered by permission |
| `biome` | `/rtp biome <biome> [...]` | `rtp.biome` | `true` | RTP with a biome wish |
| `world` | `/rtp world <world> [biome...]` | `rtp.world` + `rtp.world.<world>` | `false` | RTP in a specific world |
| `player` | `/rtp player <player> [world]` | `rtp.player` | `false` | Admin: instantly teleports another player randomly |
| `info` | `/rtp info` | `rtp.admin` | `false` | All world parameters, blocks, limits |
| `reload` | `/rtp reload` | `rtp.admin` | `false` | Reloads config and queue |
| `queue` | `/rtp queue` | `rtp.admin` | `false` | Queue fill level per world |
| `disabled` | `/rtp disabled add\|remove\|list [world]` | `rtp.admin` | `false` | Manages the world block list at runtime |

`/rtp <worldname>` is the short form of `/rtp world <worldname>`; if the name matches no world, it is interpreted as a biome.

## Additional permissions

| Permission | Default | Description |
|---|---|---|
| `rtp.world.<world>` / `rtp.world.*` | `false` | Allows RTP in that world / all worlds |
| `rtp.bypass.worldblacklist` | `false` | Ignores blocked worlds |
| `rtp.bypass.biome` | `false` | Ignores the configured biome filter |
| `rtp.bypass.cooldown` / `rtp.bypass.delay` / `rtp.bypass.cost` | `false` | Ignores cooldown/warmup/cost (automatically couple the generic `cooldown.bypass.rtp` etc.) |
| `rtp.bypass.limit` | `false` | Ignores the usage limit |
| `rtp.bypass.claimprotection` | `false` | Ignores claim protection during live searches |
| `rtp.limit.<n>` / `rtp.limit.unlimited` | `false` | Individual usage limit (highest wins) or unlimited |

> **Tip:** The queue always checks claim protection regardless of bypass permissions; only live searches respect `rtp.bypass.claimprotection`. Only one search runs per player, a second `/rtp` meanwhile is rejected.

> **Tip:** For `/rtp biome` the intersection of the player's wish and the configured `allowed-biomes` list is used; with `rtp.bypass.biome` only the player's wish counts.

## Configuration (modules/rtp.yml)

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

rtp:
  # Usage limit per player (persists across restarts). 0 = unlimited.
  # Override per rank via the permission rtp.limit.<n>.
  max-uses: 0
  # Forces plain /rtp into this world. Empty = current world.
  force-world: ""
  # Restricts /rtp world to these worlds. Empty = all (with permission).
  # rtp.admin bypasses the restriction.
  selectable-worlds: []
  # Worlds where /rtp is blocked. Bypass: rtp.bypass.worldblacklist.
  disabled-worlds: ["spawn"]
  # Redirects a source world to a target world before searching (one entry
  # per world, each source only once).
  world-redirects:
    survival_nether: survival
  defaults:
    # Search center and distance: min-radius to max-radius from center.
    center-x: 0
    center-z: 0
    min-radius: 100
    max-radius: 5000
    # Allowed landing height range.
    min-y: -64
    max-y: 320
    # Search attempts before RTP gives up.
    max-attempts: 32
    # circle (evenly distributed) or square (inner square around the
    # center is excluded).
    shape: circle
    # NORMAL or NETHER: controls the search direction for a safe height.
    world-type: NORMAL
    # Chunks around the target preloaded before the teleport.
    chunk-preload-radius: 2
    # Keeps positions inside the vanilla world border.
    respect-worldborder: true
    # Forbidden landing blocks. Empty = built-in default (water, lava,
    # cactus, leaves, bedrock, kelp). Custom blocks too: nexo:custom_ore,
    # carpentary:chair or nexo:* as wildcard.
    block-blacklist: []
    # Allowed biomes. Empty = all.
    allowed-biomes: []
    # Price in this world: -1 uses cost.commands.rtp, 0 = free.
    cost: -1
  # Overrides any defaults value per world; missing values fall back
  # to defaults.
  worlds:
    survival_nether:
      min-radius: 50
      max-radius: 1000
      min-y: 32
      max-y: 120
      world-type: NETHER
      cost: 0
  queue:
    # Prepared safe positions per world: size is the target fill level,
    # fill-interval seconds between refill attempts.
    enabled: true
    size: 5
    fill-interval: 30
  claim-protection:
    # Skips WorldGuard regions and GriefPrevention claims.
    worldguard: true
    griefprevention: true

cooldown:
  commands:
    rtp: 60

cost:
  commands:
    # Global price unless a world sets its own cost value.
    rtp: 50.0

warmup:
  commands:
    rtp:
      duration: 10
```

## Complete example config

```yaml
enabled: true

rtp:
  max-uses: 20
  force-world: "wilderness"
  selectable-worlds:
    - wilderness
    - wilderness_nether
  disabled-worlds:
    - spawn
    - event_world
  world-redirects:
    wilderness_nether: wilderness
  defaults:
    center-x: 0
    center-z: 0
    min-radius: 500
    max-radius: 10000
    min-y: 60
    max-y: 320
    max-attempts: 48
    shape: circle
    world-type: NORMAL
    chunk-preload-radius: 3
    respect-worldborder: true
    block-blacklist:
      - POWDER_SNOW
    allowed-biomes: []
    cost: -1
  worlds: {}
  queue:
    enabled: true
    size: 10
    fill-interval: 20
  claim-protection:
    worldguard: true
    griefprevention: true

cooldown:
  commands:
    rtp: 300

cost:
  commands:
    rtp: 100.0

warmup:
  commands:
    rtp:
      duration: 5
```