Custom Damage Numbers

插件

· 作者 Ded3ec

Custom Damage Numbers 为你的 Minecraft 服务器添加了干净、带动画效果的仅数据包伤害数字指示器。支持完全自定义配置,包括命中合并、跟随实体的动画、样式、玩家开关切换,并兼容现代及旧版服务器版本。

0 本站下载 0 关注 更新于 1 个月前

最新 1.0.0-legacy · 1.20.1 · Folia / Paper

一键开服(送7天)
CustomDamageNumbers banner

View

Typing SVG

CustomDamageNumbers: 完全基于数据包绘制的浮动伤害数字。不会在世界中生成任何实体,数字会跟随承受攻击的实体移动,且动画的每个部分都是 config.yml 中的配置值。

文档 · 示例 · 发布版本 · 问题反馈


为什么选择 CustomDamageNumbers

每一个显示伤害指示器的插件最终都会留下一些残留物:一个在区块保存后幸存下来的盔甲架、一个被插件遗忘未移除的实体、或者一只怪物走开后悬浮在空中的静止数字。而这个插件不会造成这种情况,因为它从未向世界中放置任何东西。

  • 仅通过数据包渲染。 每个数字都是通过 PacketEvents 协议发送的客户端显示实体。不改变任何世界状态,因此卸载时不留痕迹——也不需要向玩家解释为何存在实体计数问题。
  • 锚定于受害者。 数字归属于承受攻击的实体,并在每一步动画中重新定位,因此被击退的怪物流会带着它的数字一起移动。follow-smoothing(跟随平滑)功能会对锚点进行插值而非瞬间切换,从而消除高速目标上的抖动现象。
  • 配置驱动动画。 持续时间、上升、下落、弹跳、环绕、缩放、淡入淡出、生成扩散和锚点高度均为实时可调值。编辑后执行 /cdn reload 即可观察变化——无需重启服务器。
  • 命中合并。 在半秒内的十次命中只会生成一个数字,而不是叠加十个,支持配置时间窗口、上限和攻击者规则。
  • 仅限玩家造成的伤害。 只有玩家造成的伤害(近战、弓箭或其他投射物)才会显示数字。怪物对你造成的伤害、坠落伤害或火焰灼烧伤害故意不显示为伤害数字,这正是保持怪物农场界面清晰可读的原因。
  • 玩家自主选择。 /cdn toggle 可为单个玩家关闭数字显示,并跨重启持久化;当玩家的权限等级允许时,/cdn style 可选择一种样式配置文件。
  • 两个 JAR,一套代码库。 针对 1.20.2 – 26.x 的现代文本显示渲染器,以及针对 1.17.x – 1.20.1 的旧版盔甲架渲染器,背后由统一的 RenderBackend 接口支撑。编译时基于最旧的受支持 API,确保 Paper 专属类不会泄露。

完整文档位于 cdn.docs.potenfyr.in:包括 配置参考、示例 和 故障排除。本 README 内容与之一致。

? 我应该安装哪个 JAR?

JAR 服务端版本 渲染器 淡入淡出 / 缩放动画
CustomDamageNumbers-1.0.0.jar 1.20.2 – 26.x 客户端 TextDisplay ✅ 支持
CustomDamageNumbers-Legacy-1.0.0.jar 1.17.x – 1.20.1 客户端盔甲架名称标签 ❌ 仅位置

现代版 JAR 会在旧版服务器上拒绝启用,并提示你改用正确的 JAR,而不是什么都不渲染。旧版 JAR 也可以在现代服务器上运行,但现代版在这些服务器上表现更好(只有 TextDisplay 才能按实体进行淡入淡出和缩放);其启动日志中会有说明。在运行的服务器上执行 /cdn backend 可查看当前激活的是哪一个及其支持的功能。

? 要求

要求 最低版本 备注
Minecraft server 1.17.1 Spigot、Paper、Purpur、Pufferfish、Folia 及其分支
Java 17 jar 包基于 Java 17 字节码
PacketEvents 2.14 唯一的硬性依赖项
LuckPerms 可选 样式配置与权限路由
PlaceholderAPI 可选 其他插件中的伤害占位符

? 安装

plugins/
  PacketEvents-2.14.0.jar
  CustomDamageNumbers-1.0.0.jar          # 1.20.2 - 26.x
  # 或
  CustomDamageNumbers-Legacy-1.0.0.jar   # 1.17.x - 1.20.1

重启服务器,然后查看控制台横幅和 /cdn version。所有配置值均在执行 /cdn reload 时读取,因此以下操作无需重启即可生效。

⌨️ 命令与权限

命令 功能 权限节点 默认状态
/cdn help 显示格式化的命令列表,并过滤出你可能使用的命令 – –
/cdn version 显示插件、渲染器和服务器面板信息 – –
/cdn backend 显示当前活跃的渲染器及其功能 – –
/cdn stats 实时计数器、观众槽位、Tick 开销 cdn.stats op
/cdn toggle [on|off] [player] 为自己或其他玩家开启或关闭数字显示 cdn.toggle / cdn.toggle.others true / op
/cdn style [player] <profile|default> 选择一种样式配置 cdn.style / cdn.style.others true / op
/cdn test [type] [amount] 生成一个测试显示,无需造成伤害 cdn.test op
/cdn clear [player|all] 立即移除所有实时显示 cdn.clear op
/cdn reload [config|messages|all] 重新加载配置和/或消息文件 cdn.reload op
/cdn debug [on|off] 启用详细日志记录 cdn.debug op

别名:两个 jar 包均支持 /damagedisplay,Legacy jar 还支持 /damage——现代 jar 刻意保留 /damage 给原版使用,因为原版在 1.20.5 中新增了该命令。样式配置是按玩家授予的(cdn.style.fortnite 默认为 true,cdn.style.mmo 默认为 false),因此 LuckPerms 可以将特定样式授予某个权限组。仅当 permissions.require-view-permission 为 true 时,才会强制执行 cdn.view 权限。

每个面板会根据运行环境自适应:玩家看到的是框线边框,而控制台和 RCON 看到的是去除了颜色代码的 ASCII 边框。

⚙️ 配置

随附的 config.yml 包含完整注释。用户通常会修改的部分如下:

general:
  enabled: true              # 总开关
  view-distance: 32          # 玩家接收数字的最大距离
  disabled-worlds: [example_world]
  entities: { mobs: true, players: true, animals: true }
  max-active-displays: 2000  # 防止怪物农场洪水般的显示
  default-view-enabled: true # 玩家在未执行 /cdn toggle 前看到的默认状态

animation:
  preset: default            # 来自 presets.yml 的动画预设
  # 以下任何键都会覆盖所选预设中的单个值
  #duration-ticks: 30        # 总生命周期(20 ticks = 1秒)
  #rise-ticks: 10            # 开始下沉前上升的 tick 数
  #vertical-speed: 0.08      # 上升时每秒移动的方块数
  #scale-animation: true
  #start-scale: 1.3
  #end-scale: 0.8
  #fade-out: true            # 仅限现代 jar
  #bounce: true
  #follow-entity: true       # 数字跟随受伤实体
  #follow-smoothing: 0.35    # 0 = 每 tick 瞬间吸附,数值越高越平滑
  #position: { x: 0.0, y: 1.8, z: 0.0 }
  #offset: { random: true, spread: 0.20 }

merge-system:
  enabled: true
  merge-window-ms: 150       # 在此时间窗口内的后续攻击会使数字增长

styles:
  normal:   { format: "{damage}",    color: "#FFFFFF", bold: true, shadow: true }
  critical: { format: "✧ {damage}",  color: "#FF3333", bold: true, shadow: true }
  healing:  { format: "+{damage}",   color: "#00FF99", bold: true, shadow: true }

style-profiles:              # 通过 cdn.style.<name> 授予
  fortnite: { critical: { format: "{damage}", color: "#FFFF00" } }
  mmo:      { normal: { format: "{damage} DMG" }, critical: { format: "{damage} CRIT", color: "#FF5555" } }

critical-hits:
  sound-type: entity.player.attack.crit   # 支持原版键名和 Bukkit 风格名称

? 开发者 API

其他插件可以生成伤害数字、重设插件渲染的所有内容,或管理按玩家的设置。添加 in.potenfyr:cdn-api:1.0.0(通过 ./gradlew :cdn-api:publishToMavenLocal 构建)作为 compileOnly 依赖,并在你的 plugin.yml 中添加 softdepend: [CustomDamageNumbers],然后:

CustomDamageNumbersApi api = CustomDamageNumbersApi.get().orElse(null);
if (api != null) {
    api.spawn(api.numberBuilder()
            .at(victim)                      // 或使用 .at(location) 设置固定锚点
            .value(42.5)
            .type("fire")                    // styles.<key>,或设置 .format(...)
            .format("<gold>✦ {damage}")      // MiniMessage 或旧版代码
            .preset("explosive")             // 来自 presets.yml 的动画预设
            .critical(true));
}

每个 Builder 选项都是可选的:未指定的值将回退到插件配置,preset 会按键覆盖这些配置,而显式的 Builder 设置优先级最高。监听 DamageNumberSpawnEvent 以取消或重设插件渲染的每一个数字,包括你自己生成的。完整接口请参阅 cdn-api/src/main/java/in/potenfyr/cdn/api。

插件输出的所有字符串都位于 messages.yml 中,包括 frame: 块(宽度、边框、标题、副标题、标签、数值、强调色、字形、项目符号)——只需编辑一次,聊天面板和控制台面板都会同步更改。

? 兼容性说明

服务器版本 Jar 类型 状态
1.17.x – 1.19.x Legacy 已全面验证
1.20.1 Legacy 已全面验证
1.20.2 – 1.21.x Modern 已验证,包括淡出和缩放效果
26.x (Paper) Modern 已验证;旧版客户端可通过 ViaVersion 连接
Folia 任意 folia-mode: auto 会选择区域调度器
  • 1.16.x 已无法支持。 Paper 1.16.5 拒绝在 Java 17 上运行(Unsupported Java detected (61.0)),且其 jar 包为 Java 17 字节码。实际最低兼容版本为 1.17.1。
  • ViaVersion、ViaBackwards、ViaRewind、Geyser、ProtocolLib 和 ProtocolSupport 均为软依赖:仅检测,不强制要求。
  • Fade(淡入淡出)效果和按实体的缩放需要 TextDisplay。旧版 jar 中的位置参数和偏移数值虽能生效,但无法实现淡入淡出——这是两个 jar 之间唯一的机制差异。

? 构建

构建使用 Gradle(包含 cdn-core、cdn-modern、cdn-legacy 模块),并在 Docker 中运行,因此无需宿主机工具链:

docker run --rm -v "$PWD:/app" -v "cdn-gradle:/home/gradle/.gradle" -w /app \
  gradle:jdk17 gradle build --no-daemon

这将生成 cdn-modern/build/libs/CustomDamageNumbers-<version>.jar(已重定位 kyori 和 bStats 依赖)以及 cdn-legacy/build/libs/CustomDamageNumbers-Legacy-<version>.jar。

? 测试

docker run --rm -v "$PWD:/app" -w /app gradle:jdk17 gradle test --no-daemon
bash docker/e2e/run.sh          # 完整矩阵:1.17.1, 1.20.1, 1.21.8, 26.3
bash docker/e2e/run.sh 1.21.8   # 单版本测试,用于快速循环

单元测试套件(共 108 个测试)覆盖了配置解析、伤害分类、合并逻辑、偏好设置存储、帧渲染器以及两种渲染器的行为。端到端测试框架会在 Docker 中为每个版本启动一个真实的 Paper 服务器,安装构建好的 jar 包及 PacketEvents,并断言显示对象是否被创建、定位、在动画过程中移动并最终销毁——同时确保插件能干净禁用且服务器日志中无错误。测试结果证据保存在 docker/e2e/evidence/ 目录下。

? 发布

插件版本号固定为 1.0.0,不会因每次变更而递增。.github/workflows/release.yml 会在每次推送到 master 分支时自动发布:它执行构建和测试,从 gradle.properties 读取版本号,将新的 Build N 部分(自上次构建以来的提交记录)合并到该版本的发布说明中,使用 --clobber 选项重新上传两个 jar 包,并将 v1.0.0 标签移动到最新的构建提交上。因此,v1.0.0 始终携带最新的 jar 包和累积的更新日志,每次推送都会新增一条记录。

? 贡献

欢迎提交 PR;有关设置、命令及不可妥协的要求,请参阅 CONTRIBUTING.md。简而言之:

  1. 只操作数据包,绝不生成实体——任何代码路径都不得向世界中生成真实实体。
  2. 针对最旧的受支持 API 进行编译;特定于版本的代码应属于渲染器部分,而非核心模块。
  3. 行为变更需附带测试;推送前请运行构建及相关版本的端到端测试。

发现安全漏洞?请私下报告:详见 SECURITY.md。

CustomDamageNumbers contributors

? 文档与链接

? 许可协议

本插件基于 Apache License 2.0 加上 Commons Clause 授权:允许免费运行、分叉、修改和构建,包括在商业服务器上;禁止作为产品出售。详见 LICENSE;LICENSE 文件具有最终解释权。Minecraft 和 Mojang 商标归 Mojang 所有;详见 NOTICE.md。


由 PotenFYR Studios 开发 · potenfyr.in · 属于 PotenFYR Studios 开源生态系统的一部分。


⭐ Star 历史记录

PotenFYR Studios 所有公开仓库的星标历史图表

PotenFYR Studios 的所有公开仓库均收录在此实时图表中,由 star-history.com 提供。

贡献蛇形动画
footer

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源