Compass Basics¶

Quick Start: Pick your goal.

Who receives a compass, which item it is, names, inventory rules, drops, and distance limits. Every setting below lives under settings.compass.

Given to Roles¶

Which roles receive a compass on match start (and on respawn):

compass:
  obtaining:
    given-to:
      hunters: true
      speedrunners: false

hunters is enabled by default, speedrunners is disabled by default. Hunters always track speedrunners and speedrunners always track hunters.

If you'd like to disable the compass entirely, set both to false.

Compass Item¶

Which item is handed out as the tracking compass, in minecraft:material_name format (the minecraft: namespace may be omitted):

compass:
  obtaining:
    inventory:
      item: compass

The default is compass. Try clock or recovery_compass for a different look; anything else works too.
Unknown names, and anything with placement functionality such as dirt, signs, or redstone, fall back to compass with a console warning. Already handed out compasses keep working after a change; new ones use the configured item.
Note that only compass points its needle at the tracked player. A recovery_compass always points at its holder's last death location, so it works as a match token while direction readout stays on the actionbar.
Handed-out compasses land in the last hotbar slot (slot 9); when it is taken, the first free inventory slot is used instead, or the compass drops at the holder's feet when the inventory is full. Picked-up compasses never stack: every compass stays at amount 1.

Compass Names¶

Each role gets its own compass name and lore from the active lang file: compass.hunter-name and compass.hunter-lore for hunters, compass.speedrunner-name and compass.speedrunner-lore for speedrunners. Picking up a compass restamps it to your role.
Players who are not hunters or speedrunners in a live match cannot pick up a compass at all: the item is removed instead.

Inventory Lock¶

Whether the compass must stay in the player's inventory:

The slot may change, but dropping and containers are blocked.
Rearranging inside the inventory (shift-click, number keys) works; shift-clicking with a container open stays blocked.
Dropping on death is controlled by Drop on Death.

compass:
  obtaining:
    inventory:
      lock-to-inventory: true

Drop on Death¶

Whether the compass drops on death: handy for letting speedrunners pick up a dead hunter's compass and track back.

Only one compass may exist in the inventory at a time. Duplicate ones are removed.

compass:
  obtaining:
    drop-on-death:
      enabled: true

Tracking Distance¶

Each role gets its own tracking limits. The compass uses the block matching the role of the player holding it. Every compass distance is flat (X/Z): height never counts toward tracking, range gates, the actionbar readout, or target ranking.

distance-limits:
  hunter:
    min-distance:
      enabled: true
      distance: 25.0
    max-distance:
      enabled: true
      distance: -1.0

Minimum Distance¶

When the target is at or inside the min distance, the compass stops tracking and shows the nearby message instead.
Only flat distance counts: a target directly above or below you still reads as nearby. This makes camping a viable strategy for speedrunners.
In automatic mode the closest opponent decides: when it is inside the min distance, the compass shows the nearby message instead of jumping to the next closest opponent.

Maximum Distance¶

When the target is beyond the max distance, the compass shows an out-of-range message and either points at a closer last seen location of another player or spins its needle. Set the distance to -1 for unlimited range.
A manually locked target obeys both limits: a locked target that is too close shows the nearby message, and one that is too far shows the out-of-range message.