Hydration: A Configurable Thirst Mechanic for Paper

## 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: 1. **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. 2. **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 **` | `hydration.admin` | Fully refill a player | | `**/thirst set <0-100>**` | `hydration.admin` | Set a player's thirst | | `**/thirst add **` | `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** **1**. Download the plugin JAR. **2**. Drop it into your server's `plugins/` folder. **3**. Restart the server (default configs will generate automatically). **4**. 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. If you like this plugin and would like to see it updated/changed/more added to it consider a **donation**!(not required I still **<3** you and appreciate the support for my plugin!)

Hydration

1.0.0