GPS

GPS

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

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 / PERMISSIONS

• 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 Set the compass to the given coordinates.
  • /gps clear Restore the compass to its previous direction.

---

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

---

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

---

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

---

• Permission: gps.teleport
  • /gps tp Teleport to one of your own waypoints.

CONFIGURATION

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

USE_SOUND              true/false         Enable sounds on broadcast/arrival.
USE_PERMISSIONS        true/false         Toggle the permission system.
PERMISSION             gps.use            Default permission node.
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

### 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-v.X.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

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."


## CONFIG.YML

options: USE_SOUND: true USE_PERMISSIONS: true ARRIVAL_RADIUS: 3.0 ARRIVAL_SOUND: true ALLOW_CROSS_WORLD: false MAX_COORD: 30000000 CHECK_ARRIVAL_INTERVAL: 2 # seconds (int >= 1) HUD_TICK_INTERVAL: 1 # seconds (int >= 1) SHOW_DISTANCE_HUD: true HUD_COLOR_FAR: 100 HUD_COLOR_MID: 25 HUD_COLOR_NEAR: 5 COLOR_FAR: "&a" # green COLOR_MID: "&e" # yellow COLOR_NEAR: "&6" # gold COLOR_ARRIVED: "&c" # red MILESTONE_FACTOR: 0.5 MILESTONE_COOLDOWN: 30

## WHY

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.

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