SpyHunt-Compass

A lightweight player-tracking compass plugin for Minecraft Paper and Spigot servers (1.21+). Originally built as the tracking system for the SpyHunts manhunt gamemode, this plugin works standalone for survival, SMPs, and minigames.

---

Features

• Live Tracking: Needle updates every second to point toward the target player without placing physical lodestone blocks.
• Cross-Dimension Portals: When a target enters the Nether or End, the compass points to the portal where they left your dimension.
• Multi-Target Cycling: Store multiple runners on a single compass and right-click to cycle between them.
• Dynamic Lore: Item lore updates in real time to show the currently tracked player and total target count.
• Offline Recovery: Retains the target's last seen position if they disconnect. Offline players can still be removed with /tracker remove.
• Manhunt Privacy: Player names are hidden from tab completion on /tracker add and /tracker remove to avoid meta-gaming.
• SMP Admin Controls: Built-in config toggles allow server owners to restrict /track strictly to staff/admins.
• Persistent Data: Tracking state is saved on the compass item (PersistentDataContainer), so compasses can be stored in chests or shared with teammates.

---

Controls & Commands

Input / Command	Description	Permission
Right-Click	Cycle to the next target on the compass	—
Left-Click	Force refresh the compass target	—
/track <player>	Set compass to track only this player (clears other targets)	spyhuntcompass.track (default: true)
/tracker	Give an empty tracker compass	spyhuntcompass.tracker (default: true)
/tracker add <player>	Add a player to your compass target list	spyhuntcompass.tracker (default: true)
/tracker remove <player>	Remove a player (online or offline) from your list	spyhuntcompass.tracker (default: true)
/tracker help	Show in-game command list	spyhuntcompass.tracker (default: true)
Admin Override	Bypasses all admin-only restrictions	spyhuntcompass.admin (default: op)

---

Configuration

Settings can be edited in plugins/SpyHunt-Compass/config.yml:

# Set to true on SMP servers so only admins/staff can give out compasses
admin-only-track: false

# Restrict all tracker commands to admins/operators
admin-only: false

# Recalculation interval in ticks (20 ticks = 1 second)
refresh-interval-ticks: 20

# Minimum block movement required before updating compass metadata
movement-update-threshold: 4.0

---

Installation

1. Download the latest spyhunt-compass-1.0.1.jar from Releases.
2. Drop it into your server's plugins/ folder.
3. Requires Java 21+ and Paper / Purpur / Spigot 1.21+.
4. Restart the server.

For advanced details, mechanics, and permissions breakdown, see DOCUMENTATION.md.