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)

:::caution 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, api-key, and active-world-id (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: 1

traverse-api:
  base-url: "https://traverse.example.net"
  api-key: "CHANGE_ME"
  active-world-id: "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.
active-world-id	The World id this server is currently running a campaign for. Copy it from the admin console.

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.

:::caution 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 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 PERMISSION mode worlds that list this exact node.
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 for that world.

If active-world-id is blank, the plugin does nothing on join, and /traverse reports that Traverse is not configured for this server.

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.