Skip to content

Teleport & RTP

The teleport module is the busiest part of uxmEssentials. It bundles everything that moves a player around: player-to-player teleport requests, return-to-last-spot, random wilderness teleports, spawns, and the direct staff teleports — all governed by one shared warmup and cooldown system so the rules feel consistent no matter which command a player uses.

Everything here runs through the plugin's Folia-ready scheduler and does its I/O off the main thread, so even the safe-search behind /rtp never freezes the server.

Teleport Requests (TPA)

The request flow is the polite way to teleport to another player: you ask, they accept. The pieces:

Concept Commands
Ask /tpa <player> (go to them), /tpahere <player> (bring them to you)
Answer /tpaccept, /tpdeny
Manage yours /tpcancel, /tpalist
Set a policy /tptoggle, /tpon, /tpoff, /tpauto
Block someone /tpblock <player>, /tpunblock <player>
Ask everyone /tpaall

Requests expire after request-ttl-seconds. /tptoggle refuses all incoming requests; /tpauto auto-accepts them; and /tpblock shuts out one specific player, which is the tool a player reaches for against a stalker.

Back & Death-Back

/back (alias return) returns you to your last captured location, and /deathback (alias dback) returns you to where you last died.

Returning to a death location is a grant

By default /back and /deathback only take a player back to their last teleport location. Returning to a death location requires the uxmessentials.back.ondeath marker node. This lets you decide, per rank, whether dying is something players can undo.

The back config block controls the death behaviour: on-death (whether deaths are captured at all), death-delay-seconds (a grace window), and ignored-causes (death causes that don't seed a back point — void, for instance).

Random Teleport (RTP)

/rtp (alias wild) drops a player at a random safe spot in the wilderness. The important detail is how it stays fast: instead of searching for a safe location the moment a player runs the command (which can be slow and blocks nothing usefully), uxmEssentials keeps a pre-warmed queue of validated safe locations. /rtp hands out a location from the queue instantly, and the queue tops itself back up in the background.

The search zone and queue behaviour live in modules/teleport/rtp.conf:

Key What it does
min-radius / max-radius The ring, in blocks from origin, that RTP searches within.
claim-aware Skip candidate spots that fall inside land claims.
queue-target-size How many safe locations to keep pre-warmed.
queue-low-water Refill the queue when it drops below this.
attempt-budget How many candidate points a single search may try before giving up.
excluded-biomes Biomes RTP will never land in (oceans, for example).
avoid-blocks Block types considered unsafe to land on.

Staff can retune the ring live without editing the file:

/settpr <minRange> <maxRange>

/settpr needs uxmessentials.teleport.settpr.

Spawns

The module manages a main spawn plus any number of named spawns, and can mirror another world's spawn:

Command Description Permission
/spawn [name] Go to the server spawn, or a named one uxmessentials.spawn.use / .spawn.named
/setspawn [name] Set the (named) spawn uxmessentials.spawn.set
/setmainspawn Set the primary server spawn uxmessentials.spawn.set
/removespawn Delete a spawn uxmessentials.spawn.set
/mirrorspawn <world> Mirror another world's spawn uxmessentials.spawn.set

Named spawns let you run destinations like /spawn pvp or /spawn events; /mirrorspawn is how you make a new world hand players off to an existing spawn instead of a fresh one.

Staff Teleports

These pull players directly, without the request handshake, and default to op:

  • /tp, /tphere, /goto, /bring — direct player teleports (uxmessentials.tp.use).
  • /tp <x> <y> <z> [world], /tppos … — coordinate teleports (uxmessentials.tp.position).
  • /tpo, /tpohere — override no-tp flags (uxmessentials.tp.others).
  • /tpall — pull everyone to you (uxmessentials.tp.all).
  • /tpoffline, /tpofflinehere — to/from a player's logout location (uxmessentials.tp.offline).
  • /top, /bottom, /jump, /up, /down, /ascend, /descend, /thru — vertical/directional jumps (uxmessentials.tp.vertical).

Warmups, Cooldowns & the Move Rule

Every teleport can carry a warmup (a countdown before it fires) and a cooldown (a wait before the next one). Both are granted through numbered permission tiers, so ranks can be tuned independently — and the highest matching value wins:

Node Purpose
uxmessentials.tp.warmup.<seconds> Warmup countdown before a teleport fires
uxmessentials.tp.cooldown.<seconds> Cooldown before the next teleport
uxmessentials.tp.warmup.bypass Skip warmups entirely
uxmessentials.tp.cooldown.bypass Skip cooldowns entirely

Move cancels warmup

A teleport with a warmup is cancelled if you move before the countdown finishes. Whether rotating, taking damage, or interacting also cancels it is controlled by the warmup config block (cancel-on-move, cancel-on-rotate, cancel-on-damage, cancel-on-interact, and a move-threshold). This anti-combat-log invariant is owned by the teleport module and applies to every teleport that has a warmup. Holders of uxmessentials.tp.warmup.bypass skip it.

The defaults live in modules/teleport/config.conf: default-warmup (ships 3), default-cooldown (ships 5), cooldown-start-phase (whether the cooldown clock starts when the command is run or when the teleport lands), teleport-to-center (drop players at block centre), plus effects, arrival-messages, arrival-title, and arrival-effects for arrival polish.

Key Settings (module config)

Two files:

  • modules/teleport/config.conf — default-warmup, default-cooldown, cooldown-start-phase, request-ttl-seconds, teleport-to-center, and the effects, arrival-messages, cooldowns, warmup { … }, and back { … } blocks.
  • modules/teleport/rtp.conf — the RTP ring, queue, and safe-search tuning described above.

Tips & Gotchas

  • RTP feels instant because it's pre-warmed. If players report /rtp "failing", check attempt-budget and excluded-biomes — an over-restrictive search can starve the queue.
  • /back after death does nothing without back.ondeath. If players expect to return to their corpse, grant uxmessentials.back.ondeath and set back.on-death = true.
  • Warmups are a feature, not a bug. Setting default-warmup = 0 (or granting tp.warmup.bypass to everyone) removes the move-to-cancel protection that stops players escaping combat.
  • cooldown-start-phase changes the feel. Starting the cooldown on arrival rather than on command effectively adds the warmup to the wait.
  • /rtp respects claims only if claim-aware = true. Otherwise players can land inside protected land.

Next Steps