LeafRTPCountdownAddon¶
A shippable addon that adds two live, per-second teleport countdowns to RTP - a delay countdown
for immediate teleports ("Teleporting in N...") and a queue-position countdown for players waiting in
the public wait queue ("you are #N in the queue" -> "you're up!"). Both render as a personal on-screen
boss-bar (not chat spam) via the per-player RTPPlayer.showProgressBar / clearProgressBar API,
so the per-second updates replace one bar in place. It also doubles as the canonical reference
addon, demonstrating the four API touch-points most addons need (config + reload, an async safety
verifier, and a post-teleport observer).
It is platform-agnostic: it implements the RTPAddon SPI and is discovered via ServiceLoader,
so the same jar runs on Bukkit / Spigot / Paper / Folia and Fabric (and proxy JVMs, for the
RTPAPI-only surface) without any org.bukkit.* imports or a Bukkit plugin loader. See
leafrtp-ADR-040.
Before the move. The claim-plugin integrations (WorldGuard, Towny, Factions, …) used to ship as a separate addon. They are now bundled in the main
rtp-pluginjar — seeleafrtp-ADR-012. This addon exists as a compact teaching example so third-party authors have a starting point.
Files¶
| File | Role |
|---|---|
build.gradle |
Gradle sub-project definition. Uses compileOnly for rtp-api (the RTPAddon SPI) and rtp-core (Configs / ConfigParser / TeleportPipelineTask). No spigot-api. |
src/main/resources/META-INF/services/io.github.dailystruggle.rtp.api.addon.RTPAddon |
ServiceLoader descriptor naming the RTPAddon implementation. This is how RTP discovers the addon on every platform. |
src/main/resources/countdown.yml |
YAML config the addon ships with. Keys must match the enum constants in CountdownKeys. |
src/main/java/.../CountdownKeys.java |
Typed enum of the YAML keys. RTP's ConfigParser<E> is generic over this enum. |
src/main/java/.../RTPCountdownAddon.java |
The RTPAddon implementation. Wires everything up in onLoad(). |
src/main/java/.../CountdownHooks.java |
Two platform-agnostic teleport countdowns (immediate-teleport delay countdown via TeleportPipelineTask.setupPreActions; queue-position countdown via Region.onPlayerQueuePush / onPlayerQueuePop), rendered as per-player boss-bars through RTPPlayer.showProgressBar / clearProgressBar. Uses RTP.scheduler / RTP.serverAccessor, no org.bukkit.*. |
The four interfaces you should know¶
1. Configuration — ConfigParser<E extends Enum<E>>¶
Create an enum (CountdownKeys) whose constants name your YAML keys. Register a ConfigParser
against RTP's Configs registry so that /rtp reload picks up your file and /rtp config
tab-completes it:
RTP.configs.putParser(
new ConfigParser<>(
CountdownKeys.class,
"countdown", // YAML basename => countdown.yml
"1.0", // schema version
RTP.serverAccessor.getPluginDirectory(),
null,
RTP.configs.fileDatabase,
this.getClass().getClassLoader()));
2. Safety contribution — RTPAPI.hooks().verifiers()¶
Contribute a predicate that the pipeline evaluates asynchronously for every candidate
location. Register through the public RTPHooks facade (ADR-026 — see
docs/dev/EXTERNAL_HOOKS.md):
RTPAPI.hooks().verifiers().register(coords -> myCheckReturnsTrueIfSafe(coords));
Rules of engagement (see AGENTS.md, docs/dev/REQUIREMENTS.md section 3):
- Must return quickly; the call happens on a worker thread.
- No synchronous chunk I/O on the main thread (S-005).
- Do not swallow failures silently (S-004). Log with
RTP.log(Level.WARNING, …, t). return trueto accept the location,return falseto reject it (RTP will reroll).
For an async variant (e.g., when your check awaits a database or network call) use
RTPAPI.hooks().verifiers().registerAsync(...).
The legacy static API
GlobalRegionVerifiers.addGlobalRegionVerifier(...)still works for source compatibility but is no longer the recommended path for new addons.
3. Events — platform-agnostic post-action runnables¶
Instead of Bukkit events, observe the teleport lifecycle through the platform-agnostic runnable
lists on TeleportPipelineTask (and RTPTeleportCancel). These fire on every platform and are the
same lists the built-in Bukkit and Fabric effects handlers consume:
TeleportPipelineTask.teleportPostActions.add(task -> onPostTeleport(task));
Available lists: setupPreActions / setupPostActions, loadPreActions / loadPostActions,
teleportPreActions / teleportPostActions, cleanupPreActions / cleanupPostActions, and
RTPTeleportCancel.postActions. These callbacks may run off the main thread, so bounce any
platform-facing work onto the appropriate thread via RTP.scheduler.
4. Reload hook — Configs.onReload(Runnable)¶
When operators run /rtp reload, RTP drops its parsers and replays the hook list. Re-register your
parser inside the callback so your config survives the reload:
Configs.onReload(() -> RTP.configs.putParser(buildParser()));
Adding a combat checker (PvP / combat-tag gate)¶
RTP ships an optional pre-flight gate that refuses (or delays) /rtp while a player is
combat-tagged (off by default; operators enable it with pvpCheckEnabled: true in safety.yml).
The gate asks one question — "is this player in combat right now?" — through the single-binding
PvPCombatStateRegistry SPI. RTP answers it with a native damage-event tracker unless an addon (or
a combat plugin) binds its own authority, which then replaces the native check.
If your combat plugin is not one of the bundled integrations (PvPManager, CombatLogX, Simple Combat
Log), you do not need to wait for RTP to add a *Checker for it. Bind your own provider from
your addon's onLoad():
// Single-binding: the last bind wins and replaces RTP's native tracker (and any bundled adapter).
RTPAPI.hooks().pvpCombatState().bind(uuid -> myCombatPlugin.isTagged(uuid));
Provider is a functional interface — boolean isInCombat(UUID player) — so a lambda or method
reference is all you need. To restore RTP's native fallback, call
RTPAPI.hooks().pvpCombatState().clear() (do this from onUnload() so your provider does not
outlive your addon).
Rules of engagement (see AGENTS.md, docs/dev/REQUIREMENTS.md section 3, and
docs/dev/EXTERNAL_HOOKS.md section 6):
- Thread-safe and non-blocking.
isInCombat(UUID)is called from the command thread and the teleport pipeline. Never perform synchronous I/O or block a region/tick thread — read an in-memory tag, not a database. No synchronous chunk I/O (S-005). - Never block a teleport on a bug (S-004). A provider that throws is logged once at WARNING and treated as "not in combat", so a broken integration can never trap players. Do not rely on an exception to deny a teleport.
true= in combat (teleport refused/delayed persafety.yml),false= free to teleport.- Offline / unknown UUIDs are never combat-tagged — return
falseearly if you cannot resolve the player. - Single binding. Binding replaces whatever was bound before (native tracker or a bundled adapter). Only bind when your plugin is actually the combat authority on that server.
If you are adding a checker for a Bukkit combat plugin to the main RTP jar instead of an addon,
mirror the bundled adapters in rtp-plugin/.../softdepends/pvp/ (compile against the plugin's
published API as a compileOnly dependency, gate on Bukkit.getPluginManager().isPluginEnabled(...),
and declare the plugin as a softdepend in plugin.yml so its classes resolve at runtime). See
CombatLogXChecker / PvPManagerChecker for the pattern and PvPIntegrations for the bind site.
Build¶
From the repository root (PowerShell):
.\gradlew :addons:LeafRTPCountdownAddon:build
The jar (LeafRTPCountdownAddon-<version>.jar) lands in addons/LeafRTPCountdownAddon/build/libs/.
Because the addon is discovered via
ServiceLoader, it must be on RTP's classpath. For the full deployment / loading guide (classpath
placement per platform, lifecycle, and how to verify it loaded) see
docs/dev/ADDON_LOADING.md and
leafrtp-ADR-040.
Safety checklist (for your own addon)¶
- [ ] A
META-INF/services/io.github.dailystruggle.rtp.api.addon.RTPAddonentry names yourRTPAddon. - [ ]
onLoad()registers a parser and aConfigs.onReloadcallback for it. - [ ]
onUnload()releases anythingonLoad()allocated. - [ ] Long-running work is scheduled (
RTP.scheduler), never executed on the main thread. - [ ] Any allocated chunk ticket or pipeline task is released on every exit path (see
MemoryTracker). - [ ] Failures go through
RTP.log(Level.WARNING, msg, t)— neverprintStackTrace().