GlowAPI

插件

· 作者 LucasTHCR

使玩家和实体在任何聊天颜色中发光,根据接收者不同——两个观众可以看到同一个玩家呈现两种不同的颜色。

0 本站下载 0 关注 更新于 3 天前

最新 2.2.2-RELEASE · 26.3 · Bukkit / Folia

一键开服(送7天)

Built with Java 8 Available for Paper Available for Purpur Available for Spigot Available for Bukkit

Chat with us on Discord

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。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源