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.

Running a campaign end to end​

  1. Create the world. Enter the name, seed, and Minecraft version, then set the campaign window and time zone.
  2. Set qualification. Choose PERMISSION or GROUP mode and list the nodes or groups that qualify.
  3. Define the search area. Set origin, minimum and maximum search distance, the border if you enforce one, and the spawn keep-out.
  4. Tune thresholds. The defaults are a reasonable start. See Configuration.
  5. Draw exclusion zones over anything supporters should not be given.
  6. Set up biome categories so supporters can pick "Forests" rather than hunting through every variant.
  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. Point the plugin at the world by copying its id into the plugin's active-world-id, then run /traverse reload.
  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.

:::caution 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.

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, and manual grants all land here.

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.