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

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.

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