SpyHunt-Compass

# SpyHunt-Compass

[!(https://img.shields.io/badge/Minecraft-1. 21%2B-2ea44f.svg)](https://papermc.io) [!(https://img.shields.io/badge/Platform-Paper%20%7C%20Spigot-blue.svg)](https://papermc.io) [!(https://img.shields.io/badge/Java-21%2B-orange.svg)](https://adoptium.net) [!(https://img.shields.io/badge/Release-1. 0. 1-brightgreen.svg)](https://github.com/spygamingog/SpyHunt-Compass/releases) [!(https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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 ` | 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 ` | Add a player to your compass target list | `spyhuntcompass.tracker` (default: true) | | `/tracker remove ` | 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`:

```yaml # 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 (https://github.com/spygamingog/SpyHunt-Compass/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).