API

RTP exposes two integration surfaces:

• a platform-agnostic addon SPI (rtp-api + rtp-core) that runs on every platform (Bukkit/Paper/Folia, Fabric, NeoForge), and
• a set of Bukkit events for Bukkit-family plugins.

Referencing RTP as a dependency

RTP is a multi-module Gradle project published on JitPack. Depend on the modules you need (rtp-api for the SPI, rtp-core for core types):

Gradle:

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

Maven:

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

Use a release tag (e.g. 3.0.1) or a commit hash for VERSION. See docs/dev/PUBLISHING.md.

Platform-agnostic addons (recommended)

Implement io.github.dailystruggle.rtp.api.addon.RTPAddon and ship a META-INF/services entry; RTP discovers it via ServiceLoader on every platform - no Bukkit plugin loader required. From onLoad() you can:

• register a config file (RTP.configs.putParser(...), re-register on Configs.onReload(...)),
• contribute an async location verifier via RTPAPI.hooks().verifiers().register(coords -> ...) (the platform-neutral replacement for Region.addGlobalRegionVerifier; see ADR-026),
• observe lifecycle via TeleportPipelineTask.teleportPostActions (the platform-neutral replacement for the Bukkit PostTeleportEvent).

A complete, commented reference lives in addons/RTP_ExampleAddon.

Verifiers run asynchronously: they must not block, perform main-thread chunk I/O, or swallow exceptions (S-004 / S-005).

Bukkit Events

For Bukkit-family-only plugins, RTP fires custom Bukkit events you can listen to:

• PlayerQueuePopEvent - when a player is selected for teleportation
• PlayerQueuePushEvent - when a player begins waiting for a new location to generate
• PreSetupTeleportEvent / PostSetupTeleportEvent - around selection tasks
• PreLoadChunksEvent / PostLoadChunksEvent - around chunk preload
• PreTeleportEvent / PostTeleportEvent - around teleportation
• RandomSelectQueueEvent - when the plugin prepares a location asynchronously
• TeleportCancelEvent - when a player cancels teleportation
• TeleportCommandFailEvent / TeleportCommandSuccessEvent - command outcome

public final class OnRandomTeleport implements Listener {
    @EventHandler(priority = EventPriority.HIGHEST)
    public void onRandomTeleport(PostTeleportEvent event) {
        // runs last, after other listeners may have adjusted the destination
    }
}

Register the listener as usual: getServer().getPluginManager().registerEvents(new OnRandomTeleport(), this);

Getting a region by name

Region region = RTP.selectionAPI.getRegion("regionName");

Adding Sub-Commands

You can add a subcommand with its own permission, parameters, and logic through the bundled command framework (commands-api):

RTP.baseCommand.addSubCommand(command);

Parameter decoding is automated. See the commands-api author guide and the command sources.