Smart-rtp

🌍 RandomTeleport — Wild Teleport, Reinvented

The most configurable RTP plugin for Paper — per-world cooldowns, daily use limits, interactive GUI, LuckPerms integration, and zero bloat.

---

✦ What is RandomTeleport?

RandomTeleport lets your players explore the world with a single command. Open an interactive world selector menu, pick your destination, and get teleported to a safe random location — with sounds, particles, and a countdown to keep things smooth.

Built from the ground up for Paper 1.21+, it's designed to be clean, performant, and fully customizable without a single unnecessary line.

---

✦ Why RandomTeleport?

Unlike bloated alternatives, RandomTeleport focuses on what matters:

• Zero hard dependencies — Vault and LuckPerms are optional, plugin works standalone
• Paper-native performance — Built specifically for Paper's async APIs
• One config file — Everything in config.yml, no mess
• Real-time status display — Players see cooldowns AND daily uses directly in the GUI
• True LuckPerms integration — Native API support with group inheritance resolution

---

✦ Features

🎯 Core Gameplay

• Interactive GUI — Beautiful inventory menu with world selection. Disabled worlds are hidden from regular players but visible to admins.
• Daily use limits — Limit RTP uses per world per day, with per-group overrides via LuckPerms. Resets at midnight automatically.
• Per-world cooldowns — Each world has its own cooldown configuration with group-based overrides (LuckPerms native support).
• Real-time GUI feedback — Each world button shows cooldown status AND daily use count in the item lore.
• Custom player-head icons — Display player skulls for each world instead of blocks using Paper's native PlayerProfile API.

🔒 Safety & Performance

• Smart location finder — Async multi-threaded search with configurable block blacklist, liquid avoidance, void protection, and chunk pre-loading.
• Countdown system — Configurable countdown before teleportation, cancellable on move, damage, or command.
• Blindness effect — Optional blindness during countdown and post-teleport for immersive transitions.

💰 Economy & Permissions

• Economy support — Optional Vault integration with per-group pricing and automatic refund on teleport failure.
• LuckPerms-ready — Native LuckPerms API integration with primary group → inherited groups → permission fallback resolution.
• Fine-grained permissions — Per-world access (rtp.world.<name>), cooldown bypass (rtp.bypass.cooldown.<name>), uses bypass (rtp.bypass.uses), and admin tools.

⚙️ Admin Tools

• Hot reload — /rtpadmin reload reloads configuration without server restart.
• Usage management — Reset daily counters, clear cooldowns, toggle bypasses.
• Structured logging — Every teleport, failed attempt, economy transaction, and admin action is logged by category.
• Hidden tab-completion — /rtpadmin is completely invisible to non-admin players.

🎨 Customization

• Effects system — Custom sounds and particles on departure and landing. Title + action bar support.
• Flexible configuration — World icons, GUI layout, filler items, cooldown groups, economy amounts, log categories, and async performance settings.

---

✦ Commands

Command	Description
/rtp	Open the world selector GUI
/rtp [world]	Teleport directly to a world
/rtp [player] [world]	Teleport another player (admin)
/rtpadmin reload	Reload the configuration
/rtpadmin cooldown <player> [world]	Clear a player's cooldown
/rtpadmin uses reset <player>	Reset daily use counters
/rtpadmin bypass <player>	Toggle cooldown bypass
/rtpadmin stats [player]	View teleport statistics

---

✦ Permissions

Permission	Description
rtp.use	Access to /rtp command
rtp.world.<name>	Access to specific world
rtp.bypass.cooldown	Bypass all cooldowns
rtp.bypass.cooldown.<world>	Bypass cooldown for specific world
rtp.bypass.uses	Bypass daily use limits
rtp.bypass.economy	Bypass economy costs
rtp.others	Teleport other players
rtp.admin	Access to all admin commands

---

✦ Compatibility

Server software	Paper only
Minecraft versions	1.21.0 — 1.21.4+ (all 1.21.x)
Java	21+
Optional dependencies	Vault (economy), LuckPerms (permission groups)

⚠️ Spigot is not supported. This plugin uses Paper-exclusive APIs.

---

✦ Configuration

Everything is configurable from a single config.yml — world icons (including custom player heads), GUI layout, filler items, sounds, particles, cooldown groups, daily use limits, economy amounts, log categories, async performance settings, and more. No secondary files, no clutter.

Example world configuration:

worlds:
  world:
    enabled: true
    icon: PLAYER_HEAD
    head-uuid: "ddb0f735-90ac-44e2-8578-a7dd5a1abfc5"
    display-name: "&a&lOverworld"
    cooldown:
      default-seconds: 300
      groups:
        admin: 0
        vip: 120
        default: 300
    uses:
      default-uses: 5
      groups:
        admin: 0
        vip: 10
        default: 5

---

✦ Quick Start

1. Install — Drop RandomTeleport.jar into your plugins/ folder
2. Restart — Start your Paper server (1.21+)
3. Configure — Edit plugins/RandomTeleport/config.yml to your liking
4. Reload — Use /rtpadmin reload to apply changes without restart
5. Test — Run /rtp and explore!

Optional: Install Vault for economy integration and LuckPerms for advanced group-based permissions.

---

Made with love by valival_