Roam | Random Wild Teleport -----
Advanced asynchronous random teleport (RTP) plugin for Paper, Purpur and FoliaRoam
Async, GUI-driven random teleport for Paper / Purpur / Folia
The wild has never been one click away.
Source-available · Folia-native · 12 claim plugins detected · Iris + TerraformGenerator
support · EN / ES / PT_BR
Roam requires Paper, Purpur, or Folia. Spigot is not supported — Roam relies on Paper's Adventure API,
async chunk loading, and Folia region/global/async schedulers, none of which Spigot exposes. If you're on Spigot,
switch to Paper first (drop-in replacement, identical config).
Supported MC range: 1.21.1 → 1.21.11 → 26.1.0 → 26.1.1 → 26.1.2
(Paper rebranded its versioning after 1.21.11 — there is no 1.21.12; the next stable is 26.1.0. Roam works on every
version in this range thanks to Paper's binary forward compatibility.)
Java runtime: 21+
✦ Why Roam
- Production-grade performance — measured at 0.91% server thread CPU on a live multi-world Folia node (Spark profiler). The two main hotspots are the command dispatcher (0.51%, proportional to /rtp usage) and the Folia region scheduler return to the player thread (0.40%) after async execution. No hidden overhead, no idle loops, and no memory leaks. Built async-first by design, not by accident.
- Async parallel candidate search — multiple candidates evaluated concurrently (configurable 1–16). Reduces p95 latency from 5–10s (sequential) to 1–2s on dense or heavily-claimed worlds.
- Folia-native architecture — uses region, global, and async schedulers throughout. Lazy-expiry concurrent maps with no per-player tasks running on region threads.
- 12 region/claim plugins supported — WorldGuard, GriefPrevention, GriefDefender, Lands, RedProtect, Residence, Towny, Factions (FactionsUUID, Saber, Kitteh), KingdomsX, HuskClaims, HuskTowns, CrashClaim. Owner-aware bypass supported on 8 of them.
- Custom generator support — Iris (auto-detects biome registry from IrisDimension) and TerraformGenerator (full BiomeBank exposure, including SCARLET_FOREST, BADLANDS_CANYON, ~85 biomes). Fully reflective; gracefully degrades if generators are absent.
- Built-in interactive GUI — chest-based interface with biome selector, favorites, history, stats, and world selection. No addons required. All text is configurable via gui.yml without recompiling.
- Three storage backends — YAML (default), SQLite (file-based), and MariaDB (external). Drivers are shaded; cooldowns and cache persist across restarts when using SQL. Automatic fallback to YAML if SQL is unavailable.
- Internationalization included — English, Spanish, and Brazilian Portuguese provided out of the box. Supports custom locales. Compatible with MiniMessage and legacy & color codes.
- Source-available — fully readable, buildable, and modifiable. Designed with premium-level engineering standards at no cost.
✦ Top features at a glance
- Economy integration (Vault) — optional cost per RTP, with per-world overrides and permission-based free tiers.
- First-join RTP / teleportation — automatically teleports new players into the wild with temporary damage immunity on arrival.
- Custom locations / presets (spawn-points mode) — admin-defined named anchors with per-point spread and weighted random selection.
- Per-permission RTP setups — configure different zones, worlds, cooldowns, and costs for VIP or premium ranks without duplicating configs.
- Cooldown tier permissions — supports roam.cooldown.<seconds> (lowest value takes priority) and roam.cooldown.reduction.<%> with HIGHEST, ADDITIVE, or MULTIPLICATIVE stacking modes.
- Sign-based RTP — place a [RTP] sign and right-click to teleport. Includes automatic cyan rewrite to prevent conflicts with vanilla text.
- Citizens NPC integration — click-to-RTP NPCs with multiple modes (RANDOM, BIOME, GUI, WORLD_PICKER). No additional plugins required.
- Post-teleport invulnerability — short damage immunity window with PvP-safe logic (cancels on attack in both directions).
- Audit log — optional append-only log (CSV-style) of all RTP activity. Thread-safe and compatible with Folia; player names are properly escaped.
- Density radar — /rtp check performs a sample search without cooldown or cost, allowing players to preview RTP density before teleporting.
- Hunger gate — optional requirement (global.require-hunger: <0..20>) for survival or roleplay servers.
- EssentialsX /back integration — unified back-stack support between Roam and EssentialsX.
- HMCCosmetics compatibility — prevents teleporting players while editing cosmetics.
- CombatLogX compatibility — blocks RTP usage while players are combat-tagged.
- Public API + events — gg.roam.api available for developers, including 3 cancellable events.
- PlaceholderAPI support — includes 9 placeholders (cooldown state, history count, total RTPs, distance, discovered biomes, last biome, etc.).
- Anonymous bStats metrics — includes 14 custom charts; can be disabled via plugins/bStats/config.yml.
- Built-in update checker — uses GitLab Releases (v4 API) with a 6-hour cache. Only notifies operators in console, no spam.
✅ = first-class built-in feature, ⚠ = available but indirect (addon, partial, or via separate library), ✗
= not available
Spot a feature missing or wrong? Open an issue on the
GitLab tracker — we'd rather close real gaps than carry an
outdated comparison.
= not available
| Feature | Roam | BetterRTP | Essentials /rtp |
| Async parallel search | ✅ 1–16 candidates | ⚠ Single-threaded | ✗ |
| Folia support | ✅ Native | ✗ | ✗ |
| Built-in GUI | ✅ | ⚠ Addon required | ✗ |
| Economy integration (Vault) | ✅ Per-world + tier overrides | ✅ | ✗ |
| First-join RTP | ✅ + arrival invulnerability | ✅ | ✗ |
| Custom locations / presets | ✅ Spawn-points (weighted random) | ✅ /rtp location <name> | ✗ |
| World overrides (nether → overworld) | ✅ target-world | ✅ | ✗ |
| Permission tiers / groups | ✅ Setups + tiered cooldowns | ✅ | ✗ |
| Biome-targeted RTP | ✅ Vanilla + Iris + TerraformGenerator | ✅ Vanilla | ✗ |
| Region / claim awareness | ✅ 12 plugins (owner + trusted bypass) | ✅ Generic "Respect" | ✗ |
| WorldGuard custom flag | ✅ roam-deny + flag-only mode | ✗ | ✗ |
| Pre-warmed location cache | ✅ Persistable to SQL | ✗ | ✗ |
| Chunk preload | ✅ Configurable radius | ⚠ via PaperLib | ✗ |
| Storage backend | ✅ YAML / SQLite / MariaDB | YAML | YAML |
| Audit log | ✅ Folia-safe CSV | ✗ | ✗ |
| Density preview / radar | ✅ /rtp check | ✗ | ✗ |
| Citizens NPC integration | ✅ 4 actions, no addon | ✗ | ✗ |
| RTP on death | ✅ Per-world (bed/anchor honoured) | ✗ | ✗ |
| Sign-based RTPs | ✅ With cyan anti-collision | ✅ | ✗ |
| Cross-dimension biome validation | ✅ Refuses with hint | ✗ | ✗ |
| Action-bar feedback (search + warmup) | ✅ | ✗ | ✗ |
| bStats anonymous metrics | ✅ 14 custom charts | ✗ | ✗ |
| Built-in update checker | ✅ GitLab + on-disk cache | ✅ | ✗ |
| Three cooldown stacking modes | ✅ HIGHEST / ADDITIVE / MULTIPLICATIVE | ✗ | ✗ |
| Live config edit (no /reload) | ✅ /roamadmin edit | ✅ /rtp edit | ✗ |
| Hunger gate | ✅ | ✗ | ✗ |
| Public API + cancellable events | ✅ gg.roam.api | ✅ Internal | ✗ |
| Multi-language | ✅ EN / ES / PT_BR | ✅ Lang files | ⚠ |
Spot a feature missing or wrong? Open an issue on the
GitLab tracker — we'd rather close real gaps than carry an
outdated comparison.
- Drop Roam-<version>.jar into your plugins/ folder.
- Start the server once. Roam writes a default config and three message files into
plugins/Roam/.
- (Optional) Install soft-depends — Vault, PlaceholderAPI, EssentialsX, Iris, TerraformGenerator, Chunky,
Citizens, HMCCosmetics, CombatLogX, any of the 12 region-protection plugins. Roam picks them up on next restart and
the startup banner reports which hooks are live.
- Edit plugins/Roam/config.yml: add a worlds.<your-world-name> block
(or rename the default), set biome-finder.enabled: true if you want the biome finder, set
storage.type: SQLITE for zero-setup persistence.
- /roamadmin reload (or restart). Run /rtp in-game to verify;
/roamadmin info prints active hooks and storage backend.
they list every hook, the storage backend, and the world count Roam is tracking.
| Command | Description |
| /rtp | Instant random teleport (or open GUI, depending on gui.open-on-command) |
| /rtp <world> | RTP within a specific world |
| /rtp <player> [world] | RTP another player (requires roam.others) |
| /rtp gui (alias menu) | Force-open the GUI |
| /rtp biome [name] | No name → biome picker GUI. With name → teleport to that biome. |
| /rtp back | Return to your last RTP location |
| /rtp save <name> | Save current location as favorite |
| /rtp del <name> | Delete a favorite |
| /rtp favorites | List favorites |
| /rtp history | View teleport history |
| /rtp stats | View your RTP stats |
| /rtp go <favorite> | Teleport to one of your favorites |
| /rtp check (alias radar) [world] | Pre-flight density radar — sample search, no cooldown / charge |
| /roamadmin reload | Reload config and language file |
| /roamadmin version | Print plugin version |
| /roamadmin info | Print active hooks, region integrations, storage backend, world count |
| /roamadmin resetcooldown <player> | Clear a player's persistent cooldown |
| /roamadmin unstick <player> | Force-clear stuck teleport state |
| /roamadmin pregen <world> | Delegate to Chunky to pre-generate the configured RTP zone |
| /roamadmin edit <world> <field> <value> | Live-edit per-world config without /reload |
Aliases: /wild, /randomtp, /wilderness,
/roam
Tab-completion is permission- and context-aware: 1st-arg suggestions include subcommands, accessible worlds, and (with
roam.others) online players; 2nd-arg suggestions adapt per subcommand (biomes filtered by source mode,
favorites scoped to the player, etc.).
| Permission | Default | Purpose |
| roam.use | true | Use /rtp |
| roam.biome | true | Use the biome finder |
| roam.back | true | /rtp back |
| roam.favorites | true | Save and use favorites |
| roam.world.<name> | true | Per-world access (roam.world.* for all) |
| roam.others | op | Teleport other players |
| roam.bypass.cooldown | op | Skip cooldown |
| roam.bypass.warmup | op | Skip warmup countdown |
| roam.bypass.cost | op | Skip economy cost |
| roam.bypass.favorites | op | Skip the favorites cap |
| roam.bypass.combat | op | Skip the CombatLogX block |
| roam.bypass.hunger | op | Skip the hunger gate |
| roam.bypass.region.<id> | op | Land inside a specific claim system (use roam.bypass.region.* for all) |
| roam.bypass.region.own | true | Allow players to land inside their own claims |
| roam.bypass.region.trusted | true | Allow players to land inside claims where they are a trusted member |
| roam.cooldown.<seconds> | — | Tier override; smallest matching number wins |
| roam.cooldown.reduction.<%> | — | Percent reduction; combined per cooldown.reduction-stacking |
| roam.setup.<id> | — | Gate for a per-permission setup defined under setups: |
| roam.sign.create | op | Place a [RTP] sign |
| roam.sign.use | true | Right-click a [RTP] sign |
| roam.check | true | Use /rtp check |
| roam.admin | op | Admin commands |
Async & concurrency
- Parallel candidate search — N candidates evaluated simultaneously. First safe wins; rest become no-ops. Cuts
p95 latency 5–10s → 1–2s on dense worlds.
- Two layers of timeouts — global (5–600s, default 60) and per-candidate (500–60000ms, default 8000). Stuck
slots are abandoned and replaced; one bad slot never freezes the whole search.
- Folia-first scheduling — single Scheduler utility picks RegionScheduler / AsyncScheduler /
GlobalRegionScheduler when available, falls back to Bukkit otherwise.
- Lazy-expiry concurrent maps — invulnerability state evicted on first read after deadline; no per-player
removal task on region threads.
- Async data flush with dirty-flag tracking — favorites/history/stats writes mark entries dirty; one async
flush every 30s coalesces all dirty players. Reads always hit memory.
- Three backends — NONE (YAML), SQLITE (single file, zero setup), MARIADB (external server). Drivers shaded;
admins manage no classpath entries.
- Composite per-world cooldown PK — roam_cooldowns(player_uuid, world) so per-world
isolation works at the database layer, not just in memory.
- Dual-path fallback — if SQL is unreachable at startup, Roam logs a warning, falls back to YAML, and finishes
enabling. Plugin never refuses to enable because of a storage hiccup.
- Indexed location-cache table — pre-warmed safe locations persist across restart so the first /rtp after
reboot doesn't pay the search cost.
- 12 plugins, all auto-detected when present. WorldGuard / GriefPrevention / Towny use build-time APIs; the
other 9 bind reflectively with version-tolerant fallbacks (multiple accessor names, Optional<UUID> vs raw UUID, etc.)
so minor upstream API drift doesn't require recompile.
- Owner-aware bypass on 8 plugins — GriefPrevention, GriefDefender, Lands, WorldGuard, Residence, Towny,
RedProtect, Factions.
- Trusted-member bypass — GriefPrevention, GriefDefender, Lands, Towny, WorldGuard. Per-player
roam.bypass.region.trusted toggle.
- WorldGuard custom flag — registers roam-deny StateFlag. With flag-only-mode: true, only WG
regions carrying the flag block RTP; every other WG region is wild.
- Per-(world, hook) toggles — disable any of the 12 hooks per-world, or disable region-protection entirely
per-world (e.g., for resource worlds).
- Optional LRU+TTL cache of isProtected() results for high-concurrency servers.
- Distinct claim-rejection telemetry — teleport-fail-region message when ≥70% of candidates were
rejected by region checks.
- Move threshold (default 0.5 blocks) — strict cancellation during warmup.
- Body block blacklist separate from foot block blacklist — prevents "landed on top of lava but my head's
underwater in lava" cases.
- Min/max Y clamp — never spawns players in the void or at the build-limit ceiling.
- Cross-dimension biome validation — refuses /rtp biome for biomes outside the player's dimension with a clear
hint.
- Wardrobe / combat / hunger gates — each bypassable per-permission.
- Bed/anchor respawn exclusion from RTP-on-death — players who set a respawn point still respawn there.
- Cancel-on-attack covers both directions — invulnerability ends if the protected player takes damage
or deals damage. Closes the /rtp-into-PvP-for-free-first-hit exploit class.
- Per-permission setups — setups.<id> blocks override world defaults when the permission is held;
descending priority resolution.
- Cooldown tier perms — roam.cooldown.<seconds>; smallest matching number wins.
- Three reduction stacking modes — HIGHEST (max), ADDITIVE (capped sum), MULTIPLICATIVE (compound on residual;
never bricks the economy).
- Per-world cooldown isolation — cooldown.per-world: true tracks separate cooldowns per (player,
world).
- 14 bStats charts — language, platform, per-hook availability, GUI / cache enablement, region-protection
presence, active hook count, storage backend.
- Built-in update checker — GitLab Releases v4 + 6h on-disk cache. Op-only console notice; no nag spam.
- Audit log — Folia-safe synchronised writer; CSV-escaped player names; reopened on /roamadmin reload for
external rotation.
- /roamadmin info single-command diagnostic — lists every active hook, region integration, storage backend,
world count.
- /roamadmin edit live mutation of 12+ per-world fields without /reload.
- Coloured ASCII startup banner with version + world count + per-hook checkmark; matching shutdown banner for
log scoping.
Every player-facing string in the chest menus lives in
gui.yml, not in code. Translate,
rebrand, or rewrite without recompiling:
RoamMenuHolder token (not title-substring matching), so admins can rewrite titles freely without breaking click
routing.
rebrand, or rewrite without recompiling:
- Inventory titles for each menu (main, biome picker, world selection, favorites, history, stats)
- Item names + lore for every button
- Pagination strings (Page {page} / {total})
- World environment labels (OVERWORLD / NETHER / THE_END)
- Biome-source labels (Iris pack biome / TerraformGenerator bank / Vanilla biome)
- Time-ago and cooldown formatters
- Stats tile labels
- Click-hint footer text
RoamMenuHolder token (not title-substring matching), so admins can rewrite titles freely without breaking click
routing.
Roam ships with three translations bundled:
To add your own translation: copy any messages_xx.yml into the plugin folder, rename,
translate, set language: xx in config.yml. PRs adding new languages
welcome.
| Code | Language | File |
| en | English (default) | messages_en.yml |
| es | Español | messages_es.yml |
| pt_BR | Português do Brasil | messages_pt_BR.yml |
To add your own translation: copy any messages_xx.yml into the plugin folder, rename,
translate, set language: xx in config.yml. PRs adding new languages
welcome.
Code (YAML):
global:
warmup : 3 # seconds before teleport
cooldown : 300 # per-player cooldown in seconds
search-parallelism : 4 # parallel candidates (1–16)
cancel-on-damage : true
cancel-on-move : true
post-teleport-invulnerability:
enabled : true
duration-seconds : 5
data:
first-join-rtp:
enabled : false # opt-in: RTP first-time joiners
world : "world"
audit-log:
enabled : false # append-only RTP log
biome-finder:
enabled : false # opt-in
source : AUTO # AUTO | IRIS_ONLY | TERRAFORM_ONLY | VANILLA_ONLY | MIXED
max-radius : 10000
worlds:
world:
enabled : true
shape : circle # circle (default) | square
min-radius : 100
max-radius : 5000
respect-world-border : true
biome-blacklist : [OCEAN, RIVER, FROZEN_OCEAN ]
storage:
type : NONE # NONE | SQLITE | MARIADB
language : en # en | es | pt_BR | <your code>
Roam exposes a small, stable API in the
gg.roam.api package:
import gg.roam.api.RoamAPI ;
import gg.roam.api.RoamProvider ;
RoamAPI roam = RoamProvider. get ( ) ;
if (roam != null ) {
roam. randomTeleport (player ) ;
}
Three cancellable Bukkit events:
Check getApiVersion() for capability branching.
Code (Java):
import gg.roam.api.RoamAPI ;
import gg.roam.api.RoamProvider ;
RoamAPI roam = RoamProvider. get ( ) ;
if (roam != null ) {
roam. randomTeleport (player ) ;
}
- RoamPreTeleportEvent — before search starts. Cheapest veto point. setCancelReason(String) for custom
messages.
- RoamLocationFoundEvent — after a safe location is picked, before chunk preload. Mutable destination via
setLocation().
- RoamPostTeleportEvent — after the player has arrived. Use for achievements, audit, after-effects. Fires on
the player's region thread on Folia.
Check getApiVersion() for capability branching.
Detected automatically on enable; absent integrations degrade gracefully (no error, no console spam). The startup
banner reports which hooks are live.
Region / claim plugins (12):
WorldGuard, GriefPrevention, GriefDefender, Lands, RedProtect, Residence, Towny, Factions (FactionsUUID + Saber +
Kitteh-fork), KingdomsX, HuskClaims, HuskTowns, CrashClaim
Other integrations:
Vault, PlaceholderAPI, EssentialsX, Iris, TerraformGenerator, Chunky, Citizens, HMCCosmetics, CombatLogX
banner reports which hooks are live.
Region / claim plugins (12):
WorldGuard, GriefPrevention, GriefDefender, Lands, RedProtect, Residence, Towny, Factions (FactionsUUID + Saber +
Kitteh-fork), KingdomsX, HuskClaims, HuskTowns, CrashClaim
Other integrations:
Vault, PlaceholderAPI, EssentialsX, Iris, TerraformGenerator, Chunky, Citizens, HMCCosmetics, CombatLogX
Support
- Bug reports / feature requests: GitLab issue
tracker
- Source code: gitlab.com/naren.sanchez.h/roam
- Security issues: email [email protected] directly (please don't file public issues for security)
- Translations: PRs welcome — see the
Translation MR
template
Roam is source-available, not open-source.
Free to: install, run, and modify on your own server (commercial servers included).
Not allowed: redistribution or publishing as a fork-as-product.
Full terms: EULA (English) ·
EULA (Español)
Made with care by Naren Sánchez
Built for the FrontierCraft network and battle-tested in production.
Built for the FrontierCraft network and battle-tested in production.
Resource Information
Author:
----------
Total Downloads: 52
First Release: May 6, 2026
Last Update: Jun 10, 2026
Category: ---------------
All-Time Rating:
Find more info at gitlab.com...1 ratings
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings