Hydration: 适用于 Paper 的自定义口渴机制模组

- 版本:1.0.0
- 适用:Paper 26.1.2 (Minecraft 1.21.x)
- 依赖:Java 25
- 软依赖:PlaceholderAPI (可选)
<--->
概述
Hydration 为你的生存服务器添加了一个功能完善且与原版的风格相融合的口渴机制。玩家通过饮水、牛奶、汤和水果来保持水分充足;如果忽视补水,他们将感受到后果:挖掘疲劳、缓慢、虚弱、饥饿,随着口渴值降至零,还会遭受周期性的伤害。
整个系统围绕着一个核心设计目标构建:让它感觉像是原版 Minecraft 的一部分。没有 Boss 血条,没有侵入式的 UI,也没有强制性的肝度——只有一个清爽的动作栏计量表,以及一个奖励玩家真正利用周围水源的系统。
<--->
工作原理
每位玩家都有一个隐藏的 0-100 口渴属性,直接保存在其玩家数据中(通过 PersistentDataContainer),因此它能在重启后保留且永远不会不同步。口渴值会随时间自动消耗,消耗速率根据玩家实际的行为和环境进行调整:
- 活动状态 -> 冲刺、游泳、战斗、挖矿以及使用鞘翅飞行都会比静止站立更快地消耗口渴值。
- 生物群系 -> 沙漠、恶地、热带草原和下界会加速脱水。雪原生物群系和针叶林会降低消耗速度。
- 天气 -> 如果在户外遭遇降雨或雷暴,口渴值会缓慢恢复。
- 睡眠 -> 从床上醒来时会恢复少量口渴值,正如休息应有的效果一样。
HUD 显示
Hydration 仅使用动作栏,没有 Boss 血条。它显示一个水滴形状的计量表,随着口渴值下降颜色会发生变化:
██████████ 100% (青色)
██████░░░░ 60% (黄色)
██░░░░░░░░ 20% (金色 → 红色)
当你的口渴值处于危险低位时,你会在动作栏、聊天框、标题/副标题以及音效中收到警告。所有这些警告都是独立可配置的,并设有冷却间隔,确保你不会受到信息轰炸。
饮水方式
玩家可以通过两种方式恢复口渴值:
- 食用物品 <-> 水瓶、牛奶桶、蜂蜜瓶、炖菜(蘑菇、甜菜根、兔子肉、诡异炖菜)、西瓜、浆果、苹果(普通和金苹果)、紫颂果、胡萝卜和甜菜根。每种物品的数值均可单独配置。
- 直接从环境中饮水 <-> 对着河流、海洋、湖泊、水源方块、含水方块或炼药锅按住 Shift + 右键。此操作具有可配置的冷却时间、恢复量、音效和粒子效果。
脏水(可选)
如果启用,饮用自然水有一定几率获得负面效果:饥饿、中毒、反胃或挖掘疲劳,概率会根据生物群系加权调整。在沙漠绿洲喝水比在针叶林的河里喝水风险更大。此功能完全可选,只需一行代码即可禁用。
基于阈值的状态效果
随着口渴值降低,效果会分阶段叠加:
| 口渴值 |
效果 |
| 60% |
仅发出警告 |
| 40% |
挖掘疲劳 I |
| 30% |
缓慢 I |
| 20% |
虚弱 |
| 10% |
饥饿 + 缓慢 II |
| 5% |
黑暗闪烁,心跳/沉重呼吸音效 |
| 0% |
周期性伤害,虚弱 II,挖掘疲劳 III,无法冲刺 |
每个阈值、效果、放大倍数和持续时间均可在 potions.yml 中进行编辑。
<--->
命令
| 命令 |
权限 |
描述 |
/thirst |
hydration.use |
显示你当前的口渴值 |
/thirst help |
hydration.use |
显示帮助菜单 |
/thirst refill <player> |
hydration.admin |
完全补充某位玩家的口渴值 |
/thirst set <player> <0-100> |
hydration.admin |
设置某位玩家的口渴值 |
/thirst add <player> <amount> |
hydration.admin |
为某位玩家增加口渴值 |
/thirst reload |
hydration.reload |
重新加载所有配置文件,无需重启 |
/thirst debug |
hydration.debug |
切换调试日志记录 |
权限
hydration.use (默认:true) -> 访问基本命令
hydration.admin (默认:op) -> 执行 refill / set / add 命令
hydration.reload (默认:op) -> 重载配置
hydration.bypass (默认:op) -> 完全豁免口渴消耗和效果
hydration.debug (默认:op) -> 查看调试输出
<--->
PlaceholderAPI 支持
如果安装了 PlaceholderAPI,Hydration 会自动注册以下占位符:
%hydration_thirst% -> 原始数值(0–100)
%hydration_percent% -> 百分比形式的口渴值
%hydration_status% -> Hydrated / Thirsty / Dehydrating / Critical
%hydration_bar% -> 原始计量表,可直接放入记分板或标签页列表
<--->
统计数据
Hydration 默默地为每位玩家追踪以下数据:
- 总饮用量
- 完全脱水的次数
- 累计恢复的水分量
- 最长未饮水存活时长
- 当前口渴值
这些数据按玩家存储,非常适合作为未来统计/排行榜插件的基础 groundwork。
<--->
完全可配置性
没有任何内容被硬编码。八个独立的配置文件让你无需触碰代码即可微调整个插件:
- config.yml -> 核心口渴设置、HUD、警告、活动/生物群系/天气开关
- foods.yml -> 所有支持物品的口渴恢复值
- biomes.yml -> 各生物群系的消耗倍率和脏水倍率
- potions.yml -> 所有状态效果的阈值
- messages.yml -> 所有面向玩家显示的文本,支持
& 颜色代码
- sounds.yml / particles.yml -> 插件使用的每种音效和粒子效果
执行 /thirst reload 即可即时应用更改 —— 无需重启服务器。
<--->
要求
- 服务端软件:Paper 26.1.2(也应在基于相同 API 构建的分叉版上运行)
- Minecraft 版本:1.21.x
- Java:25
- 依赖项:无必需依赖。PlaceholderAPI 完全可选且会自动检测。
<--->
安装
- 下载插件 JAR 文件。
- 将其放入服务器的
plugins/ 文件夹中。
- 重启服务器(默认配置将自动生成)。
- 根据需要调整
config.yml 等配置文件,然后执行 /thirst reload。
<--->
为什么选择 Hydration?
大多数 thirst 插件要么强行添加第二个状态栏,使屏幕显得杂乱无章;要么硬编码数值,无法适配不同服务器的节奏。Hydration 的设计初衷恰恰相反:它仅提供一个简洁的动作栏(action-bar)计量条,并将所有数值——包括脱水速率、恢复量、生物群系影响、阈值以及提示信息——全部开放给管理员,以便他们根据各自生存服务器的难度曲线进行自定义调整。
Hydration: A Configurable Thirst Mechanic for Paper

- Version: 1.0.0
- For: Paper 26.1.2 (Minecraft 1.21.x)
- Requires: Java 25
- Soft-dependency: PlaceholderAPI *(optional)*
<--->
Overview
Hydration adds a fully-featured, vanilla-friendly thirst mechanic to your survival server. Players drink water, milk, soups, and fruit to stay hydrated and if they don't, they'll feel it: mining fatigue, slowness, weakness, hunger, and eventually periodic damage as their thirst bar drops to zero.
Everything is built around a single design goal: feel like it belongs in vanilla Minecraft. No boss bars, no intrusive UI, no forced grind just a clean action-bar meter and a system that rewards players for actually using the water around them.
<--->
How It Works
Every player has a hidden thirst stat from 0-100, saved directly to their player data (via PersistentDataContainer) so it survives restarts and never desyncs. Thirst drains automatically over time, and the drain rate scales with what the player is actually doing and where they are:
- Activity -> sprinting, swimming, fighting, mining, and flying with an elytra all drain thirst faster than standing still.
- Biome -> deserts, badlands, savannas, and the Nether dry you out faster. Snowy biomes and taiga slow drain down.
- Weather -> rain and thunderstorms slowly restore thirst if you're caught outside.
- Sleep -> waking up from a bed restores a bit of thirst, just like resting should.
The HUD
Hydration uses an action bar only no boss bar. It displays a droplet meter that shifts color as your thirst drops:
██████████ 100% (Aqua)
██████░░░░ 60% (Yellow)
██░░░░░░░░ 20% (Gold → Red)
When you're critically low, you'll get warnings across action bar, chat, title/subtitle, and sound all independently toggleable and cooldown-gated so you're never spammed.
Drinking
Players can restore thirst two ways:
- Consuming items <-> water bottles, milk buckets, honey bottles, stews (mushroom, beetroot, rabbit, suspicious), melons, berries, apples (regular and golden), chorus fruit, carrots, and beetroot. Every value is configurable per item.
- Drinking directly from the environment <-> Sneak + Right-Click while looking at rivers, oceans, lakes, water source blocks, waterlogged blocks, or cauldrons. This has a configurable cooldown, restoration amount, sound, and particle effect.
Dirty Water (optional)
If enabled, drinking natural water carries a chance of a negative effect hunger, poison, nausea, or mining fatigue with the odds weighted per-biome. Drinking from a desert oasis is riskier than drinking from a river in the taiga. This is fully optional and can be disabled in one line.
Status Effects by Threshold
As thirst drops, effects stack up in stages:
| Thirst |
Effect |
| 60% |
Warning only |
| 40% |
Mining Fatigue I |
| 30% |
Slowness I |
| 20% |
Weakness |
| 10% |
Hunger + Slowness II |
| 5% |
Darkness flashes, heartbeat/heavy-breathing sounds |
| 0% |
Periodic damage, Weakness II, Mining Fatigue III, cannot sprint |
Every threshold, effect, amplifier, and duration is editable in potions.yml.
<--->
Commands
| Command |
Permission |
Description |
/thirst |
hydration.use |
Show your current thirst |
/thirst help |
hydration.use |
Show the help menu |
/thirst refill <player> |
hydration.admin |
Fully refill a player |
/thirst set <player> <0-100> |
hydration.admin |
Set a player's thirst |
/thirst add <player> <amount> |
hydration.admin |
Add thirst to a player |
/thirst reload |
hydration.reload |
Reload all config files, no restart needed |
/thirst debug |
hydration.debug |
Toggle debug logging |
Permissions
hydration.use (default: true) -> access to basic commands
hydration.admin (default: op) -> refill / set / add
hydration.reload (default: op) -> reload configs
hydration.bypass (default: op) -> exempt from thirst drain and effects entirely
hydration.debug (default: op) -> debug output
<--->
PlaceholderAPI Support
If PlaceholderAPI is installed, Hydration automatically registers:
%hydration_thirst% -> raw value (0–100)
%hydration_percent% -> thirst as a percentage
%hydration_status% -> Hydrated / Thirsty / Dehydrating / Critical
%hydration_bar% -> the raw meter, ready to drop into scoreboards or tab lists
<--->
Statistics
Hydration quietly tracks, per player:
- Total drinks consumed
- Times fully dehydrated
- Lifetime hydration restored
- Longest streak survived without drinking
- Current thirst
These are stored per-player and are ideal groundwork for a stats/leaderboard addon down the line.
<--->
Full Configurability
Nothing is hardcoded. Eight separate config files let you tune the entire plugin without touching code:
- config.yml -> core thirst settings, HUD, warnings, activity/biome/weather toggles
- foods.yml -> hydration value for every supported item
- biomes.yml -> per-biome drain and dirty-water multipliers
- potions.yml -> every status effect threshold
- messages.yml -> all player-facing text, with
& color code support
- sounds.yml / particles.yml -> every sound and particle effect used by the plugin
/thirst reload applies changes instantly — no restart required.
<--->
Requirements
- Server software: Paper 26.1.2 (should also run on forks built against the same API)
- Minecraft version: 1.21.x
- Java: 25
- Dependencies: None required. PlaceholderAPI is fully optional and auto-detected.
<--->
Installation
- Download the plugin JAR.
- Drop it into your server's
plugins/ folder.
- Restart the server (default configs will generate automatically).
- Tune
config.yml and friends to taste, then /thirst reload.
<--->
Why Hydration?
Most thirst plugins either bolt on a second boss bar and clutter the screen, or hardcode values that don't fit every server's pace. Hydration was built to be the opposite: a single clean action-bar meter, and every number drain rates, restoration amounts, biome effects, thresholds, messages exposed for admins to tune to their own survival server's difficulty curve.
评论 0
登录后参与评分
还没有评论,来抢沙发吧