Plugin Setup

The plugin is the in-game half of Traverse. It never talks to the world seed or the database itself; it identifies qualifying supporters, asks the Traverse API for a one-time access link, and shows it to the player.

Requirements

Requirement	Detail
Server software	Paper
Minecraft	1.21.7 or newer
API version	1.21
Built against	io.papermc.paper:paper-api:1.21.7-R0.1-SNAPSHOT
Java	21
Soft dependency	LuckPerms
Also needed	A reachable Traverse web app (see Installation)

Paper 1.21.7 is a hard floor

The onboarding prompt uses Paper's Dialog API, which first appears in 1.21.7. The plugin will not run on an older Paper build, or on Spigot or CraftBukkit.

LuckPerms is a soft dependency. Without it the plugin still runs, but group-based qualification cannot resolve any groups, so only operators and players holding the permission node directly will qualify.

Install steps

1. Place traverse-<version>.jar in your server's plugins/ directory.
2. Start the server once. The plugin writes plugins/Traverse/config.yml with placeholder values.
3. Fill in base-url and api-key (below).
4. Run /traverse reload to apply the changes without a restart.

Configuration

plugins/Traverse/config.yml:

# Bump this when a release adds, removes, or renames a key below, so an
# existing config.yml is migrated instead of going stale.
file-version: 2

traverse-api:
  base-url: "https://traverse.example.net"
  api-key: "CHANGE_ME"

Key	Meaning
base-url	Root URL of your Traverse web app. Must match the app's own PUBLIC_BASE_URL, because access links are built from that value.
api-key	Shared secret for the plugin API. Must equal the web app's PLUGIN_API_KEY.

No world id to configure

The web app now runs exactly one world per installation, so there is nothing to point the plugin at beyond the deployment itself. The active-world-id key that older releases carried has been removed; a config.yml left over from one is migrated automatically (file-version goes to 2 and the dead key is dropped).

The config file is version tracked, so a config.yml left over from an older release has new keys backfilled with their defaults on load, keeping your existing values.

Treat api-key as a credential

It authenticates every plugin call, including issuing access links for any entitlement. Do not commit it, and rotate it on both sides at once if it leaks.

Commands

Command	Permission	Description
/traverse	none	Issues the player a fresh single-use access link, plus a backup access code. Players only.
/traverse status	traverse.admin.status	Reports server reachability, the world's name and state, its open and close times, and whether the plugin and server versions are compatible. The quickest in-game check that the plugin is wired up correctly.
/traverse reload	traverse.admin.reload	Reloads config.yml, including the version migration pass, and re-applies base-url and api-key to the live API client.

Both the join handler and /traverse call the API off the main thread, so a slow or unreachable web app slows the response to that player rather than the server tick.

Permissions

Node	Default	Description
traverse.supporter	false	Qualifies a player for a PERMISSION mode world that lists this exact node.
traverse.admin.status	op	Allows /traverse status.
traverse.admin.reload	op	Allows /traverse reload.

Server operators bypass the world's qualification check entirely, so staff can walk the whole flow without joining a supporter group.

What the plugin does on join

1. Reads the player's LuckPerms groups, and checks whether they hold traverse.supporter.
2. Calls the API to create the player and entitlement if they qualify.
3. Asks whether an onboarding dialog should be shown, and shows it once. Whether the player accepts or dismisses it, it is never shown again.
4. If the campaign is inside its closing window and the player has access but has not revealed yet, sends one [Open Traverse] reminder in chat. Each player is reminded at most once.

If base-url or api-key is still at its placeholder, or the web app cannot be reached, the plugin cannot do any of this; /traverse tells the player so, and /traverse status shows staff what is wrong.

Version compatibility

The plugin stamps every request with its version, and the server treats the two as compatible when they share a major and minor version (the patch may differ). On startup, and on /traverse status, the plugin checks the server is reachable and the versions line up, and logs a warning if they do not. Keep the plugin and the web app on matching major.minor releases.

Building from source

The plugin is a Maven module inside the Traverse repository.

Setting	Value
Group ID	dev.anchorlight
Artifact ID	traverse
Main class	dev.anchorlight.traverse.TraversePlugin
Java source/target	21
Paper API	1.21.7-R0.1-SNAPSHOT

mvn package   # produces target/traverse-<version>.jar
mvn test      # JUnit 5 + Mockito suite

The shaded jar in target/ is the one to deploy. Tests cover LuckPerms qualification, the API client, and the command, with the dialog presenter behind an interface so the command can be driven without a live server.