Skip to content

Building a Menu

Jump to bottom
Leaf26 edited this page Jun 17, 2026 · 1 revision

A surprising number of plugins depend on a random-teleport plugin only to put a destination menu in front of players - a clickable "where do you want to go?" GUI - and then let the RTP engine do the actual teleport. LeafRTP supports that use case as a first-class, safe, platform-neutral API. You do not need to fork the plugin, parse /rtp output, or reimplement safety checks. This page is the addon-developer guide for building a menu or GUI on top of LeafRTP.

!!! tip "You probably do not need to render LeafRTP's own menu" LeafRTP already ships an interactive menu (book-first on Paper/Folia, chat fallback elsewhere; see the player-facing Menu page). This page is for when you want to build your own GUI - a chest inventory, a custom book, a web panel - and have LeafRTP supply the data and perform the teleport.

Why this is a real API and not a hack

Legacy random-teleport plugins force integrators to either shell out to /rtp as the player (losing all type-safety and result feedback) or to copy the plugin's coordinate logic into the GUI (which re-runs unsafe synchronous rerolling on the main thread). LeafRTP draws a hard line instead:

  • LeafRTP owns safety and validation. Permission gating, cooldowns, cost, and the S-001..S-007 prohibitions (no unsafe block, no claim-protected land, no main-thread chunk I/O, no silently-discarded failures) all live behind the API. A GUI author cannot cause an unsafe teleport through this surface.
  • Your addon owns presentation and click handling. Layout, icons, and the open/close/click lifecycle are yours.
  • The only mutating call is teleport(...), which re-validates everything server-side and always completes with a result - never a silent no-op (REQ-RTP-S-004).

The result: your GUI stays trivial, and it inherits LeafRTP's asynchronous pre-generation queue, Folia-native regional scheduling, and spatial memory for free.

Happy path: a destination picker in four calls

Depend on rtp-api (the stable, semver-guaranteed surface) - not rtp-core. A full GUI needs only four RTPAPI calls.

=== "Gradle (Kotlin)"

```kotlin
repositories {
    maven("https://jitpack.io")
}
dependencies {
    compileOnly("com.github.DailyStruggle.RTP:rtp-api:VERSION")
    // metrics-api is only needed if you render a server-health tile:
    compileOnly("com.github.DailyStruggle.RTP:metrics-api:VERSION")
}
```

=== "Gradle (Groovy)"

```groovy
repositories {
    maven { url 'https://jitpack.io' }
}
dependencies {
    compileOnly 'com.github.DailyStruggle.RTP:rtp-api:VERSION'
    compileOnly 'com.github.DailyStruggle.RTP:metrics-api:VERSION'
}
```

=== "Maven"

```xml
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>
<dependencies>
  <dependency>
    <groupId>com.github.DailyStruggle.RTP</groupId>
    <artifactId>rtp-api</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
  </dependency>
</dependencies>
```

import io.github.dailystruggle.rtp.api.RTPAPI;
import io.github.dailystruggle.rtp.api.RtpTarget;
import io.github.dailystruggle.rtp.api.RtpTargetStatus;
import java.util.List;
import java.util.UUID;

void openPicker(UUID playerId) {
    // 1. Ask LeafRTP which destinations THIS player may use (permission gates already applied).
    List<RtpTarget> targets = RTPAPI.getAllowedTargets(playerId);

    for (RtpTarget target : targets) {
        // 2. Decorate each slot with the player's live status (cooldown / cost / availability).
        RtpTargetStatus status = RTPAPI.getTargetStatus(playerId, target);
        addSlot(target, status); // YOUR rendering: icon, lore, lock/greyed-out, price tag
    }
}

void onSlotClicked(UUID playerId, RtpTarget target) {
    // 3. Submit a validated teleport intent. LeafRTP re-checks everything server-side.
    RTPAPI.teleport(playerId, target).thenAccept(result -> {
        if (result.isSuccess()) {
            // teleported; result.location() is the landing spot
        } else if (result.isQueued()) {
            // accepted onto the cross-server wait queue (network mode)
        } else {
            // result.reason() e.g. ON_COOLDOWN / NO_SAFE_LOCATION / NO_PERMISSION ...
            // result.message() is a human-readable explanation. Never silent (S-004).
        }
    });
}

That is the whole integration. The teleport future always completes with an RTPResult, so your GUI can always give the player feedback.

!!! warning "rtp-api entry points throw before core loads" Every RTPAPI method throws IllegalStateException if called before rtp-core has finished loading (REQ-RTP-S-006) - it never returns null or silently no-ops. Call these from inside your addon's onLoad() (where core is guaranteed loaded) or in response to a player action, not from a static initializer.

The four building blocks

1. RTPAPI.getAllowedTargets(UUID) - what to show

Returns an immutable List<RtpTarget> of the destinations the player is actually permitted to use, with the same permission gates the /rtp command applies already resolved. The first element is always RtpTarget.defaultRegion() (a bare /rtp is always offered), followed by any named regions/worlds the player passes the permission check for. Render the list verbatim - one slot per entry.

2. RtpTarget - addressing a destination

An immutable selector that hides all rtp-core region internals. Build one with a static factory:

Factory Resolves to
RtpTarget.defaultRegion() the server default region (a bare /rtp)
RtpTarget.region("spawnlands") a region by its configured name
RtpTarget.world("world_nether") the region configured for a named world
RtpTarget.network("backend-b", "wilds") a region on a peer backend (network mode); routed via the cross-server wait queue

3. RTPAPI.getTargetStatus(UUID, RtpTarget) - how to decorate a slot

Returns a point-in-time RtpTargetStatus for decorating one button. It is read-only - it never teleports or charges the player.

Accessor Use for
availability() enum: READY / ON_COOLDOWN / NO_PERMISSION / NO_FUNDS / DISABLED / UNKNOWN
isReady() convenience boolean for "clickable right now"
remainingCooldownMillis() grey-out timer / countdown lore
cost() price tag lore
iconBlock() / environment() / label() optional display hints (may be null)

!!! note "UNKNOWN is a real value, plan for it" The Availability enum may grow over time, and a null delegate result degrades to UNKNOWN rather than throwing. Always have a sensible fallback rendering for an availability you do not recognise.

4. RTPAPI.teleport(UUID, RtpTarget) - the only mutating call

CompletableFuture<RTPResult> teleport(UUID player, RtpTarget target);
boolean cancel(UUID player);            // cancel a pending/in-flight teleport
boolean isWarmingUp(UUID player);       // a teleport requested but not yet completed?
int     queueDepth(RTPWorld<?> world);  // pre-verified ready locations for a world

Permission, cooldown, cost, and every S-00x safety check are enforced inside this call, regardless of what getAllowedTargets / getTargetStatus returned. Treat those reads as display hints and teleport(...) as the authority.

Understanding RTPResult

The teleport future always completes with an RTPResult so you can always inform the player (S-004 - no silent failures):

RTPAPI.teleport(playerId, RtpTarget.defaultRegion()).thenAccept(result -> {
    switch (result.reason()) {
        case SUCCESS           -> /* result.location() is non-null */;
        case QUEUED            -> /* accepted onto the cross-server wait queue */;
        case ON_COOLDOWN, COOLDOWN -> /* show remaining cooldown */;
        case NO_SAFE_LOCATION  -> /* pipeline found nothing safe */;
        case ALREADY_TELEPORTING, LOCKED, RELOADING, PLAYER_OFFLINE,
             INVALID_TARGET, CANCELLED, ERROR -> /* result.message() explains */;
        default -> /* forward-compatible fallback */;
    }
});

isSuccess() and isQueued() are both non-failure outcomes (a queued request will complete on a remote backend after transfer). On success location() is non-null; on failure it is null and message() carries a human-readable explanation.

Optional: a server-health dashboard tile

If your menu shows live server health, read a sampled snapshot - it is produced by the metrics sampler, never computed on your thread, so it adds no main-thread cost and no chunk I/O:

import io.github.dailystruggle.metrics.api.MetricsSnapshot;

MetricsSnapshot snap = RTPAPI.getMetricsSnapshot();   // TPS, MSPT, player count, heap, ...
// On Folia, per-region detail:
RTPAPI.getRegionSamples().forEach(sample -> /* region-scoped tile */);

Unsampled fields report MetricsSnapshot.UNSAMPLED; check before displaying.

The reference addon: RTP_GuiAddon

addons/RTP_GuiAddon is a complete, drop-in destination picker built only on the stable rtp-api surface above (it deliberately does not link rtp-core, proving the public surface is sufficient for a full GUI). It is structured like the plugin itself - a platform-neutral core plus thin per-platform renderers:

Module Platform Responsibility
rtp-gui-common none the menu model, guimenu.yml config, the render seam, the teleport submit. No org.bukkit.*.
rtp-gui-bukkit Bukkit/Paper/Folia chest-inventory renderer + click listener
rtp-gui-fabric Fabric (MC 26.x) server-side container (ChestMenu) screen renderer
rtp-gui-neoforge NeoForge (MC 26.x) server-side container screen renderer
rtp-gui none (assembly) the single multi-loader distributable jar

It demonstrates the security boundary precisely: one slot per getAllowedTargets(UUID) target, each decorated via getTargetStatus(UUID, RtpTarget), a health tile from getMetricsSnapshot(), and click -> teleport(UUID, RtpTarget). The Bukkit renderer cancels every click on the read-only chest (anti-dupe) and identifies its own inventory by a custom InventoryHolder, never by a spoofable title.

!!! tip "Read it before writing your own" The reference addon is the fastest way to see the whole pattern end-to-end, and it doubles as a working template. Build it from the repo root with .\gradlew :addons:RTP_GuiAddon:rtp-gui:build.

Two ways to wire the open trigger

Replace what a bare /rtp does (root action)

If you want a bare /rtp (no arguments) to open your GUI instead of teleporting, bind the root-action hook. Sub-commands (/rtp region=..., /rtp admin, ...) are never affected:

RTPAPI.hooks().rootAction().bind((uuid, feedback) -> {
    openMyMenu(uuid);
    return true;   // true = handled (classic teleport suppressed); false = defer to classic /rtp
});

This is the seam RTP_GuiAddon uses so a bare /rtp opens the picker. See Hooks and verifiers for the full hook catalog.

Your own command

Register your own /rtpgui-style command in your plugin/mod as usual and call openMyMenu(...) from it - LeafRTP imposes nothing here.

Bring your own renderer (advanced)

LeafRTP's internal menu is built on a platform-neutral SPI in rtp-api (MenuModel, MenuPage, MenuLine, MenuFragment, MenuAction, MenuOpenRequest, and MenuRenderer). If you want LeafRTP to drive your renderer with its menu content (rather than building your own model), implement MenuRenderer:

public interface MenuRenderer {
    void render(UUID playerId, MenuModel model);  // throws IllegalStateException pre-core-load (S-006)
}

An inventory GUI is then "just another MenuRenderer" - LeafRTP does not write it for you. Most integrators do not need this; the four RTPAPI calls above are simpler and decouple you from the menu model's shape. Reach for MenuRenderer only when you specifically want to re-skin LeafRTP's own pages.

Safety checklist for your menu addon

  • Depend on rtp-api (compileOnly / provided), not rtp-core, unless you need an unstable introspection hook.
  • Call RTPAPI methods only after core is loaded (inside onLoad() or in response to player actions) - they throw pre-load (S-006).
  • Treat getAllowedTargets / getTargetStatus as display hints; teleport(...) is the authority.
  • Always handle the RTPResult (including UNKNOWN/unrecognised reasons) so the player gets feedback (S-004).
  • Do your own anti-dupe on click handling (cancel clicks on a read-only inventory; identify your inventory by holder, not title).
  • Never load chunks or run blocking work on the main thread - the teleport is async and LeafRTP handles it.

See also

  • Addon development - the developer landing page and happy path.
  • Hooks and verifiers - the root-action hook and the full behavior-modification catalog.
  • Example addon - the RTPAddon lifecycle and config seam.
  • Menu - LeafRTP's own player-facing menu (admin/player perspective).
  • API - the broader rtp-api reference.
Start here
Design
Setup
Config files
Usage
Development

Clone this wiki locally