重新夺回对 Minecraft 定位栏的控制权。
隐藏你的位置、重绘你的圆点,为玩家提供真正的隐私。无需安装客户端模组。
什么是定位栏?
Minecraft 1.21.6 引入了定位栏:屏幕顶部的一条横条,以彩色圆点(路标)的形式显示其他所有玩家的方向和距离。它非常适合与朋友聚会,但当你不想被追踪时,它就成了一个问题。
Firefly 将这种可见性交还给你的玩家。 任何人都可以让自己对其他玩家的定位栏不可见,或者重绘自己的圆点。管理员则拥有“全视”覆盖权限以及管理工具。
100% 服务端插件。 玩家使用普通的原版客户端即可加入。他们无需安装任何东西:不需要资源包,也不需要模组。Firefly 完全通过在服务端重写定位栏数据包来实现所有功能。
✨ 特性
- ? 隐藏你的位置。 使用
/firefly hide 从其他所有玩家的定位栏中消失。
你的位置将不再被广播。
- ? 重绘你的圆点。 选择 16 种 Minecraft 命名颜色之一 或 一个完整的
#RRGGBB 十六进制代码
来脱颖而出、融入环境或协调团队。
- ?️ 管理员全视绕过。 工作人员可以揭示隐藏的玩家以进行管理。每个管理员的开/关选择会在登录之间保存,并设有你控制的服务器全局默认值。
- ? 查看谁在隐藏。
/firefly showhidden 列出当前隐藏其圆点的每位玩家。
- ? 持久的玩家偏好设置。 隐藏状态、颜色和绕过选择在重新连接和重启后依然存在。可存储于 YAML、嵌入式 H2 或共享的 MySQL 中。
- ? 完全支持翻译。 每条消息都位于
messages.yml 中;编辑文本,使用传统的 & 代码进行着色,并通过 /firefly reload 实时重载。
- ⚡ Folia 兼容 & 轻量级。 专为现代高性能服务器构建,当没有人隐藏或重绘圆点时完全空闲。
- ? 免费且开源。 GPL-3.0 许可,附带签名且经过构建溯源验证的发布 jar 包。
? 适用场景
- 生存 & SMP 服务器。 在共享地图上给予玩家真正的安全感和隐私感。
- PvP、无政府 & 阵营服务器。 防止定位栏让每个人都成为被追踪的目标。
旅行、突袭和伏击时,无需向整个服务器广播你的坐标。
- 角色扮演 & 冒险地图。 保持沉浸感;并非每个角色都应该是一个发光的圆点。
- 小游戏。 让捉迷藏、猎杀、刺客和潜行模式再次变得可玩。
⌨️ 命令
基础命令:/firefly(别名 /ff)。
| 命令 |
权限 |
功能 |
/firefly hide |
firefly.use |
对其他玩家的定位栏隐藏你的圆点。 |
/firefly show |
firefly.use |
再次显示你的圆点。 |
/firefly toggle |
firefly.use |
切换你的隐藏状态。 |
/firefly color <name|#RRGGBB> |
firefly.use |
重绘你的圆点(他人所见颜色)。 |
/firefly color reset |
firefly.use |
将你的圆点重置为原版颜色。 |
/firefly bypass <on|off|toggle> |
firefly.admin |
全视:揭示正在隐藏的玩家。 |
/firefly showhidden |
firefly.admin |
列出当前隐藏其圆点的玩家。 |
/firefly reload |
firefly.admin |
重载 config.yml 和 messages.yml。 |
颜色: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold,
gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white,或任何
#RRGGBB 十六进制值,例如 /ff color #FF8800。
? 权限
| 权限 |
默认分配 |
授予 |
firefly.use |
所有人 |
隐藏 / 显示 / 切换并重绘自己的圆点。 |
firefly.admin |
ops |
绕过隐藏、列出隐藏的玩家、重载配置。 |
? 快速开始
- 安装 packetevents (2.10.1+; 26.1 - 26.2 版本需 2.13.0+; 26.3 版本需 2.14.0+) 到你的
plugins/ 文件夹中。
这是一个必需的依赖项(Firefly 通过它驱动定位栏,没有它将无法启用)。
- 下载 Firefly 并将
.jar 文件放入 plugins/。
- 重启服务器。搞定:Firefly 开箱即用,无需任何配置。
⚙️ 配置
Firefly 会在 plugins/Firefly/ 目录下生成 config.yml 和 messages.yml(在默认后端下还会生成 playerdata.yml)。
管理员绕过默认值。 决定管理员加入时是否默认开启全视。管理员显式的 /firefly bypass 选择会被持久化,并在未来的登录中始终优先;如果他们带着激活的绕过权限登录,Firefly 会提醒他们。
存储后端。 选择玩家偏好设置的存储位置:
yaml (默认):平面文件,零设置。
h2:嵌入式、基于文件的 SQL 数据库;无需运行外部服务器。
mysql:外部服务器,使用 HikariCP 连接池,因此你可以在整个服务器网络中共享隐藏/颜色偏好。
所有数据库 I/O 都在专用的后台线程上运行,切换后端不会破坏数据,如果无法访问数据库,Firefly 会自动回退到 YAML,以确保插件继续工作。
本地化。 所有面向玩家的文本均可在 messages.yml 中编辑和翻译。您未修改的键将回退到内置的英文默认值,因此该文件在更新后绝不会出错。
✅ 兼容性
- Minecraft 1.21.6 - 1.21.11 与 26.1 - 26.3。定位栏自 1.21.6 起存在,Firefly 已验证兼容至 26.3。
- Paper、Spigot 或 Folia。Folia 完全支持。
- Java 21+。
- 需要安装 packetevents 插件:
- 在 1.21.6 - 1.21.11 上:版本 2.10.1 或更高。
- 在 26.1 - 26.2 上:版本 2.13.0 或更高(首个知晓 26.2 协议的版本)。
- 在 26.3 上:版本 2.14.0 或更高(首个知晓 26.3 协议的版本)。
- 原版客户端。无需客户端模组或资源包。
?️ 性能与安全
- 闲置时无开销。当没有任何玩家处于隐藏或变色状态时,数据包热路径会立即短路,因此在常规情况下实际上零开销。
- 绝不阻塞服务器线程。所有存储 I/O 均在专用的工作线程上运行。
- 设计即兼容 Folia。Firefly 仅操作玩家 UUID、内存状态和数据包,从不触及区域锁定的世界或实体状态。
- 加固存储。仅使用参数化查询,H2 文件名经过清理,MySQL 通过环境变量密码间接方式实现 TLS 加密连接。
- 可信构建。每个发行版均附带 CycloneDX SBOM 和 GitHub 构建来源证明,可供验证。
❓ 常见问题
玩家需要安装模组或资源包吗?
不需要。Firefly 完全是服务端插件。玩家使用普通原版客户端连接即可正常工作。
隐藏功能会影响指南针、地图或其他内容吗?
不会。Firefly 仅更改定位栏(屏幕上的玩家方向点)。指南针、游戏内地图、记分板和标签列表均不受影响。
管理员是否仍能看到隐藏的玩家?
是的。拥有 firefly.admin 权限的管理员可以开启绕过模式(/firefly bypass on)以显示隐藏玩家,并使用 /firefly showhidden 列出当前所有隐藏的确切人员。
玩家的隐藏和颜色选择会被保存吗?
会。偏好设置按玩家独立保存,并在重新登录和服务端重启后保留,数据存储于 YAML、H2 或 MySQL 中。
为什么需要 packetevents?
Bukkit API 没有提供针对每位查看者的定位栏控制接口,因此 Firefly 通过 packetevents 拦截服务器到客户端的 WAYPOINT 数据包来实现功能。这是必需的依赖项。
它在 Folia 上能工作吗?
可以。Folia 完全受支持且是首要目标平台,而非事后补充。
源代码与问题追踪:
github.com/GooberCraft/Firefly
发现错误或有任何功能请求?请在 GitHub 上提交 Issue。Firefly 基于 GPL-3.0 开源。
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
- Install packetevents (2.10.1+; 2.13.0+ on 26.1 - 26.2; 2.14.0+ on 26.3) into your
plugins/ folder.
It's a required dependency (Firefly drives the locator bar through it and won't enable without
it).
- Download Firefly and drop the
.jar into plugins/.
- 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.3. The locator bar exists from 1.21.6 onward,
and Firefly is verified up to 26.3.
- Paper, Spigot, or Folia. Folia is fully supported.
- Java 21+.
- Requires the packetevents plugin:
- On 1.21.6 - 1.21.11: version 2.10.1 or newer.
- On 26.1 - 26.2: version 2.13.0 or newer (the first release that knows the 26.2 protocol).
- On 26.3: version 2.14.0 or newer (the first release that knows the 26.3 protocol).
- 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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧