GlowAPI
让玩家和实体在十六种聊天颜色中发光,并且是针对每个接收者单独处理。
原版的光照效果只是实体的一个标志位,所以所有能看到它的玩家看到的都一样。这在你希望它表达特定含义时就不够用了。例如,团队插件希望己方队伍显示为绿色轮廓、敌方为红色轮廓,同时作用于同一个实体;管理员工具希望只有其他管理员能看到隐身玩家的轮廓;迷你游戏希望仅对旁观者高亮显示最后存活的玩家,而对其他人不可见。
这些需求都无法通过单一的服务器端标志位实现。GlowAPI 改为在客户端侧进行处理:发光效果和携带颜色的记分板队伍信息会分别发送给每位观察者。因此,玩家 A 可以看到玩家 B 发出红光,而玩家 C 看到同一玩家 B 发出蓝光,玩家 B 自己则看不到任何发光效果。
这是 InventivetalentDev's GlowAPI 的维护延续版本,原项目已多年未更新。包名、类名和方法签名均保持一致——基于旧版开发的插件无需任何代码修改即可继续正常工作。
变更内容
旧版本需要同时安装 PacketListenerAPI,而该依赖库早已停止维护。当它不再更新时,所有基于 GlowAPI 构建的内容也随之失效。
现在数据包层已迁移至 PacketEvents,并打包在 jar 文件内部且进行了重定位,因此无需额外安装其他内容,也不会与其他插件的副本发生冲突。这也将支持的 Minecraft 版本范围从大约 1.19 扩展到了当前最新版本。
|
旧版 GlowAPI |
GlowAPI 2.0 |
| 数据包层 |
PacketListenerAPI(已废弃) |
PacketEvents,内置于 jar 包中 |
| 需安装的其他插件 |
一个 |
无 |
| Minecraft 版本 |
最高至 ~1.19 |
1.9 至 26.3 |
| 公共 API |
- |
保持不变 |
不支持 Minecraft 1.8.x,也不会提供支持。由于发光效果在 1.9 之前并不存在,因此没有可发送的数据。
要求
- Bukkit、Spigot、Paper 或其分支,运行在 Minecraft 1.9 或更高版本上
- 无需其他依赖。PacketEvents 已包含在 jar 包内
如果您已经作为独立插件运行着 PacketEvents,GlowAPI 会检测到并使用该实例,而不是启动第二个实例。
将 jar 文件放入 plugins/ 目录并重启服务器即可。无需进行任何设置步骤——该插件处于空闲状态,直到有其他插件向其请求功能,或者您输入 /glow 命令为止。
通过权限实现自动发光,无需编写代码
并非每个服务器都愿意为此专门编写插件。在 config.yml 中设置 auto-glow.enabled: true,并为某个用户组授予 glowapi.auto.<color> 权限,例如为 LuckPerms 中的 VIP 等级授予 glowapi.auto.gold。拥有该权限的玩家对其他所有玩家都会显示为该颜色的发光效果。
如果一名玩家拥有多个此类权限,则按以下顺序优先应用第一个:black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, purple, yellow, white。修改权限后,执行 /glowapi reload 即可对已在线的玩家生效。只有以此方式发放的发光效果会被收回,而 /glow 命令及其他插件设置的发光效果不受影响。
在你的插件中使用
在 plugin.yml 中将 GlowAPI 添加为软依赖:
softdepend: [GlowAPI]
然后调用它。所有方法均为静态方法,因此无需获取实例或查找服务:
// 仅对一名观看者显示绿色发光
GlowAPI.setGlowing(target, GlowAPI.Color.GREEN, viewer);
// 对所有在线玩家显示红色发光
GlowAPI.setGlowing(target, GlowAPI.Color.RED, Bukkit.getOnlinePlayers());
// 停止对该观看者的发光效果
GlowAPI.setGlowing(target, (GlowAPI.Color) null, viewer);
需要注意的一点是加入服务器时的时机问题。玩家在触发 PlayerJoinEvent 的那个刻(tick)尚未准备好接收实体数据包,因此请稍作延迟:
@EventHandler
public void onJoin(PlayerJoinEvent event) {
Bukkit.getScheduler().runTaskLater(this, () ->
GlowAPI.setGlowing(event.getPlayer(), GlowAPI.Color.DARK_AQUA, Bukkit.getOnlinePlayers()), 10L);
}
将 API 集成到你的构建系统中
该构件位于 Codeberg 的软件包注册表中。
Maven
<repositories>
<repository>
<id>codeberg-glowapi</id>
<url>https://codeberg.org/api/packages/LucasTHCR/maven</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.inventivetalent</groupId>
<artifactId>glowapi</artifactId>
<version>2.2.0-RELEASE</version>
<scope>provided</scope>
</dependency>
</dependencies>
Gradle (Kotlin DSL)
repositories {
maven("https://codeberg.org/api/packages/LucasTHCR/maven")
}
dependencies {
compileOnly("org.inventivetalent:glowapi:2.2.0-RELEASE")
}
Gradle (Groovy DSL)
repositories {
maven { url 'https://codeberg.org/api/packages/LucasTHCR/maven' }
}
dependencies {
compileOnly 'org.inventivetalent:glowapi:2.2.0-RELEASE'
}
provided 和 compileOnly 这一细节不可忽略。GlowAPI 采用 GPLv3 协议,因此将其阴影打包(shading)进你自己的 jar 文件会将你的整个插件也置于 GPLv3 协议之下。仅针对其进行编译并在运行时由服务器提供该 jar 包则不会如此——你的插件将保留你所选择的任何许可证。这也意味着你的用户只需安装一个 GlowAPI,而不是每个插件各装一份。
服务器管理员从下载页面安装该 jar 包;无需在构建过程中额外添加任何内容。
完整接口
| 方法 |
功能 |
setGlowing(Entity, Color, Player) |
为一名观看者设置单个实体的发光颜色 |
setGlowing(Entity, Color, Collection<Player>) |
同上,但适用于多名观看者 |
setGlowing(Collection<Entity>, Color, Player) |
多个实体,一名观看者 |
setGlowing(Collection<Entity>, Color, Collection<Player>) |
多个实体,多名观看者 |
setGlowing(Entity, boolean, Player) |
以默认的白色开启或关闭发光效果 |
setGlowing(Entity, Color, String tagVisibility, String push, Player) |
如上所述,但在本次调用中覆盖队伍的名称标签可见性和碰撞规则 |
isGlowing(Entity, Player) |
该观看者当前是否看到该实体发光 |
isGlowing(Entity, Collection<Player>, boolean checkAll) |
checkAll 决定是检查所有观看者还是任意一名观看者 |
getGlowColor(Entity, Player) |
该观看者看到的 Color,若无则为 null |
initTeam(Player) |
为观看者创建发光队伍。加入游戏时会自动运行;仅当你构建自定义登录流程时才需要手动调用 |
Color 包含十六种聊天颜色:BLACK、DARK_BLUE、DARK_GREEN、DARK_AQUA、DARK_RED、DARK_PURPLE、GOLD、GRAY、DARK_GRAY、BLUE、GREEN、AQUA、RED、PURPLE、YELLOW、WHITE,以及 NONE。
NONE 表示在不加入颜色队伍的情况下发光,客户端会将其显示为白色。传入 null 而非 Color 则是关闭发光效果的方式。
任何拥有 UUID 的对象均可使用,不仅限于玩家:包括生物、盔甲架、掉落物品和物品框架。
命令
这些命令的存在是为了让你能够在不编写代码的情况下测试插件是否正常工作。真正的接口是 API。
| 命令 |
权限 |
功能 |
/glow <color|off> [player] |
glowapi.command.glow |
使一名玩家对所有在线人员发光。若未指定名称,则作用于你自己 |
/glowapi reload |
glowapi.command.admin |
重新读取 config.yml 并重建队伍 |
/glowapi version |
glowapi.command.admin |
打印当前运行的版本 |
/glowapi debug |
glowapi.command.admin |
显示检测到的客户端版本以及正在发送的颜色 ID |
这两个权限默认均授予 OP(操作员)。Tab 补全支持颜色名称和在线玩家列表。
配置
共有四个值,除非你有特殊理由,否则默认值即是你所需要的。
# always | never | hideForOtherTeams | hideForOwnTeam
nameTagVisibility: always
# always | never | pushOtherTeams | pushOwnTeam
collision: always
# auto | always | never
modern-team-colors: auto
auto-glow:
enabled: false
bstats: true
modern-team-colors 的存在是因为 Minecraft 将颜色编码为位字段——蓝色、绿色、红色、高亮——而 26.1 及更新版本的客户端会以相反的方式读取红色和蓝色位。若不处理,aqua 在这些客户端上会显示为 yellow,dark_blue 会显示为 dark_red,而绿色、灰色、黑色和白色看起来正常,因为它们的红色和蓝色位相同。auto 模式会为 26.1 及更高版本的客户端交换这两个位,并保持旧版客户端不变,从而确保无论玩家使用何种客户端连接都能正确显示。它跟随每位观看者的客户端版本,而非服务器版本,因此即使服务器位于协议翻译器后方且版本混杂,也能正确处理。你可以通过 /glowapi debug 查看正在发送的内容。
bstats: true 会将匿名服务器统计数据发送至 bStats。将其设置为 false 则不会发送任何数据。
颜色通过记分板队伍传递,而队伍同时也决定其成员的名称标签是否可见以及是否会相互推挤。这两个设置是发光玩家继承颜色时所附带属性,因此它们在此处可配置而非固定不变。
设置 collision: never 会使发光的玩家彼此穿过,这通常是一种令人意外的结果而非预期功能。若保持两者均为 always,则发光效果纯粹是装饰性的。
若某个插件需要对某一次特定调用应用不同的规则,可以直接将这些规则传递给 setGlowing,而无需修改配置文件。
关于其他记分板插件的注意事项
队伍名称为 GAPI#<COLOR>,且仅发送给客户端。它们从不触及服务端记分板,因此管理自有队伍的其他标签页(tab-list)或名字标签插件不会被覆盖。
确实存在的重叠发生在客户端侧,而非服务端:一名玩家在客户端同一时间只能属于一个队伍。如果另一个插件将玩家放入用于前缀的客户端侧队伍中,最后发送数据包的那个队伍将被客户端保留。这是原版协议的局限性,并非任何插件能够绕过的问题。
支持
由 LucasTHCR 维护。原始工作由 InventivetalentDev 完成。
Bug 报告和问题请发送至 dc.gg/paperstream。请附上你的服务器版本以及执行调用的插件信息——发光相关的 bug 几乎总是由于其他触及队伍或实体元数据的插件冲突所致,了解已安装的其他插件有助于省去一轮猜测。
许可证
版权所有 (C) 2026 LucasTHCR
GlowAPI 是自由软件:你可以根据自由软件基金会发布的 GNU 通用公共许可证第 3 版 的条款对其进行再分发和/或修改。
本程序的发布是希望它能有用,但 没有任何保证;甚至没有隐含的对适销性或特定用途适用性的保证。详情请参阅 GNU 通用公共许可证。
原始的 GlowAPI 由 Haylee Schäfer 以 MIT 许可证发布,那些条款仍然适用于原始代码。整个 jar 包采用 GPLv3 是因为其中捆绑的 PacketEvents 为 GPL-3.0,而包含 GPL-3.0 代码的作品必须完整地以 GPL-3.0 进行传播。MIT 与 GPL 兼容,这使得这种操作成为可能。
简而言之:使用它、研究它、修改它、传播它。任何基于它构建并分发的作品也必须采用 GPLv3,并且必须附带其源代码。
这不会侵入你的插件。 在运行时调用 GlowAPI(将其作为独立的 jar 与你自己的插件一起安装)并不构成分发合并作品。你的插件保持为你为其选择的任何许可证。GPLv3 的要求是你不要将 GlowAPI 阴影打包(shading)进你自己的 jar 中,然后以不同的条款发布该 jar。
GlowAPI
Makes players and entities glow in any of the sixteen chat colors, and does it per receiving player.
The vanilla glowing effect is one flag on the entity, so it looks the same to everyone who can see it. That's fine until you want it to mean something. A team plugin wants your own team outlined green and the enemy red, at the same time, on the same entity. A staff tool wants a vanished player outlined only for other staff. A minigame wants the last player alive highlighted for the spectators and nobody else.
None of that is possible with one server-side flag. GlowAPI does it client-side instead: the glow bit and the scoreboard team that carries the color are sent to each viewer individually, so player A can see player B glowing red while player C sees that same player B glowing blue, and player B sees nothing at all.
This is a maintained continuation of InventivetalentDev's GlowAPI, which stopped being updated years ago. Same package, same class, same method signatures - plugins written against the old one keep working without a single code change.
What changed
The old version needed PacketListenerAPI installed alongside it, and that dependency died first. When it stopped being updated, everything built on GlowAPI went with it.
The packet layer is now PacketEvents, bundled inside the jar and relocated, so nothing else has to be installed and nothing collides with another plugin's copy. That also carried the supported range from roughly 1.19 up to the current release.
|
old GlowAPI |
GlowAPI 2.0 |
| Packet layer |
PacketListenerAPI (dead) |
PacketEvents, bundled |
| Extra plugins to install |
one |
none |
| Minecraft versions |
up to ~1.19 |
1.9 through 26.3 |
| Public API |
- |
unchanged |
Minecraft 1.8.x is not supported and won't be. The glowing effect didn't exist before 1.9, so there is nothing to send.
Requirements
- Bukkit, Spigot, Paper or a fork, on Minecraft 1.9 or newer
- Nothing else. PacketEvents is inside the jar
If you already run PacketEvents as its own plugin, GlowAPI notices and uses that instance instead of starting a second one.
Drop the jar in plugins/ and restart. There is no setup step - the plugin is idle until another plugin asks it for something, or until you type /glow.
Glow by permission, no code
Not every server wants to write a plugin to use this. Set auto-glow.enabled: true in
config.yml and give a group glowapi.auto.<color>, for example glowapi.auto.gold for your
VIP rank in LuckPerms. Everyone holding it glows in that color for every other player.
If a player holds several, the first in this order wins: black, dark_blue, dark_green,
dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, purple, yellow,
white. After changing permissions, /glowapi reload applies them to players who are already
online. Only glows handed out this way are taken back, so /glow and other plugins keep theirs.
Using it from your plugin
Add GlowAPI as a soft dependency in your plugin.yml:
softdepend: [GlowAPI]
Then call it. Every method is static, so there is no instance to fetch and no service to look up:
// green for one viewer
GlowAPI.setGlowing(target, GlowAPI.Color.GREEN, viewer);
// red for everyone online
GlowAPI.setGlowing(target, GlowAPI.Color.RED, Bukkit.getOnlinePlayers());
// stop glowing for that viewer
GlowAPI.setGlowing(target, (GlowAPI.Color) null, viewer);
The one thing to watch is timing on join. A player isn't ready to receive entity packets in the same tick they fire PlayerJoinEvent, so give it a moment:
@EventHandler
public void onJoin(PlayerJoinEvent event) {
Bukkit.getScheduler().runTaskLater(this, () ->
GlowAPI.setGlowing(event.getPlayer(), GlowAPI.Color.DARK_AQUA, Bukkit.getOnlinePlayers()), 10L);
}
Getting the API into your build
The artifact lives in Codeberg's package registry.
Maven
<repositories>
<repository>
<id>codeberg-glowapi</id>
<url>https://codeberg.org/api/packages/LucasTHCR/maven</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.inventivetalent</groupId>
<artifactId>glowapi</artifactId>
<version>2.2.0-RELEASE</version>
<scope>provided</scope>
</dependency>
</dependencies>
Gradle (Kotlin DSL)
repositories {
maven("https://codeberg.org/api/packages/LucasTHCR/maven")
}
dependencies {
compileOnly("org.inventivetalent:glowapi:2.2.0-RELEASE")
}
Gradle (Groovy DSL)
repositories {
maven { url 'https://codeberg.org/api/packages/LucasTHCR/maven' }
}
dependencies {
compileOnly 'org.inventivetalent:glowapi:2.2.0-RELEASE'
}
provided and compileOnly are not a detail you can skip. GlowAPI is GPLv3, so shading it
into your own jar would put your whole plugin under GPLv3 as well. Compiling against it and
letting the server supply the jar at runtime does not - your plugin keeps whatever licence
you chose. It also means your users install one GlowAPI, not one copy per plugin.
Server owners install the jar from the download page; nothing extra goes into your build.
The full surface
| Method |
Does |
setGlowing(Entity, Color, Player) |
Sets the color of one entity for one viewer |
setGlowing(Entity, Color, Collection<Player>) |
Same, for several viewers |
setGlowing(Collection<Entity>, Color, Player) |
Several entities, one viewer |
setGlowing(Collection<Entity>, Color, Collection<Player>) |
Several entities, several viewers |
setGlowing(Entity, boolean, Player) |
Glow on or off in the default white |
setGlowing(Entity, Color, String tagVisibility, String push, Player) |
As above, overriding the team's name-tag and collision rules for this call |
isGlowing(Entity, Player) |
Whether that viewer currently sees it glowing |
isGlowing(Entity, Collection<Player>, boolean checkAll) |
checkAll decides between all viewers and any viewer |
getGlowColor(Entity, Player) |
The Color that viewer sees, or null |
initTeam(Player) |
Creates the glow teams for a viewer. Runs on join by itself; you only need it if you build your own login flow |
Color is the sixteen chat colors - BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, PURPLE, YELLOW, WHITE - plus NONE.
NONE means glowing without joining a color team, which the client draws in white. Passing null instead of a Color is the one that turns the glow off.
Anything with a UUID works, not just players: mobs, armor stands, dropped items, item frames.
Commands
The commands exist so you can check the plugin works without writing code first. The real interface is the API.
| Command |
Permission |
Does |
/glow <color|off> [player] |
glowapi.command.glow |
Makes a player glow for everyone online. Without a name, yourself |
/glowapi reload |
glowapi.command.admin |
Re-reads config.yml and rebuilds the teams |
/glowapi version |
glowapi.command.admin |
Prints the running version |
/glowapi debug |
glowapi.command.admin |
Shows the detected client version and the colour ids being sent |
Both permissions default to OP. Tab completion covers the colors and the online players.
Configuration
Four values, and the defaults are what you want unless you have a reason otherwise.
# always | never | hideForOtherTeams | hideForOwnTeam
nameTagVisibility: always
# always | never | pushOtherTeams | pushOwnTeam
collision: always
# auto | always | never
modern-team-colors: auto
auto-glow:
enabled: false
bstats: true
modern-team-colors exists because Minecraft encodes colours as a bit field - blue, green, red, bright - and clients from 26.1 on read the red and blue bits the other way round. Left alone, aqua reaches those clients as yellow and dark_blue as dark_red, while green, gray, black and white look fine because their red and blue bits are the same. auto swaps the two bits for clients on 26.1 and newer and leaves older ones untouched, so it is correct whatever your players connect with. It follows each viewer's client, not the server, so a mixed-version server behind a protocol translator is handled too. /glowapi debug shows you what is being sent.
bstats: true sends anonymous server counts to bStats. Set it to false and nothing is sent.
The color is carried by a scoreboard team, and a team also decides whether its members' name tags are visible and whether they push each other. Those two settings are what a glowing player inherits along with the color, which is why they're configurable here rather than being fixed.
Set collision: never and glowing players walk through each other, which is usually a surprise rather than a feature. Leave both on always and glow is purely cosmetic.
A plugin that needs different rules for one particular call can pass them to setGlowing directly instead of changing the file.
A note on other scoreboard plugins
The teams are named GAPI#<COLOR> and are sent to the client only. They never touch the server-side scoreboard, so a tab-list or nametag plugin managing its own teams won't be overwritten.
The overlap that does exist is the client's, not the server's: a player can only be in one team at a time on the client. If another plugin puts a player in a client-side team for a prefix, whichever of the two sent its packet last is the one the client keeps. This is a limitation of the vanilla protocol, not something either plugin can work around.
Support
Maintained by LucasTHCR. Original work by InventivetalentDev.
Bug reports and questions go to dc.gg/paperstream. Include your server version and the plugin doing the calls - glow bugs are almost always a conflict with something else touching teams or entity metadata, and knowing what else is installed saves a round of guessing.
License
Copyright (C) 2026 LucasTHCR
GlowAPI is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License version 3 as published by the Free Software
Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for details.
The original GlowAPI was released under the MIT License by Haylee Schäfer, and those
terms still govern that original code. The jar as a whole is GPLv3 because the bundled
PacketEvents is GPL-3.0, and a work containing GPL-3.0 code has to be passed on under
GPL-3.0 in full. MIT is GPL-compatible, which is what makes that possible.
Short version: use it, study it, change it, pass it on. Anything you distribute that is
built on it has to be GPLv3 too and has to ship its source.
This does not reach into your plugin. Calling GlowAPI at runtime, with it installed
as its own jar next to yours, is not distributing a combined work. Your plugin stays
under whatever license you picked for it. What GPLv3 asks is that you don't shade
GlowAPI into your own jar and then ship that under different terms.
评论 0
登录后参与评分
还没有评论,来抢沙发吧