HealthScale
一款轻量级的 Paper/Folia 插件,用于缩放玩家 HUD 中的血量显示——无论玩家实际拥有多少生命值,心形血条始终渲染为配置的值。
专为高血量 RPG 服务器设计,并完全兼容 Folia 的多线程区域调度。
功能特性
- 全局血量缩放 — 为所有世界设置一个统一的显示值
- 按世界覆盖 — 每个世界使用不同的缩放比例(例如:RPG 世界中为 80 颗心,竞技场中为 20 颗)
- 热重载 —
/healthscale reload 会重新加载 config.yml 并立即应用到所有在线玩家,无需重启服务器
- 运行时设置 —
/healthscale set <value> 可在不修改配置文件的情况下动态更改全局缩放值
- 原生支持 Folia — 所有玩家状态变更均通过
EntityScheduler 分发;批量操作通过 GlobalRegionScheduler 执行
- MiniMessage 消息格式 — 所有消息均完全支持 MiniMessage 格式化
- 可配置的数值边界 —
min-scale / max-scale 防止输入无意义的数值;无效输入会自动回退到默认值
依赖要求
| 依赖项 |
版本 |
| Java |
25+ |
| Paper / Folia |
1.21 (API),已在 26.1.2 上测试 |
| Minecraft |
1.21+ |
该插件基于 Paper API 编译,并声明了 folia-supported: true,因此它可以在 Paper 和 Folia 上运行。
安装步骤
- 从 Releases 下载最新的
HealthScale-x.x.x.jar。
- 将其放入服务器的
plugins/ 文件夹中。
- (重新)启动服务器 —— 将自动生成默认的
config.yml。
- 根据需要编辑
plugins/HealthScale/config.yml。
- 运行
/healthscale reload 以应用更改,无需重启服务器。
指令
| 指令 |
描述 |
权限节点 |
/healthscale info |
显示当前插件版本及激活的血量缩放值 |
healthscale.use |
/healthscale reload |
重新加载 config.yml 并应用到所有在线玩家 |
healthscale.admin |
/healthscale set <value> |
在运行时更改全局血量缩放值 |
healthscale.admin |
别名: /hs, /hscale
权限节点
| 节点 |
默认权限 |
描述 |
healthscale.use |
everyone |
访问 /healthscale info |
healthscale.admin |
OP |
访问 reload 和 set 子指令 |
healthscale.* |
OP |
授予上述所有权限 |
配置说明
# plugins/HealthScale/config.yml
# 启用或禁用整体血量缩放功能
enabled: true
# 所有世界的默认显示缩放值 (20.0 = 10 颗心)
# 无论玩家实际最大 HP 是多少,HUD 始终显示这么多颗心
health-scale: 20.0
# 允许的健康缩放数值范围
min-scale: 2.0
max-scale: 2048.0
# 按世界覆盖 — 列出的世界将使用其自身的缩放值
# 未列出的世界将回退到上方定义的 health-scale
world-overrides:
# rpg_world:
# health-scale: 80.0 # 你的 RPG 世界中为 40 颗心
# arena_world:
# health-scale: 20.0 # 竞技场中为标准 10 颗心
# 所有消息均支持 MiniMessage 格式化
# 可用的占位符如下文注释所示
messages:
no-permission: "<red>你沒有權限執行此指令!</red>"
reload-start: "<yellow>正在重載 HealthScale 設定...</yellow>"
reload-success: "<green>設定重載完成!全域血量縮放: <white><scale></white></green>" # {scale}
reload-invalid-scale: "<red>health-scale 數值無效(必須介於 <min> ~ <max>),已還原預設值。</red>" # {min} {max}
set-success: "<green>已將血量顯示縮放設為 <white><scale></white> 顆心。</green>" # {scale}
set-invalid: "<red>無效數值。請輸入介於 <min> ~ <max> 之間的數字。</red>" # {min} {max}
usage: "<red>用法:<white>/healthscale <reload|set <數值>|info></white></red>"
info: "<aqua>HealthScale v<version> | 全域縮放: <white><scale></white> | 世界覆蓋: <white><overrides></white> 個</aqua>" # {version} {scale} {overrides}
缩放数值参考
health-scale |
显示的爱心数量 |
20.0 |
10 颗心(原版默认值) |
40.0 |
20 颗心 |
80.0 |
40 颗心 |
200.0 |
100 颗心 |
玩家的真实最大生命值不会受到影响 —— 仅改变视觉表现。
工作原理
Minecraft 的 Player#setHealthScaled 和 Player#setHealthScale 方法控制客户端如何渲染心形血条。
当设置为 80.0 时,拥有 2000 最大生命值的玩家仍会看到满格的 40 颗心 —— 他们的生命值只是映射到了这个显示范围内。
HealthScale 挂钩了 PlayerJoinEvent、PlayerRespawnEvent 和 PlayerChangedWorldEvent,以便在每个相关时刻正确地(重新)应用缩放值。
在 Folia 上,所有状态变更都通过 EntityScheduler 分发到所属的区域线程,以确保线程安全。
从源代码构建
git clone https://github.com/Misty4119/HealthScale.git
cd healthscale
./gradlew shadowJar
输出的 jar 包位于 build/libs/HealthScale-2.0.0.jar。
许可证
本项目为开源项目。详情请参阅 LICENSE。
作者
由 Misty4119 制作 (Misty4119)
HealthScale
A lightweight Paper/Folia plugin that scales the health display in players' HUD — no matter how many actual hit points a player has, the heart bar always renders at the configured value.
Designed for high-health RPG servers and fully compatible with Folia's multi-threaded region scheduling.
Features
- Global health-scale — set a single display value for all worlds
- Per-world overrides — different scale for each world (e.g. 80 hearts in your RPG world, 20 in the arena)
- Live reload —
/healthscale reload reloads config.yml and reapplies to all online players instantly, no restart needed
- Runtime set —
/healthscale set <value> changes the global scale on the fly without touching the config file
- Folia-native — all player mutations are dispatched through
EntityScheduler; bulk operations through GlobalRegionScheduler
- MiniMessage — every message is fully customizable with MiniMessage formatting
- Configurable bounds —
min-scale / max-scale guard against nonsensical values; invalid entries fall back gracefully
Requirements
| Requirement |
Version |
| Java |
25+ |
| Paper / Folia |
1.21 (API), tested on 26.1.2 |
| Minecraft |
1.21+ |
The plugin is compiled against the Paper API and declares folia-supported: true, so it runs on both Paper and Folia.
Installation
- Download the latest
HealthScale-x.x.x.jar from Releases.
- Drop it into your server's
plugins/ folder.
- (Re)start the server — a default
config.yml is generated automatically.
- Edit
plugins/HealthScale/config.yml to your liking.
- Run
/healthscale reload to apply changes without restarting.
Commands
| Command |
Description |
Permission |
/healthscale info |
Show the current plugin version and active scale values |
healthscale.use |
/healthscale reload |
Reload config.yml and reapply to all online players |
healthscale.admin |
/healthscale set <value> |
Change the global health-scale at runtime |
healthscale.admin |
Aliases: /hs, /hscale
Permissions
| Node |
Default |
Description |
healthscale.use |
everyone |
Access to /healthscale info |
healthscale.admin |
OP |
Access to reload and set subcommands |
healthscale.* |
OP |
Grants all permissions above |
Configuration
# plugins/HealthScale/config.yml
# Enable or disable health scaling entirely
enabled: true
# Default display scale for all worlds (20.0 = 10 hearts)
# The HUD always shows this many hearts regardless of the player's actual max HP
health-scale: 20.0
# Allowed range for health-scale values
min-scale: 2.0
max-scale: 2048.0
# Per-world overrides — worlds listed here use their own scale value
# Worlds not listed fall back to health-scale above
world-overrides:
# rpg_world:
# health-scale: 80.0 # 40 hearts for your RPG world
# arena_world:
# health-scale: 20.0 # standard 10 hearts in the arena
# All messages support MiniMessage formatting
# Available placeholders are shown in the comments below
messages:
no-permission: "<red>你沒有權限執行此指令!</red>"
reload-start: "<yellow>正在重載 HealthScale 設定...</yellow>"
reload-success: "<green>設定重載完成!全域血量縮放: <white><scale></white></green>" # {scale}
reload-invalid-scale: "<red>health-scale 數值無效(必須介於 <min> ~ <max>),已還原預設值。</red>" # {min} {max}
set-success: "<green>已將血量顯示縮放設為 <white><scale></white> 顆心。</green>" # {scale}
set-invalid: "<red>無效數值。請輸入介於 <min> ~ <max> 之間的數字。</red>" # {min} {max}
usage: "<red>用法:<white>/healthscale <reload|set <數值>|info></white></red>"
info: "<aqua>HealthScale v<version> | 全域縮放: <white><scale></white> | 世界覆蓋: <white><overrides></white> 個</aqua>" # {version} {scale} {overrides}
Scale value reference
health-scale |
Hearts displayed |
20.0 |
10 hearts (vanilla default) |
40.0 |
20 hearts |
80.0 |
40 hearts |
200.0 |
100 hearts |
The player's actual max HP is not affected — only the visual representation changes.
How it works
Minecraft's Player#setHealthScaled and Player#setHealthScale control how the client renders the heart bar.
When set to, say, 80.0, a player with 2000 max HP will still see a full bar of 40 hearts — their HP is just mapped to that display range.
HealthScale hooks into PlayerJoinEvent, PlayerRespawnEvent, and PlayerChangedWorldEvent to (re)apply the correct scale at every relevant moment.
On Folia, every state mutation is dispatched to the owning region thread via EntityScheduler to stay thread-safe.
Building from source
git clone https://github.com/Misty4119/HealthScale.git
cd healthscale
./gradlew shadowJar
The output jar is at build/libs/HealthScale-2.0.0.jar.
License
This project is open source. See LICENSE for details.
Author
Made by Misty4119 (Misty4119)
评论 0
登录后参与评分
还没有评论,来抢沙发吧