Firefly

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 ` | `firefly.use` | Recolor your dot as others see it. | | `/firefly color reset` | `firefly.use` | Reset your dot to the vanilla color. | | `/firefly bypass ` | `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](https://modrinth.com/plugin/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.

MDWGames