GhostRun | Competitive Ghost Parkour [BETA]

GhostRun
Race the ghost. Break the record. Become the ghost.

⚠ This plugin is currently in Beta — bugs may occur. Feedback is welcome!

―――――――――――――――――――――――――――――――――――――――――――

What is GhostRun?

GhostRun is a competitive parkour plugin for Paper 1.21.x servers.
Every time a player completes a map, their run is recorded frame by frame.
The next time someone starts that map, an invisible glowing ghost NPC appears
and follows the exact path of the record holder — every jump, every strafe, every millisecond.

Beat the ghost and you become the new ghost everyone races against.

―――――――――――――――――――――――――――――――――――――――――――

Features

Ghost Replay System
A client-side fake NPC (powered by ProtocolLib) replays the best run in real time.
The ghost is invisible with an aqua glow outline — always visible, never in the way.
Recordings only save when a new personal best is set — no wasted storage.

Auto-Race on Start
Use /gr start <map> — if a record exists, the ghost spawns automatically.
A title displays the map name and the current record holder as the run begins.

Global & Monthly Leaderboards
Every map tracks two separate leaderboards simultaneously:
★ Global — All-time best runs, stored permanently.
Monthly — Resets every month for fresh competition. Tracked by YYYY-MM.

Map Selector GUI
A compass in the hotbar opens a chest GUI on right-click.
Each map card shows the record holder's player head, their global best time, and the monthly record.
Click any card to instantly start a race.

Stats Holograms
Place TextDisplay holograms anywhere in the world showing live global and monthly records.
Holograms persist through restarts and update automatically every 20 seconds.

Lobby System
Set a lobby spawn with /gr setlobby — all players teleport there on join.
Full configurable protection per toggle in config.yml:
No hunger · No damage · No fall damage · No block breaking

Admins with the ghostrun.build permission can toggle build mode via /build.

―――――――――――――――――――――――――――――――――――――――――――

Commands

/gr start <map> — Start a run (ghost spawns automatically if a record exists)
/gr race <map> [rank] — Race against a specific leaderboard rank
/gr stop — Cancel your current run
/gr top <map> [global|monthly] — View leaderboards in chat
/gr menu — Open the map selector GUI
/gr list — List all maps
/gr ghost <map> [rank] — Watch a ghost replay without starting a run
/gr hologram add <map> — Place a stats hologram at your position
/gr hologram remove <id> — Remove a hologram
/gr setlobby — Set the lobby spawn point
/build — Toggle build mode (requires ghostrun.build)

Admin map setup: /gr create · /gr setend · /gr checkpoint · /gr delete

―――――――――――――――――――――――――――――――――――――――――――

Permissions

ghostrun.play — Start and race maps (default: true)
ghostrun.admin — Create maps, set lobby, place holograms (default: op)
ghostrun.build — Toggle build mode (default: op)
ghostrun.reload — Reload the config (default: op)

―――――――――――――――――――――――――――――――――――――――――――

Requirements

⚠ ProtocolLib is required for the ghost NPC system!
→ Download ProtocolLib here

Paper 1.21.x is required (1.21 – 1.21.4).
Spigot may work but is untested. Older versions are not supported.

―――――――――――――――――――――――――――――――――――――――――――

Quick Setup

1. Install ProtocolLib on your server
2. Drop GhostRun.jar into your /plugins folder and restart
3. Stand at your map's start position → /gr create <name>
4. Walk to the finish line → /gr setend <name>
5. Optionally add checkpoints → /gr checkpoint <name>
6. Run /gr start <name>, complete the map — the first ghost is now set!

―――――――――――――――――――――――――――――――――――――――――――

Developed by xDanArts · Open to feedback and bug reports · Thank you for trying GhostRun!
​