Firefly

Minecraft 版本： 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11 26.1 26.1.1 26.1.2

平台： folia paper spigot

标签： management social utility

Take back control of the Minecraft locator bar.
Hide your position, recolor your dot, and give players real privacy. No client mod required.

---

What is the locator bar?

Minecraft 1.21.6 introduced the locator bar: the strip across the top of the screen that
shows the direction and distance of every other player as a colored dot (a waypoint). It's handy
for meeting up with friends, and a problem when you'd rather not be tracked.

Firefly hands that visibility back to your players. Anyone can hide their own dot from everyone
else's locator bar, or recolor it. Admins get a see-all override plus moderation tools.

100% server-side. Players join with an ordinary vanilla client. There is nothing for them to
install: no resource pack, no mod. Firefly does everything by rewriting the locator-bar packets on
the server.

✨ Features

• ? Hide your location. Disappear from every other player's locator bar with /firefly hide.
  Your position simply stops being broadcast.
• ? Recolor your dot. Pick any of the 16 named Minecraft colors or a full #RRGGBB hex code
  to stand out, blend in, or coordinate a team.
• ?️ Admin see-all bypass. Staff can reveal hidden players for moderation. Each admin's on/off
  choice is remembered between logins, with a server-wide default you control.
• ? See who's hidden. /firefly showhidden lists every player currently hiding their dot.
• ? Persistent per-player preferences. Hide state, colors, and bypass choices survive relogs
  and restarts. Store them in YAML, embedded H2, or shared MySQL.
• ? Fully translatable. Every message lives in messages.yml; edit the text, color it with
  legacy & codes, and reload live with /firefly reload.
• ⚡ Folia-ready & featherweight. Built for modern high-performance servers and completely idle
  when nobody is hiding or recoloring.
• ? Free & open source. GPL-3.0, with signed, build-provenance-attested release jars.

? Perfect for

• Survival & SMP servers. Give players a genuine sense of safety and privacy on a shared map.
• PvP, anarchy & factions. Stop the locator bar from turning everyone into a tracked target.
  Travel, raid, and ambush without broadcasting your coordinates to the whole server.
• Roleplay & adventure maps. Preserve immersion; not every character should be a glowing dot.
• Minigames. Make hide-and-seek, manhunt, assassin, and stealth modes playable again.

⌨️ Commands

Base command: /firefly (alias /ff).

Command	Permission	What it does
/firefly hide	firefly.use	Hide your dot from other players' locator bars.
/firefly show	firefly.use	Show your dot again.
/firefly toggle	firefly.use	Flip your hidden state.
/firefly color <name\|#RRGGBB>	firefly.use	Recolor your dot as others see it.
/firefly color reset	firefly.use	Reset your dot to the vanilla color.
/firefly bypass <on\|off\|toggle>	firefly.admin	See-all: reveal players who are hiding.
/firefly showhidden	firefly.admin	List players who currently have their dot hidden.
/firefly reload	firefly.admin	Reload config.yml and messages.yml.

Colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold,
gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white, or any
#RRGGBB hex value, e.g. /ff color #FF8800.

? Permissions

Permission	Default	Grants
firefly.use	everyone	Hide / show / toggle and recolor your own dot.
firefly.admin	ops	Bypass hiding, list hidden players, reload config.

? Quick start

1. Install packetevents (2.10.1+ — 2.10.1 or newer) into your plugins/ folder.
   It's a required dependency (Firefly drives the locator bar through it and won't enable without
   it).
2. Download Firefly and drop the .jar into plugins/.
3. Restart your server. That's it: Firefly works out of the box with no configuration required.

⚙️ Configuration

Firefly generates config.yml and messages.yml (plus playerdata.yml on the default backend) in
plugins/Firefly/.

Admin bypass default. Decide whether admins start with see-all enabled when they join. An
admin's explicit /firefly bypass choice is persisted and always wins on future logins; if they log
in with bypass active, Firefly reminds them.

Storage backends. Choose where per-player preferences live:

• yaml (default): a flat file, zero setup.
• h2: embedded, file-based SQL database; no external server to run.
• mysql: external server, HikariCP-pooled, so you can share hide/color preferences across a
  whole network of servers.

All database I/O runs on a dedicated background thread, switching backends is non-destructive, and if
a database can't be reached Firefly automatically falls back to YAML so the plugin keeps working.

Localization. Every player-facing string is editable and translatable in messages.yml. Keys
you don't touch fall back to the built-in English defaults, so the file never breaks across updates.

✅ Compatibility

• Minecraft 1.21.6 – 1.21.11 and 26.1 – 26.1.2. The locator bar exists from 1.21.6 onward,
  including 26.1"
• Paper, Spigot, or Folia. Folia is fully supported.
• Java 21+.
• Requires the packetevents plugin, version 2.10.1 or newer (2.10.1+).
• Vanilla clients. No client-side mod or resource pack.

?️ Performance & safety

• Idle when unused. The packet hot path short-circuits the instant nobody is hiding or
  recoloring, so there's effectively zero overhead in the common case.
• Never blocks the server thread. All storage I/O runs on a dedicated worker thread.
• Folia-safe by design. Firefly only ever touches player UUIDs, in-memory state, and packets,
  never region-locked world or entity state.
• Hardened storage. Parameterized queries only, sanitized H2 file names, and TLS-secured MySQL
  with environment-variable password indirection.
• Trustworthy builds. Every release ships a CycloneDX SBOM and a GitHub build-provenance
  attestation you can verify.

❓ FAQ

Do players need to install a mod or resource pack? No. Firefly is entirely server-side. Players connect with a normal vanilla client and everything just works. Does hiding affect compasses, maps, or anything else? No. Firefly only changes the **locator bar** (the on-screen player-direction dots). Compasses, in-game maps, scoreboards, and tab list are untouched. Can admins still see players who are hiding? Yes. Admins with `firefly.admin` can turn on **bypass** (`/firefly bypass on`) to reveal hidden players, and use `/firefly showhidden` to list exactly who is currently hidden. Are a player's hide and color choices saved? Yes. Preferences persist per player and survive relogs and restarts, stored in YAML, H2, or MySQL. Why does it need packetevents? There is no Bukkit API for per-viewer locator-bar control, so Firefly works by intercepting the server-to-client `WAYPOINT` packet through packetevents. It's a required dependency. Does it work on Folia? Yes. Folia is fully supported and a first-class target, not an afterthought.

---

Source code & issue tracker: github.com/GooberCraft/Firefly
Found a bug or have a feature request? Open an issue on GitHub. Firefly is open source under GPL-3.0.