RTP

Commands

Configuration

All RTP settings live under the rtp: section in config.yml.

rtp:
  enabled: true
  cooldown: 60
  warmup: 5
  cancel-on-movement: true
  particles: true
  max-attempts: 10
  min-y: 64
  max-y: 128
  use-world-border: true
  global:
    min-radius: 1000
    max-radius: 10000
    blocked-biomes:
      - ocean
      - deep_ocean
  worlds:
    world:
      enabled: true
      min-radius: 1000
      max-radius: 10000
      display-name: "<#55FF55>Overworld"
    world_nether:
      enabled: false
      min-radius: 500
      max-radius: 3000
      display-name: "<#FF5555>The Nether"
      blocked-biomes:
        - basalt_deltas
    world_the_end:
      enabled: true
      min-radius: 1000
      max-radius: 10000
      display-name: "<#FF55FF>The End"

Permissions

Safe Location Search

When you run /rtp, the plugin searches for a safe location asynchronously:

1. Permission check — Verifies essentialsc.rtp and the specific world permission.
2. Cooldown check — If on cooldown, shows remaining time. Bypassed by essentialsc.rtp.bypass.cooldown.
3. World enabled check — The world must have enabled: true in config.
4. Random coordinate generation — Uses polar coordinates: random angle (0-2pi) and random distance between min-radius and max-radius from world spawn.
5. World border check — If use-world-border: true, the coordinate must be inside the border.
6. Async chunk loading — The chunk at the target coordinates is loaded asynchronously via getChunkAtAsync().
7. Y-level determination
   • Overworld — Uses getHighestBlockYAt()
   • Nether — Searches downward from Y=min(126, maxY) to Y=max(1, minY), looking for solid ground with air space above. Skips bedrock below Y=5.
   • End — Uses highest block YAt, but gets 3x max attempts (30) because End islands are sparse
8. Biome check — The biome at the location must not be in the world's blocked-biomes list.
9. Safety validation — Ground block must be solid and not lava, cactus, fire, or magma block. Feet and head blocks must be air or non-solid.
10. Retry loop — If any check fails, a new random coordinate is generated. Up to 10 attempts (30 for End).

If no safe location is found after all attempts, the player is notified and no cooldown is applied.

Teleport and Effects

Once a safe location is found:

• Random orientation — Yaw is randomized (0-360 degrees), pitch is set to 0 degrees.
• Async teleport — Performed via scheduler.teleportAsync() for Folia safety.
• Cooldown applied — Only on successful teleport.
• Back location saved — The player's pre-teleport location is stored for /back.
• Particles — 30 portal particles in a random spread around the destination, plus one explosion particle at the exact location (if rtp.particles: true).
• Sounds — Enderman teleport sound plays at the destination for both the player and the world.
• Success message — Coordinates and world name are displayed via MiniMessage.

Warmup

If warmup is enabled (default 5s):

• A pling sound plays at the start.
• An action bar countdown updates every second with remaining time.
• A hat sound (quiet click) plays on each tick during countdown.
• Movement is checked at block coordinates (X/Y/Z). If the player moves and cancel-on-movement is true, the teleport is cancelled. Bypassed by essentialsc.rtp.bypass.movement.
• Quitting during warmup cancels the teleport and cleans up all state.

GUI

Running /rtp without arguments opens the world selection GUI:

• Layout — 27-slot inventory with 3 world slots per page (positions 11, 13, 15).
• Icons — Environment-based materials: grass block (overworld), netherrack (nether), end stone (end). Disabled or permission-locked worlds show a barrier.
• Information — Each icon shows the display name (MiniMessage), enabled status, permission status, live player count, and min/max radius.
• Pagination — Arrow buttons for previous/next page, book icon showing current page.
• Live refresh — The GUI updates every second (20 ticks) to reflect current player counts and world status.
• Click to teleport — Clicking an enabled, permitted world closes the GUI and starts the RTP process for that world.

The GUI is fully async-safe and cleans up all tasks and state when closed.

Troubleshooting

"No safe location found after 10 attempts"

The search radius may be too large, the blocked-biomes list too restrictive, or the world too sparse (especially the End). Increase max-attempts, reduce blocked-biomes, or shrink the radius.

"You do not have permission for this world"

The player lacks the specific world permission. Grant essentialsc.rtp.world.<key> matching the config key, or essentialsc.rtp.world.* for all worlds.

Cooldown not resetting

Cooldowns are stored in-memory and reset on server restart. If a player reports cooldown issues, check that rtp.cooldown is not set to an unexpectedly high value.

Nether RTP falling into lava

The Nether search algorithm skips lava, cactus, fire, and magma blocks, but may find locations above lava lakes. Increase min-y for the Nether or add crimson_forest and warped_forest to blocked-biomes for safer results.

GUI not updating player counts

The GUI refreshes every second. If counts appear stuck, the player may have closed and reopened the GUI too quickly. The refresh task cleans up on inventory close.

World border blocking all locations

If use-world-border: true and the border is very small, most random coordinates will be outside it. Either disable world border checking or expand the border.

Next Steps