Why EzRTP?

• Player-friendly RTP – `/rtp` finds solid ground inside the configured world border, skips unsafe blocks, and reports the final coords with MiniMessage styling.
• Multi-world teleports – Offer curated destinations for overworld, resource, or event worlds with an optional permission-gated GUI selector.
• Join protection – Optionally teleport newcomers (or everyone) on join with delay + bypass permission toggles to prevent spawn camping.
• Vault economy ready – Charge a configurable fee for each teleport, refund on failure, and surface friendly "insufficient funds" prompts.
• Performance-conscious queue – Throttle heavy usage with a configurable teleport queue that spaces out searches while respecting bypass permissions.
• Purpose-built service – Cleanly separates config, command, and teleport logic so you can drop the jar into any survival setup without conflicts.

Quick Start

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

Configuring EzRTP in a Server Network

• Install EzRTP on each backend world that should provide random teleports as well as on your lobby if you want the selector GUI to offer server transfers.
• Enable the proxy integration by setting `enabled: true` inside `network.yml` everywhere EzRTP is installed. Leave `lobby` at `false` on gameplay servers so `/rtp` behaves normally.
• On your lobby server, set `lobby: true`. Any configured servers will then fill open slots in the RTP GUI alongside world entries, complete with ping/online status.
• Define each destination under `servers` using the proxy-registered `bungee-server` name, the host/port to ping, desired GUI slot, optional permission, and icon text. Toggle `hide-when-offline` or `allow-when-offline` per server to control visibility and connection attempts.
• Keep your proxy (BungeeCord/Velocity) listing in sync with the `servers` block so EzRTP can connect players using the standard `BungeeCord` plugin message channel. After editing, run `/rtp reload` on each node to pick up the changes.
• Use MiniMessage in `connect-message`, `offline-message`, and icon lore to brand the selector and give players clear network feedback.

Commands & Permissions

Command	Description	Permission
/rtp	Teleport the executing player to a random safe location.	ezrtp.use (default: true)
/rtp reload	Reload EzRTP configuration from disk.	ezrtp.reload (default: op)
/rtp stats	View RTP statistics and performance metrics.	ezrtp.stats (default: op)
/rtp stats biomes	View detailed biome-specific statistics showing top biomes by activity, success rates, and average teleport times.	ezrtp.stats (default: op)
/rtp heatmap [gridSize] [world]	Visualize cached RTP location distribution with grid-based heatmap analysis. Verify randomness, detect clustering, and troubleshoot imbalances with configurable grid resolution (16-4096 blocks).	ezrtp.heatmap (default: op)
/forcertp <player> [world]	Force random teleportation for a specified player while bypassing cooldowns and limits. Can be executed from console or in-game.	ezrtp.forcertp (default: op)
/rtp fake <amount>	Simulate a specified number of random teleports for testing, analytics, and heatmap generation.	ezrtp.fake (default: op)

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

Feature Highlights

Biome Selector GUI Example
The world selector GUI now supports biome selection for RTP.


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 uses a professional yellow-to-red color scale (yellow = low, red = high) for maximum clarity. 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
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