Teleport System

All teleports on the server run through one shared engine: Homes, Warps, TPA, spawn, /back and RTP automatically get destination safety checks, combat lock, warmup, cooldown, the shared teleport cooldown and costs. Admin teleports act instantly and skip all of these checks.

Commands #

Commands6

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`	op	Admin: to a player, or player to player
`/tphere`	`/tphere <player>`	`teleport.tphere`	op	Admin: player to you
`/tppos`	`/tppos <x> <y> <z> [world]`	`teleport.tppos`	op	Admin: to coordinates
`/tpall`	`/tpall`	`teleport.tpall`	op	Admin: all players to you

Additional permissions #

Permissions8

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
`cooldown.bypass.teleport`	false	Skips the shared teleport cooldown (the per-command cooldowns still apply). Included in `cooldown.bypass.*`, not in `rtp.bypass.cooldown`
`cooldown.teleport.<seconds>`	false	Shorter shared teleport cooldown for a group, e.g. `cooldown.teleport.30`; with several, the lowest wins
`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 has its own dback keys for warmup/cooldown/costs (default: 30 minutes cooldown, /back 8 minutes).

Note: After a void death, /back and /dback lead to the nearest safe block above the death position (column search up to the surface). Without any ground the teleport fails as unsafe like before and the cost is refunded.

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: []
  global-cooldown:
    # Shared wait in seconds after ANY regular teleport before the next one,
    # whichever command it uses. The per-command cooldowns apply on top.
    # 0 disables it.
    duration: 60
    # Commands that are neither blocked by nor start the shared cooldown.
    exempt:
      - dback
      - world

cooldown:
  # Wait time in seconds between two uses, per player and command.
  # 480 = 8 minutes, 1800 = 30 minutes.
  commands:
    back: 480
    dback: 1800

cost:
  # Economy cost per use. 0 = free. Charged right before the jump,
  # refunded if the teleport fails afterwards.
  commands:
    back: 0
    dback: 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
    dback:
      duration: 3
      # true = any damage cancels the warmup as well. If missing,
      # warmup.default.cancel-on-damage from config.yml applies.
      cancel-on-damage: false

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
    # true = any damage cancels the warmup, not only PvP hits.
    cancel-on-damage: false
    # 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), apply per player and survive a
  # relog, but not a server restart.
  default: 0
  commands:
    pay: 1

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

Warmup cancellation: The warmup is cancelled on movement (block change, as long as cancel-on-move is enabled), logout, external teleports and death. Optionally (warmup.default.cancel-on-damage, per command warmup.commands.<command>.cancel-on-damage, default false) also on any damage. PvP damage already cancels through the combat lock (combat-tag).

Shared teleport cooldown #

After every successful regular teleport the player waits teleport.global-cooldown.duration seconds (default 60) before the next one, whichever command it uses. That stops hopping from /home to /spawn to /warp to /tpa just because each command has its own cooldown.

Affected: /home, /spawn, /warp (command and menu), /tpa and /tpahere (only the player who moves), /rtp, /back, team home, team warp and world shortcuts like /shopping_district.
Not affected: admin teleports (/tp, /tphere, /tppos, /tpall, /homeof, /rtp player), jail, /claim trapped, first spawn, respawn and portals. The return trip of a world shortcut (the same shortcut a second time) is free, so a player who entered the wrong world can leave right away. /dback and the admin command /world are in exempt by default.
Together with the command cooldowns: both apply, the longer remaining wait counts and only that one is shown. After /home, /home is locked for 3 minutes and every other teleport for 60 seconds.
Start: only after a successful teleport. A cancelled warmup, an unsafe destination or missing money start nothing.
TPA: a player on cooldown cannot send /tpa. On /tpaccept the player who would move is checked first; if they still have to wait, both get a message and the request stays open. If the wait outlasts the request, it is cancelled right away.
RTP: checked before the location search.

Cooldowns: Cooldowns are bound to the player UUID and survive a relog. They are not persisted across a server restart. Expired entries are cleaned up automatically.

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
      cancel-on-damage: true

BackPerformance NextHomes