WaterBar999

💧 How Thirst Works

• Every player has a water level, from nothing up to the maximum set in the configuration. The current level is shown on screen at all times through the water bar.
• Water drains slowly over time — once every ten seconds. How much is lost depends on where the player is and what they are doing:
  • Hot places drain water much faster, cold places drain it much more slowly, and anywhere else uses a middle rate.
  • Being active drains more: sprinting, jumping, swimming, mining and fighting all increase the drain, and they stack when several happen at once.
• Low water is announced. When the level falls to the warning point, the player is told their water is low. At the critical point, low-water effects begin.
• No water means damage. Once the level reaches zero, the player takes damage on a repeating timer until they drink or die. Players who die this way get their own dehydration death message.
• Everyone starts with a full bar. New players and players who respawn after dying return to the starting water level.
• Creative and spectator players are not affected. They never lose water and never take thirst damage, so building and spectating are never interrupted.

🖥 Water Bar Displays

The water bar can be shown in four different ways, chosen by the server:

• Experience bar — fills the experience bar above the hotbar. Default.
• Action bar — a line of text above the hotbar that also shows the current level, for example 87/100, and turns yellow or red as water runs low.
• Boss bar — a coloured bar along the top of the screen, which works well with the segmented styles.
• Sidebar panel — a small panel on the side of the screen showing the bar. While this display is active it takes over the sidebar.

The bar itself is fully adjustable: how many segments it has, which symbols are used for filled and empty segments, and which colours are used for each.

---

⚙️ Configuration

All settings live in config.yml. Every duration measured in ticks uses Minecraft ticks, where 1 second equals 20 ticks.

💧 Water Levels

• max-water — the highest water level a player can have. Everything else follows this value: the bar, the warnings, the commands and the placeholders all use it, so a smaller number makes the whole system harder.
• starting-water — the level a player begins with when they first join and when they respawn after dying.
• dirty-water-restore — how much water is gained by drinking dirty water.
• clean-water-restore — how much water is gained by drinking clean water. This is intentionally much larger than dirty water.

⚠️ Thresholds

• low-water — the level at which players start being warned. When the bar reaches this point the warning appears, and the "low" effects begin.
• critical — the level at which the situation becomes critical. The stronger "critical" effects replace the low ones. This value must not be higher than the warning level.

🖥 Display

• display.type — which water bar display to use. Valid choices are EXP, ACTION_BAR, BOSS_BAR and SCOREBOARD.
• display.bar-length — how many segments the bar is made of. A larger number gives a more precise bar.
• display.filled-symbol and display.empty-symbol — the characters used for the filled and empty parts of the bar.
• display.filled-color and display.empty-color — the colours of those two parts. Any Minecraft colour name works, such as AQUA, BLUE, GOLD or DARK_GRAY.
• display.boss-bar.color — the colour of the boss bar, for example BLUE, RED, GREEN, YELLOW, PURPLE, PINK or WHITE.
• display.boss-bar.style — the shape of the boss bar: SOLID or one of the segmented styles, which suit a water bar well.
• display.scoreboard.title — the label shown above the sidebar panel.

🏜 Water Loss

• default-loss — how much water is lost every cycle anywhere that is not listed as a hot or cold area.
• hot-loss — how much water is lost every cycle in hot areas, such as deserts, badlands, warm oceans and the nether. Hot areas drain about twice as fast by default.
• cold-loss — how much water is lost every cycle in cold areas, such as snowy plains, ice spikes, frozen oceans and frozen peaks. Cold areas drain about half as fast by default.
• hot-biomes and cold-biomes — the lists of areas that use those two rates. Names must match the game's own area names exactly. Any area that is not listed uses the default rate.
• activity-multipliers — how much extra water each activity costs. They stack, so a player who is sprinting while mining loses water faster than one who is only sprinting.
  • default — a multiplier applied to everyone at all times.
  • sprinting, jumping, swimming, mining, fighting — the extra cost of each activity. Setting one to 1.0 makes that activity cost nothing extra, and values above 1.0 make it cost more.

✨ Effects

• notification-radius — how many blocks away a player can be from a furnace or campfire and still see purification messages.
• dirty-water.poison-duration — how long the poison from dirty water lasts, in ticks.
• dirty-water.poison-strength — how strong that poison is, where 0 is the weakest level.
• dehydration.damage-amount — how much damage is dealt each time a player with no water is hurt, where 2 equals one heart.
• dehydration.damage-interval-ticks — how often that damage is dealt, in ticks.
• dehydration.death-message — the message shown when a player dies of dehydration. Use %player% for the name, colour codes with &, or leave it empty to hide the message entirely.
• low-water.slowness-type — the effect applied when water drops to the critical level. Any potion effect name works, such as SLOWNESS, WEAKNESS or MINING_FATIGUE. This is only used while the custom effects below are disabled.
• low-water.slowness-duration — how long that effect lasts, in ticks.
• low-water.slowness-amplifier — how strong that effect is, where 0 is the weakest level.
• custom-effects.enabled — turns the custom effect lists on. When enabled, they are used instead of the slowness settings above.
• custom-effects.low — the effects applied at the warning level. Each entry needs an effect name, a duration in ticks and a strength.
• custom-effects.critical-low — the effects applied at the critical level. These replace the "low" effects once a player drops this far.

🥤 Waterskin

• max-charges — how many drinks a full waterskin holds. A larger number makes it a much stronger survival tool, and also changes how many charges can be carried over during purification.
• purification-time-ticks — how long a dirty waterskin takes to purify on a campfire.

🌧 Cauldron

• fill-rate-ticks — how often the server checks nearby cauldrons during rain.
• fill-chance — the chance that an eligible cauldron gains one water level each check, where 0.25 means a quarter of the time.
• scan-radius — how far around each online player cauldrons are checked. A larger radius covers more ground but costs more to check, so keep it modest on busy servers.

---

🧾 Commands

Command	What it does
/water check	Shows your own water level and the maximum.
/water check <player>	Shows another player's water level.
/water give <clean|dirty|waterskin>	Gives you a clean water bottle, a dirty water bottle, or an empty waterskin.
/water set <player> <amount>	Sets a player's water level to an exact amount.
/water add <player> <amount>	Adds water to a player. A negative amount takes water away.
/water reset <player>	Returns a player to the starting water level.
/water reload	Reloads all settings, the area rates, the water bar and the recipes without restarting the server.
/water help	Shows the commands you are allowed to use.

Every command can be completed with tab, so command names, item names and player names fill in as you type. Admin commands also work from the server console, except the give command, which needs a player to receive the item.

Values given to set, add and reset are always kept inside the valid range, so nobody can be pushed above the maximum or below zero.

🔑 Permissions

Permission	Gives access to	Default
thirstbar.use	Checking your own water level and using the help command.	Everyone
thirstbar.admin	The give, set, add and reset commands, and checking other players.	Operators
thirstbar.reload	The reload command.	Operators

🔗 Placeholders

With PlaceholderAPI installed, these values are available anywhere placeholders are supported, such as scoreboards, chat or tab lists:

• %thirstbar_water_level% — the player's water level as a whole number, for example 87.
• %thirstbar_water_level_formatted% — the same level with one decimal place, for example 87.3.
• %thirstbar_water_percentage% — the level as a percentage of the maximum.
• %thirstbar_water_bar% — a ready-made visual bar using the symbols and colours set in the configuration, so it always matches what players see on screen.

---

🧪 Items and Crafting

Dirty Water Bottle

A glass bottle of murky water. Drinking it restores a small amount of water but poisons the player, so it is best purified first.

• Crafting: a glass bottle with a piece of dirt, in any arrangement.

Clean Water Bottle

Safe, refreshing water that restores a large amount of water with no side effects.

• Obtained by: purifying dirty water, collecting water from a rainwater cauldron, or the small chance when bottling any other water source.

Waterskin

A reusable container that holds several drinks at once, saving precious inventory space. It glows so it stands out, and its description always shows how many charges are left or that it is empty.

• Crafting: leather, string and a glass bottle in a "U" shape around the middle:

L S L
S G S
L S L

(L = Leather, S = String, G = Glass Bottle)

• Filling: right-click a water source with an empty waterskin to fill it. Filled waterskins always contain dirty water, so they need purifying before they are safe to drink.
• Drinking: right-click with a charged waterskin to take a drink. Each drink uses one charge, and the description updates immediately.

🔥 Purifying Water

Dirty water and dirty waterskins become clean in two ways:

• Furnace — smelt them like any other item.
• Campfire — cook them on a campfire.

A dirty waterskin keeps exactly as many charges as it had, so nothing is wasted and nothing is gained. Nearby players see a short message when purification starts and finishes, and how far that message reaches can be set in the configuration.

🌧 Rainwater Cauldrons

Cauldrons left out in the rain slowly collect clean water, one level at a time, but only while it is actually raining and only when they have a clear view of the sky. Water taken from a filled cauldron with a bottle or an empty waterskin lowers it by one level, so cauldrons are a renewable supply of clean water for anyone patient enough to wait for rain.

💾 Player Data and Updating

• Water levels are remembered between sessions and are saved regularly while the server runs, as well as when players log out and when the server stops, so nothing is lost in a crash.
• Players are only tracked while they are online, so large servers do not build up idle data over time.
• When updating from an older version, new options are added to the plugin but an existing settings file will not contain them. The console reports any missing options with a warning, and the built-in defaults keep everything working in the meantime. Copying the new options from a fresh settings file into your own is the recommended way to pick them up.