# Vexal Ping Compass - Free

A lightweight Spigot/Paper plugin that gives players special compasses which point to the online player with the highest or the lowest ping. Useful for staff, events, or debugging network issues on your server.

### Features

* Highest Ping Compass: points to the online player with the highest latency.
* Lowest Ping Compass: points to the online player with the lowest latency.
* Simple admin command to give items to players.
* Per‑item cooldowns (configurable; set to 0 to disable).
* Customizable item names, lore, glow, and material.
* Works across modern Spigot/Paper versions. Uses Player#getPing when available and falls back to reflection for older versions.

### Requirements

* Java 17+ (use the same Java version as your server runtime)
* Spigot or Paper server (Minecraft 1.16+ recommended)

### Installation

1. Download the plugin JAR (vexalpingcompass-1.0-STABLE\*.jar).
2. Place it into your server's `plugins/` directory.
3. Start or restart your server.
4. A default `plugins/VexalPingCompass/config.yml` will be created.

### Commands

* `/vpc` — Shows a brief help message.
* `/vpc reload` — Reloads the plugin configuration from disk.
* `/vpc give <player> <type>` — Gives one of the special compasses to the specified player.
  * `<type>`: `highest` or `lowest`

### Permissions

* `vexalpingcompass.admin`
  * Required to run `/vpc reload` and `/vpc give`.

### Usage

* Right‑click the compass to set your compass target to the selected player:
  * Highest Ping Compass: tracks the player with the highest ping.
  * Lowest Ping Compass: tracks the player with the lowest ping.
* If a cooldown is configured, you must wait until the cooldown expires before using the compass again. The plugin will inform you how many seconds remain.

### Configuration

Default configuration (plugins/VexalPingCompass/config.yml):

```
plugin:
  prefix: "&7[VexalPingCompass]"

compass:
  highest:
    item: "COMPASS"
    displayname: "&aHighest Ping Compass"
    lore:
      - "&7Points to the player with the highest ping."
    glowing: true
    cooldown: 2 # in seconds
  lowest:
    item: "COMPASS"
    displayname: "&bLowest Ping Compass"
    lore:
      - "&7Points to the player with the lowest ping."
    glowing: true
    cooldown: 2 # in seconds

messages:
  reload: "&aConfiguration reloaded!"
  no_permission: "&cYou do not have permission to use this command!"
  invalid_command: "&cInvalid command usage!"
```

Notes:

* Colors use `&` codes and are translated automatically.
* `item`: any valid Bukkit `Material` name (e.g., `COMPASS`, `RECOVERY_COMPASS`, etc.). If invalid, it falls back to `COMPASS`.
* `glowing`: adds a hidden enchant to make the item glow.
* `cooldown`: set to `0` to disable cooldown for that compass.

### Compatibility notes

* Ping retrieval tries `Player#getPing()` first (available on modern API builds). If unavailable, it falls back to CraftBukkit internals via reflection for broad compatibility.
* Should work on Spigot or Paper. Other forks are untested but likely fine.

### Troubleshooting / FAQ

* The compass doesn’t point anywhere
  * Ensure at least one other player is online to track.
  * Make sure you’re using the correct compass (highest vs lowest) for your use‑case.
* "Please wait X seconds" message
  * You’re on cooldown. Adjust `compass.<type>.cooldown` or set it to `0` to disable.
* "You do not have permission" when running commands
  * Grant `vexalpingcompass.admin` to the appropriate staff group.
* Unsupported Material name in config
  * The plugin will fall back to `COMPASS`. Use a valid `Material` name for your server version.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vexalstudios.com/minecraft-plugins/vexal-ping-compass-free.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.