Skip to main content

Admin Guide

The admin console lives at /admin on your Traverse deployment. Sign in with the admin user created by the seed script, then change that password.

Traverse runs one world per installation. It is created for you, disabled, the first time the server starts, so you never create or pick a world - you configure the one you have and then enable it. The dashboard shows a Finish setting up Traverse checklist that tracks exactly the steps below until each is done.

Running a campaign end to end​

  1. Set the world's identity. In World Settings → Configuration, set the name, seed, and Minecraft version. Use Preview this seed to check the terrain before saving. The seed and version lock once the first player searches.
  2. Set the campaign window. In World Settings → Campaign, set the start and end dates, the time zone, and how many hours before the close supporters are reminded.
  3. Set qualification. Choose PERMISSION or GROUP mode and list the nodes or groups that qualify.
  4. Define the search area. Set minimum and maximum search distance, the border if you enforce one, and the spawn keep-out.
  5. Tune thresholds. The defaults are a reasonable start. See Configuration.
  6. Draw exclusion zones over anything supporters should not be given.
  7. Build the biome index and wait for it to report ready.
  8. Write the supporter copy: hero phrase, welcome description, and the in-game dialog title and message.
  9. Connect the plugin. Point it at this deployment's base-url and api-key and run /traverse reload. There is no world id to copy any more - the plugin uses whichever world this installation has. The checklist ticks Minecraft plugin connected once the plugin has called in on a matching version.
  10. Test as an operator. Operators bypass qualification, so you can walk the whole flow yourself before opening it up.
  11. Enable the world and let the window open.
Test the whole flow before the window opens

Join, take the dialog, run a search, and reveal on a throwaway entitlement. A world whose thresholds are too tight, or whose version the engine cannot generate, only shows itself when a real supporter gets no candidates.

The seed lock​

Once a world has any candidate previews or claims, its seed can no longer be changed. Every claim was matched against that seed, so changing it would silently invalidate every location already handed out. The console reports the world as seed locked.

The biome index​

Each world has a biome index: a cached render of its terrain used for the world map and lookups. It reports BUILDING, READY, or STALE. Rebuild it from the console after changing the seed or the version. Rebuilding always clears and re-renders, even when the existing index is already ready.

Exporting and importing settings​

World Settings can move a configuration between installs. Export settings downloads a JSON file holding every editable world setting plus all exclusion zones. Import settings applies such a file to this world:

  • If the file includes exclusion zones, they replace the current ones in a single transaction; if it omits them, the existing zones are left alone.
  • A different seed or Minecraft version is refused once searching has started, for the same reason the seed locks. Re-importing a file exported from this same world after searching is fine, because the seed in it already matches.
  • Every import is recorded in the audit log.

This is the quickest way to clone a tuned setup to a staging instance, or to keep a backup of a configuration you are about to change.

Exclusion zones​

Zones keep areas out of the search entirely. Each is:

  • a circle (centre and radius) or a rectangle (min and max on both axes),
  • with a buffer of extra clearance around it,
  • individually enabled or disabled, so you can retire one without deleting it.

A candidate is rejected if its plot, plus that buffer, touches an enabled zone. Use them for spawn towns, roads, event builds, and anywhere you are keeping in reserve.

Disabling a zone does not release claims already granted; it only affects future searches.

Claims​

The claims view lists every claim with its supporter, coordinates, radius, matched biomes, score, and status. Statuses are ACTIVE, SUPERSEDED, RELEASED, and REVOKED.

  • Release a claim when a supporter gives up their location. It stops reserving the area, and the release is timestamped.
  • Supersede a claim when it is replaced by a new one.
  • Toggle exclusion to control whether a claim continues to block other supporters' candidates. This is the switch to reach for when you want a location on record without it carving a hole in the search.

Every claim also appears on the world map alongside exclusion zones and the biome index, which is the quickest way to see how much of the world is spoken for.

Granting access by hand​

Sometimes the plugin cannot reach a supporter: the world id is wrong, LuckPerms is misconfigured, or the player has never joined. The console can issue an access code directly from a Minecraft username. Traverse resolves the real Mojang UUID first, so the player row is the same one a genuine join would produce, and the grant is recorded in the audit log.

Support requests​

Requests filed from the supporter app arrive here, typed as lost redemption session, reactivate access, wrong location, technical problem, or other. Each carries a self-reported username, because the most common reason for filing one is that the supporter has no working session to identify them. Work them through their status and, if you have configured a Discord webhook in the instance settings, they are relayed there as they arrive.

Audit log​

Every admin change writes an entry recording the admin user, the action, the entity, the before and after state, the source IP, and the time. Releases, supersedes, world edits, settings imports, exclusion-zone changes, and manual grants all land here. Browse it from Admin → System → Audit Log, newest first, with a before/after view of the fields that changed.

Health check and monitoring​

An unauthenticated GET /api/health is there for uptime monitors. It returns 200 whenever the server and database are reachable, and 503 only when the database probe fails. The body reports the world's state, the biome index state, and when the plugin last called in, so a disabled world, a stale index, or a quiet plugin shows up as information rather than as an outage. It deliberately exposes no seed, coordinates, or player data. See the Plugin API Reference for the full response.

Security notes​

  • Admin sessions use signed, HTTP-only, same-site cookies, and every mutating admin endpoint requires a CSRF token.
  • Admin login is rate limited to 10 attempts per 15 minutes.
  • Access codes and plugin tokens are hashed at rest and are single use, guarded atomically so two concurrent redemptions cannot both win.
  • Access token URLs are redacted from request logs.