EzRTP - The random teleport plugin for Minecraft servers

EzRTP is a powerful, safe, and highly configurable random teleport (RTP) plugin for Minecraft servers. Designed for Paper, Purpur, and Spigot (1.19+), EzRTP offers advanced features like biome selection, world-border awareness, Vault economy integration, and a modern GUI for world and biome selection. Perfect for survival, adventure, and networked servers seeking a reliable, lag-free RTP experience.

Key Features:

• Compatible with Paper, Purpur, and Spigot (1.19+)
• Requires Java 17+
• Safe random teleportation with world-border and biome awareness
• Modern MiniMessage chat output
• Optional Vault economy support for paid teleports
• Lightweight, standalone JAR – easy to install and update

Why Choose EzRTP for Your Minecraft Server?

• Safe Random Teleport (RTP): /rtp finds solid ground inside the configured world border, skips unsafe blocks, and reports the final coordinates with MiniMessage styling.

  

• Multi-World & Biome Teleports: Offer curated destinations for overworld, nether, end, resource, or event worlds with an optional permission-gated GUI selector. Biome selection lets players target their favorite environments.

• Join Protection: Optionally teleport newcomers (or everyone) on join with delay and bypass permission toggles to prevent spawn camping.
• Vault Economy Integration: Charge a configurable fee for each teleport, refund on failure, and display friendly "insufficient funds" prompts. Works seamlessly with Vault and popular economy plugins.
• Performance-Conscious Queue: Throttle heavy usage with a configurable teleport queue that spaces out searches while respecting bypass permissions.
• Purpose-Built & Modular: Cleanly separates config, command, and teleport logic so you can drop the jar into any survival or network setup without conflicts.

Quick Start

1. Drop EzRTP.jar into your Paper or Purpur plugins/ directory and restart the server.
2. Edit plugins/EzRTP/config.yml to set the target world, teleport center, radius bounds, teleport cost, unsafe block list, particles, and on-join behaviour.
3. Localise the MiniMessage output in plugins/EzRTP/messages.yml (or create language-specific files like messages/en.yml) so the searching, success, failure, and queue prompts match your server's style.
4. Toggle enabled inside gui.yml and add world entries to present a permission-aware teleport selector menu.
5. Adjust queue.yml if you need to throttle teleport requests during peak hours or grant bypass permissions to staff.
6. Hook Vault + your economy plugin if you want to charge for teleports; leave cost at 0 for free usage.
7. Run /rtp reload or restart once you finish editing to apply the new settings.

Commands & Permissions

Grant ezrtp.queue.bypass to let trusted players skip the queue, and assign per-option GUI permissions directly in gui.yml.

Feature Highlights

Biome Stats Example

View detailed biome-specific statistics with /rtp stats biomes:

Heatmap Example

RTP location distribution can be visualized with a heatmap for analysis and troubleshooting.

The heatmap feature visualizes RTP location distribution for analysis and troubleshooting. It uses a professional yellow-to-red color scale (yellow = low, red = high) for maximum clarity, and images automatically center and scale to display all RTP data—ensuring every teleport is visible regardless of configuration. Grid size is fully configurable for both detailed and high-level analysis.

Simulate RTPs for Testing

Use /rtp fake <amount> to simulate a specified number of random teleports for testing, analytics, and heatmap generation. This is ideal for stress-testing, visualizing distribution, or populating statistics without affecting real players.

Usage

/rtp fake <amount>

Example:

/rtp fake 1000

Simulates 1000 random teleports in the current world.

Interactive World Selector

Enable an inventory GUI with filler items, custom icons, and per-option permissions so players can pick their landing zone from a visual menu.

How to configure

Set enabled: true in gui.yml and add world entries with custom icons, permissions, and settings for each destination world.

Safe Block Filtering

Maintain a denylist of unsafe floor blocks (lava, water, magma, powder snow, etc.) and expand it per biome or gamemode needs to ensure players always land safely.

How to configure

Edit the unsafe-blocks list in config.yml to add or remove block types that should be avoided during teleport location validation.

Chunk Readiness Checks

Skips ungenerated chunks, ensures the destination chunk is loaded, and applies configurable retry limits. Automatically unloads temporarily loaded chunks to optimize memory usage.

How to configure

Adjust max-attempts in config.yml to control how many location attempts are made before giving up on a teleport.

MiniMessage Messaging

Customize searching, success, failure, queue, and missing-world alerts with Adventure MiniMessage placeholders for rich, formatted chat output.

How to configure

Edit messages.yml with MiniMessage formatting using placeholders like <x>, <z>, <world>, <cost>, and more.

Usage

Messages automatically display during teleport operations with player-specific information filled in.

Teleport Flair

Trigger configurable particle effects at the landing spot so players know the teleport completed successfully.

How to configure

Enable particles in config.yml under the particles section, choosing type, count, and visual effects.

Economy Feedback

Configure the teleport cost, enable Vault integration automatically, and localize insufficient balance messaging for paid teleports.

How to configure

Set cost in config.yml to charge players for teleports. Requires Vault and a compatible economy plugin.

Biome Inclusion/Exclusion

Restrict teleports to approved biome lists or skip unwanted regions like oceans and deserts for targeted exploration.

How to configure

Use biomes.include and biomes.exclude lists in config.yml to control which biomes are allowed or forbidden.

Smart Biome Pre-Caching

Automatically cache pre-validated safe locations per biome to dramatically improve success rates and reduce lag when biome filters are active.

How to configure

Configure cache settings in biomes.pre-cache section of config.yml, including cache size, warmup size, and expiration time.

RTP Statistics & Monitoring

Track RTP performance with comprehensive metrics showing success rates, cache hit rates, per-biome metrics, and failure causes.

Usage

• /rtp stats - View overall RTP performance metrics
• /rtp stats biomes - Detailed biome-specific statistics

How to configure

Statistics are automatically collected and displayed. No configuration required.

Heatmap Visualization

Generate in-game maps showing RTP location distribution with grid-based statistical analysis to verify randomness and detect clustering.

Usage

/rtp heatmap [gridSize] [world]

How to configure

Grid size is configurable from 16-4096 blocks. Specify world parameter to analyze different worlds.

Rare-Biome Analytics

Audit hotspot tracking and weighted search effectiveness to ensure rare-biome targeting performs as expected.

Usage

/rtp stats rare-biomes

How to configure

Configure rare biome optimization settings in biomes.rare-biome-optimization section of config.yml.

Join-Delay Scheduler

Wait a configurable number of ticks after login before teleporting so players can load resource packs or tutorials first.

How to configure

Set on-join.delay-ticks in config.yml and enable on-join.enabled for automatic teleportation on player join.

Reload Subcommand

Hot-swap config changes without kicking players or restarting the server for seamless configuration updates.

Usage

/rtp reload

Permissions

ezrtp.reload (default: op)

Per-Player Cooldowns, Limits, & Costs

Configure per-world, per-group cooldowns, daily/weekly usage limits, and optional cost overrides with permission-based bypass.

How to configure

Edit the rtp-limits section in config.yml with world-specific and group-specific settings. Supports YAML or MySQL storage.

Configurable Teleport Countdown

Add an optional countdown before teleportation with bossbar and particle ring visuals for enhanced user experience.

How to configure

Set countdown-seconds in config.yml or use the detailed countdown block for bossbar and particle customization.

Y-Level and Debug Controls

Restrict random teleports to a min/max Y-level range and enable detailed debug logging for troubleshooting safe-location logic.

How to configure

Set min-y and max-y in config.yml for height restrictions. Enable debug-rejection-logging for detailed logging.

Protection-Aware Search

Optionally avoid protected regions/claims by integrating with popular protection plugins like WorldGuard or GriefPrevention.

How to configure

Set protection.avoid-claims: true and list protection providers in config.yml.

Per-World Daily Limit Controls

Disable daily and weekly RTP limits per world for unlimited usage in specific worlds while maintaining limits elsewhere.

How to configure

Set disable-daily-limit: true in world-specific configurations within rtp-limits.worlds section.

Flexible GUI Cooldown Behavior

Allow GUI opening during cooldowns with disabled options instead of blocking GUI access entirely.

How to configure

Set allow-gui-during-cooldown: true in rtp-limits section of config.yml.

Visible Cooldown Indicators

Show cooldown timers in GUI item lore so players can see remaining wait times immediately.

How to configure

Cooldown indicators are automatically enabled when GUI cooldown behavior is configured.

Human-Readable Cooldown Messages

Display cooldowns in readable format like "1h 30m 45s" instead of raw seconds using dedicated placeholders.

How to configure

Use <hours>, <minutes>, and <seconds> placeholders in cooldown messages in messages.yml.

Admin-Only Cache Visibility

Control biome cache information display to show stats only to administrators or all players.

How to configure

Set admin-only-cache-info in gui.yml to restrict cache information to players with appropriate permissions.

Multi-Language Support

Language-specific message files with automatic fallback to English, supporting both MiniMessage and legacy color codes.

How to configure

Create language-specific files like messages/en.yml, messages/de.yml in the plugin folder for different languages.

PlaceholderAPI Integration

Use dynamic placeholders like %player_name% in GUI item names and lore for personalized teleport menus.

How to configure

Install PlaceholderAPI plugin and use placeholders in gui.yml item names and lore. No additional configuration needed.

Rare Biome Optimization

Intelligent search strategies prioritize rare biome hotspots while maintaining randomness with configurable weighted algorithms.

How to configure

Enable and configure settings in biomes.rare-biome-optimization section of config.yml.

ForceRTP Admin Override

Force random teleportation on specific players while bypassing cooldowns and limits for administrative control.

Usage

/forcertp <player> [world]

Permissions

ezrtp.forcertp (default: op)

How to configure

Command is automatically available to players with permission. Configure force-rtp settings in force-rtp.yml.

Configuration Overview

# EzRTP teleport configuration
# Set to true to enable debug logging for rejected random teleport locations (for troubleshooting safe location logic).
debug-rejection-logging: false
# Enable or disable bStats metrics (https://bstats.org/plugin/bukkit/EzRTP/27735)
# These anonymous metrics help track plugin usage and performance across servers.
enable-bstats: true
# Optional: restrict random teleport Y-levels (inclusive). If omitted, world min/max height is used.
# min-y: 64
# max-y: 120
world: world
center:
  x: 0
  z: 0
radius:
  min: 256
  # max: 2048
  use-world-border: true
max-attempts: 32
cost: 0.0
countdown-seconds: 0 # Optional countdown before teleport (0 = disabled)
countdown:
  # Optional: override countdown seconds here instead of countdown-seconds.
  # seconds: 5
  bossbar:
    enabled: false
    title: "<yellow>Teleporting in <white><seconds></white> seconds...</yellow>"
    color: YELLOW
    style: SOLID
  particles:
    enabled: true
    # Primary Bukkit particle to use for the countdown ring.
    type: ENCHANTMENT_TABLE
    # Number of points in the ring around the player.
    points: 12
    # Ring radius in blocks.
    radius: 1.2
    # Height offset from the player's feet.
    height-offset: 0.8
    # Additional speed/extra parameter passed to the particle effect.
    extra: 0.0
    # Force the particles to render for players at long distances (1.13+ servers).
    force: false
    # Optional secondary sparkle particle.
    secondary-particle: PORTAL
    secondary-count: 6
    secondary-offset: 0.35
unsafe-blocks:
  - WATER
  - LAVA
  - MAGMA_BLOCK
  - POWDER_SNOW
  - FIRE
  - CAMPFIRE
  - SOUL_FIRE
biomes:
  # Optional: list of allowed biomes. Leave empty to allow all.
  include: []
  # Optional: list of biomes to avoid.
  exclude: []
  # Pre-caching configuration for biome-filtered RTPs
  # When enabled, the server will pre-generate and cache safe locations for biome filters,
  # significantly improving RTP success rates and reducing failed attempts.
  pre-cache:
    # Toggle pre-caching on/off. Enabled by default for better RTP performance with biome filters.
    enabled: true
    # Maximum number of locations to cache per biome (higher = better hit rate but more memory)
    max-per-biome: 50
    # Number of locations to pre-generate during server startup/reload for each configured biome
    warmup-size: 20
    # How long (in minutes) cached locations remain valid before expiring
    expiration-minutes: 10
  # Rare biome optimization for improved search efficiency
  # When enabled, uses intelligent strategies to prioritize rare biome hotspots
  rare-biome-optimization:
    # Toggle rare biome optimization on/off
    enabled: true
    # Custom list of biomes considered "rare" (leave empty for built-in list)
    rare-biomes: []
    # Enable weighted search that favors hotspots for rare biomes
    use-weighted-search: true
    # Track and maintain hotspots for rare biomes
    enable-hotspot-tracking: true
protection:
  avoid-claims: false
  providers:
    - worldguard
    - griefprevention
particles:
  enabled: false
  type: PORTAL
  count: 40
  offset:
    x: 0.5
    y: 1.0
    z: 0.5
  extra: 0.0
  force: false
on-join:
  enabled: false
  only-first-join: false
  bypass-permission: ""
  delay-ticks: 40
# RTP cooldowns and usage limits
rtp-limits:
  # Allow opening the GUI even if the current world has an active cooldown
  # When true, GUI opens but worlds with active cooldowns are disabled in the GUI
  # When false, GUI won't open if any world has an active cooldown (current behavior)
  allow-gui-during-cooldown: true
  default:
    cooldown-seconds: 300   # Cooldown in seconds between /rtp uses
    daily-limit: 10         # Max uses per day
    weekly-limit: 50        # Max uses per week
    cost: 0.0               # Optional cost override for this group
  worlds:
    world:
      # Disable daily limit for this world (overrides daily-limit and weekly-limit)
      disable-daily-limit: false
      default:
        cooldown-seconds: 300
        daily-limit: 10
        weekly-limit: 50
        cost: 0.0
      group.vip:
        cooldown-seconds: 60
        daily-limit: 50
        weekly-limit: 200
        cost: 0.0
    world_nether:
      disable-daily-limit: false
      default:
        cooldown-seconds: 600
        daily-limit: 5
        weekly-limit: 20
        cost: 0.0
      group.staff:
        cooldown-seconds: 0
        daily-limit: -1   # -1 = unlimited
        weekly-limit: -1
        cost: 0.0
  bypass-permissions:
    - ezrtp.bypass.cooldown
    - ezrtp.bypass.limit
  storage: yaml # or mysql
  mysql:
    url: jdbc:mysql://localhost:3306/mc
    user: root
    password: ""

# EzRTP MiniMessage templates
# Placeholders: <world>, <x>, <z>, <position>, <server>, <cost>, <target-biome>, <cached-locations>
teleporting: "<gray>Searching for a safe location...</gray>"
teleport-success: "<green>Teleported to <white><x></white>, <white><z></white> in <white><world></white>.</green>"
teleport-failed: "<red>Unable to find a safe location. Please try again.</red>"
teleport-failed-biome: "<red>No valid biome was found. Please try again or try a different biome filter.</red>"
world-missing: "<red>The configured world '<white><world></white>' is not available.</red>"
join-searching: "<gray>Finding you a safe place to explore...</gray>"
insufficient-funds: "<red>You need <white><cost></white> to use random teleport.</red>"
queue-queued: "<gray>You joined the random teleport queue. Position: <white><position></white>.</gray>"
queue-full: "<red>The random teleport queue is currently full. Please try again soon.</red>"
# Cooldown and usage limit messages
cooldown: "<red>You must wait <white><hours></white> <white><minutes></white> <white><seconds></white> before using /rtp again.</red>"
limit-daily: "<red>You have reached your daily /rtp limit for this world.</red>"
limit-weekly: "<red>You have reached your weekly /rtp limit for this world.</red>"
# Countdown messages
countdown-start: "<yellow>Teleporting in <white><seconds></white> seconds...</yellow>"
countdown-tick: "<gray><seconds>...</gray>"

# EzRTP teleport queue configuration
enabled: false
max-size: 0
bypass-permission: "ezrtp.queue.bypass"
start-delay-ticks: 20
interval-ticks: 40

# EzRTP GUI configuration
enabled: false
title: "<gold>Select a destination</gold>"
rows: 1
no-permission-message: "<red>You do not have permission to teleport there.</red>"
# Only show cache info (biome counts) to players with ezrtp.admin permission
admin-only-cache-info: false
# Disable cache filtering entirely (show all biomes regardless of cache status)
disable-cache-filtering: true
# Supports PlaceholderAPI placeholders in item names and lore (e.g., %player_name%)
filler:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: "<gray> </gray>"
worlds:
  overworld:
    # slot: 0
    permission: ""
    icon:
      material: GRASS_BLOCK
      name: "<green>Overworld</green>"
      lore:
        - "<gray>Teleport to a random location in the overworld.</gray>"
    settings:
      world: world
      radius:
        min: 256
        use-world-border: true
  resource:
    slot: 1
    permission: "ezrtp.gui.resource"
    icon:
      material: IRON_PICKAXE
      name: "<gold>Resource World</gold>"
      lore:
        - "<gray>Gather materials without ruining the main world.</gray>"
    settings:
      world: resource
      radius:
        min: 512
        max: 4096
        use-world-border: false

# EzRTP proxy / network configuration
enabled: false
lobby: false
ping-interval-ticks: 200
ping-timeout-millis: 1500
servers:
  skyblock:
    bungee-server: "skyblock"
    host: "127.0.0.1"
    port: 25566
    slot: 4
    permission: ""
    display-name: "Skyblock"
    hide-when-offline: false
    allow-when-offline: false
    connect-message: "<gray>Connecting you to <white><server></white>...</gray>"
    offline-message: "<red><server></red> is currently unavailable."
    icon:
      material: ENDER_PEARL
      name: "<gold><server></gold>"
      lore:
        - "<gray>Status: <status></gray>"
        - "<gray>Ping: <white><ping></white>ms</gray>"

Requirements

• Java 17 or newer
• Paper, Purpur, or SpigotMC 1.19+ server build
• Optional: Vault + an economy plugin if you want to charge for teleports
• Optional: A permissions plugin (LuckPerms, etc.) if you want granular control over /rtp reload, queue bypass, GUI option access, or cost bypasses

Support & Links

• Need help? Join our Discord and open a ticket under the EzRTP category.
• Share seeds, biome rules, or config presets on the discussion tab so other admins can jumpstart their setup.
• Pair EzRTP with EzSpawners, EzAuction, and the rest of the Ez-series utilities for a cohesive network toolkit.
• Get EzEconomy – Modern Vault Economy Plugin

Ready to launch players into adventure?

Install EzRTP and give explorers a safe, stylish way to discover your world—across every dimension!