GPS ⭐ #ultimate #vanilla #lightweight

=========================================================================
GPS - VANILLA-FEEL COMPASS PLUGIN
=========================================================================

A lightweight, vanilla-style GPS plugin for Spigot/Paper servers.
Uses the player's built-in compass to point at coordinates, waypoints,
or another player - like in real life. No lore, no fluff, just navigation.

Supported : Spigot 1.13+ / Paper
Java : 17+
Dependencies : None
Style : Vanilla-friendly
compiled with Spigot API 1.21.11

=========================================================================
FEATURES
=========================================================================

[+] Compass targets: coords, waypoints, player follow
[+] Personal waypoints (add / list / remove / share / go / tp)
[+] /gps tell & /gps share to broadcast positions in chat
[+] /gps chat - grab the last broadcast coords into your compass
[+] Live action-bar with distance, color-coded by proximity
[+] Milestone alerts at 50% of the initial distance
[+] Vanilla compass item placed in the hotbar (slot 8)
[+] Arrival sound + automatic compass restoration
[+] Persistent targets and waypoints (per-player)
[+] Two independent schedulers (HUD and arrival) for performance
[+] Fully configurable: messages, colors, intervals, radius, sound

=========================================================================
COMMANDS
=========================================================================

Permission: gps.use
/gps Show your own position (private).
/gps help Display the in-game help.
/gps tell Broadcast your position to the whole server.
/gps <x> <y> <z> Set the compass to the given coordinates.
/gps clear Restore the compass to its previous direction.

Permission: gps.waypoints
/gps add <name> Save your current position as a waypoint.
/gps list List all your waypoints with index and coords.
/gps remove <idx> Remove one of your waypoints by its 3-digit index.
/gps share <idx> Broadcast a waypoint's coords to everyone.
/gps go <idx> set the compass to a waypoint.

Permission: gps.chat
/gps chat Set your compass to the last broadcast coords.

Permission: gps.follow
/gps follow <player> Live-track another player with your compass.

Permission: gps.teleport
/gps tp <idx> Teleport to one of your own waypoints.

=========================================================================
PERMISSIONS
=========================================================================

gps.use -- Basic /gps command.
gps.waypoints -- Add/list/remove/share waypoints.
gps.follow -- Follow another player with the compass.
gps.teleport -- Teleport to your own waypoints.
gps.chat -- /gps chat to grab last broadcast coords.

=========================================================================
CONFIGURATION
=========================================================================

Everything lives in plugins/GPS/config.yml.
All numeric intervals are validated on startup (must be int >= 1).

--- Options ---

USE_SOUND true/false Enable sounds on broadcast/arrival.
USE_PERMISSIONS true/false Toggle the permission system.
ARRIVAL_RADIUS 3.0 Meters considered "arrived".
ARRIVAL_SOUND true/false Sound on arrival.
ALLOW_CROSS_WORLD false Restrict targets to player's world.
MAX_COORD 30000000 Coordinate sanity limit.

CHECK_ARRIVAL_INTERVAL 2 Seconds (int, >= 1) between
arrival/follow checks.

HUD_TICK_INTERVAL 1 Seconds (int, >= 1) between
action-bar refreshes.

SHOW_DISTANCE_HUD true Show live distance above hotbar.

HUD_COLOR_FAR 100 Threshold for FAR color (meters).
HUD_COLOR_MID 25 Threshold for MID color (meters).
HUD_COLOR_NEAR 5 Threshold for NEAR color (meters).

COLOR_FAR &a Green (> 100m)
COLOR_MID &e Yellow (100m .. 25m]
COLOR_NEAR &6 Gold (25m .. 5m]
COLOR_ARRIVED &c Red (<= ARRIVAL_RADIUS)

MILESTONE_FACTOR 0.5 Fraction of initial distance at
which the milestone alert fires.
MILESTONE_COOLDOWN 30 Seconds between two milestone
messages (anti-spam).

!!! Non-integer values for CHECK_ARRIVAL_INTERVAL or HUD_TICK_INTERVAL
are rejected with a console warning and replaced by the default value.

=========================================================================
HOW IT WORKS
=========================================================================

--- Set a target ---
/gps 120 64 -300
The compass now points to those coordinates. A vanilla compass item is
placed in the player's hotbar (slot 8) with the GPS marker in its name.

--- Live tracking ---
The action-bar above the hotbar shows the live distance and color-codes
itself as the player moves:
> 100m : COLOR_FAR (default green)
25m .. 100m : COLOR_MID (default yellow)
5m .. 25m : COLOR_NEAR (default gold)
<= radius : COLOR_ARRIVED (default red)

--- Waypoints ---
/gps add home -> returns a 3-digit index, e.g. 001
/gps list -> shows all your waypoints with their indices
/gps tp 001 -> teleport to that waypoint (same world)
/gps share 001 -> broadcast the waypoint's coords to everyone
/gps remove 001 -> delete it

--- Chat-grab ---
Anyone broadcasts /gps tell or /gps share <idx>. The coords are
memorized. Other players can then type /gps chat to copy those coords
into their own compass - a one-step "follow the message".

--- Follow ---
/gps follow <player>
Compass live-tracks the player. Auto-clears if they log out or if you
reach them within ARRIVAL_RADIUS.

--- Milestones ---
When the current distance falls under MILESTONE_FACTOR (default 50%) of
the initial distance, a single "you're getting closer" alert is sent.
Subsequent milestones are gated by MILESTONE_COOLDOWN.

--- Arrival ---
When the player is within ARRIVAL_RADIUS of the target, the compass
restores to its previous direction, the GPS compass item is removed,
a sound plays (if ARRIVAL_SOUND is enabled) and an "arrived" message
is shown.

=========================================================================
EXAMPLE WORKFLOW
=========================================================================

Alice: /gps tell
-> "[GPS] Alice ... X:120 Y:64 Z:-300"
-> action-bar memorized in chat registry

Bob: /gps chat
-> "Compass set to last broadcast coords (X:120 Y:64 Z:-300) from Alice"
-> compass points to Alice's location

Bob walks toward the target:
-> action-bar distance: 423m -> green
-> at 211m (50%): milestone "You're getting closer! ~211m to chat:(Alice)"
-> at 25m: yellow / at 5m: gold / at 3m: red
-> "You've arrived at your destination. Compass restored."

=========================================================================
INSTALLATION
=========================================================================

1. Drop GPS-2.1.jar into your server's plugins/ folder.
2. (Re)start the server. config.yml is auto-generated on first run.
3. Edit plugins/GPS/config.yml to your taste.
4. (Re)start the server again to apply interval changes.
5. Done.

=========================================================================
PERMISSIONS NOTICE
=========================================================================

All permissions default to FALSE. Players have NO access until the
server owner explicitly grants them via your permission plugin
(LuckPerms, PermissionsEx, GroupManager, etc.).

Without these grants, /gps returns:
"You do not have permission."

=========================================================================
DEFAULT CONFIG.YML
=========================================================================

options:

messages:
  MESSAGE_POSITION: "X: %d | Y: %d | Z: %d | FACING: &7%s"
  MESSAGE_TARGET_SET: "Compass set to &7X: %d &r| &7Y: %d &r| &7Z: %d&r. Use &7/gps clear &rto restore."
  MESSAGE_INVALID_COORDS: "Invalid coordinates. Use integers within ±%d."
  MESSAGE_WAYPOINT_REMOVED:  "Waypoint &a%i&r removed."
  MESSAGE_WAYPOINT_NOT_FOUND: "Waypoint &7%i&r not found."
  MESSAGE_TP_OK: "Teleported to waypoint &a%i &7(%name%)&r."
  MESSAGE_WAYPOINT_ADDED: "Waypoint &a%i&r: &7%name% &radded at X: %x Y: %y Z: %z"
  GPS_CHAT_PREFIX: "&6&k000&r[&7GPS&r] "
  MESSAGE_BROADCAST_USAGE: "\n&7   /gps tell&r to broadcast position."
  MESSAGE_PERMISSION: "You do not have permission."
  MESSAGE_USAGE: "Usage: &7/gps [tell|<x> <y> <z>|clear|help|add <name>|list|remove <idx>|follow <player>|share <idx>|chat|tp <idx>]"
  MESSAGE_HELP: "&7--- GPS Help ---\n&r/gps &7- show your position\n&r/gps tell &7- broadcast position\n&r/gps <x> <y> <z> &7- compass to coords\n&r/gps clear &7- restore original compass\n&r/gps add <name> &7- save current position as waypoint\n&r/gps list &7- list your waypoints\n&r/gps remove <idx> &7- remove a waypoint\n&r/gps go <idx> &7- compass to a saved waypoint\n&r/gps share <idx> &7- broadcast a waypoint coords\n&r/gps chat &7- compass to last broadcast coords\n&r/gps follow <player> &7- compass follows a player"
  MESSAGE_TARGET_CLEARED: "Compass restored to its previous direction."
  MESSAGE_NO_TARGET: "No GPS target currently active."
  MESSAGE_ARRIVED: "&aYou've arrived at your destination. Compass restored."
  MESSAGE_PLAYER_ONLY: "This command can only be executed by players."
  MESSAGE_WAYPOINT_LIST_EMPTY: "You have no waypoints."
  MESSAGE_WAYPOINT_INVALID_NAME: "Invalid name. Use letters, digits, spaces, dashes or underscores (max 32)."
  MESSAGE_FOLLOW_SET: "Compass now follows &a%name%&r. ..."
  MESSAGE_FOLLOW_TARGET_OFFLINE: "Target went offline. GPS cleared."
  MESSAGE_FOLLOW_REACHED: "&aYou have reached &7%name%&a."
  MESSAGE_FOLLOW_NO_PLAYER: "Player not found."
  MESSAGE_COMPASS_GIVEN: "&7GPS compass placed in your hotbar (slot &e%slot%&7)."
  MESSAGE_RELOADED: "&aGPS configuration reloaded."
  MESSAGE_DISTANCE_HUD: "&7%mode% &a%name% &r→ &7%dist%m &8| X:&7%mx% Y:&7%my% Z:&7%mz%"
  MESSAGE_CHAT_NONE: "No broadcast coords available. Ask someone to &7/gps tell&r or share a waypoint."
  MESSAGE_TP_DENY_WORLD: "Cannot teleport to a waypoint in another world."
  MESSAGE_MILESTONE: "&eYou're getting closer! &7~&a%dist%m &7remaining to &a%name%&7."

options:
  USE_SOUND: true
  USE_PERMISSIONS: true
  ARRIVAL_RADIUS: 3.0
  ARRIVAL_SOUND: true
  ALLOW_CROSS_WORLD: false
  MAX_COORD: 30000000

  # Tick intervals (seconds, int >=1)
  # How often we check for arrival / update follow target.
  CHECK_ARRIVAL_INTERVAL: 2
  # How often we refresh the action-bar (perf vs responsiveness).
  HUD_TICK_INTERVAL: 1

  # Live HUD
  SHOW_DISTANCE_HUD: true

  # Color thresholds (meters). The action-bar color depends on distance to target.
  # If distance > HUD_COLOR_FAR  : COLOR_FAR
  # If distance > HUD_COLOR_MID  : COLOR_MID
  # If distance > HUD_COLOR_NEAR : COLOR_NEAR
  # Else                        : COLOR_ARRIVED
  HUD_COLOR_FAR:     100
  HUD_COLOR_MID:     25
  HUD_COLOR_NEAR:    5
  # Vanilla color codes. Examples: &a green, &e yellow, &6 gold, &c red, &b aqua.
  COLOR_FAR:         "&a"
  COLOR_MID:         "&e"
  COLOR_NEAR:        "&6"
  COLOR_ARRIVED:     "&c"

  # Milestone
  MILESTONE_FACTOR: 0.5
  MILESTONE_COOLDOWN: 30

=========================================================================
WHY THIS PLUGIN
=========================================================================

Most "GPS" plugins out there either rewrite the compass, abuse NMS,
or require client-side mods. This one stays 100% vanilla: it only uses
the player's built-in compass, the action-bar, and a regular compass
item in the hotbar. No protocol hacks, no client install, no surprises.

Inspired by real-life navigation: set coords, follow the needle, arrive.

Perfect for survival servers, explorers, treasure hunts, roleplay
scenarios and races across your world.

License : Free for private use. Modification of the authorship
in the source is not allowed.

=========================================================================
END
=========================================================================

---

---

---