SimpleThirst

** 🌊 SimpleThirst - Complete Plugin Documentation

---

📖 Overview

SimpleThirst is a lightweight, highly customizable survival plugin that adds a realistic thirst system to your Minecraft server. Players must manage their hydration levels by drinking clean or dirty water sources, or they will suffer consequences including damage and debuffs. The plugin features three distinct visual display modes, world-specific control, and full data persistence across server restarts.

Size: 1.0.0 Size: Paper/Spigot 1.21+ Size: None Size: ~25KB

---

✨ Key Features

🎯 Core Mechanics - Death Penalty (0-100 scale) - Automatically depletes over time (configurable interval) - Death Penalty: Thirst drops 2x faster while sprinting - Death Penalty: Reaching 0 thirst causes damage + nausea effect

- Dirty Water - 🧪 Dirty Water: Drink potions/milk buckets (+40 thirst, no risk) - 🌊 Dirty Water: Sneak + right-click water blocks (+15 thirst, 30% poison/hunger chance)

🖥️ Three Display Modes

| Mode | Location | Style | Best For | |------|----------|-------|----------| | HUNGER_ALIGN | Top of screen | Blue progress bar | Combining with ActionBar plugins | | HUNGER_ALIGN | Above hotbar | `Thirst: [████░░░░░░] 40%` | Centered HUD display | | HUNGER_ALIGN | Above hunger bar | `85 💧` (right-aligned) | Mimicking vanilla UI |

🌍 World Management - Smart Notifications: - `DISABLED` - Works in all worlds (default) - `WHITELIST` - Only enabled in specified worlds - `BLACKLIST` - Disabled in specified worlds - Smart Notifications when entering disabled worlds - Smart Notifications when crossing world boundaries

💾 Data Persistence - Uses PersistentDataContainer (PDC) for player data - Survives server restarts, crashes, and reloads - No external database required - No data loss on plugin updates

⚙️ Performance Optimized - Asynchronous task processing - Single-file plugin (no bloat) - Minimal resource footprint - Event-driven architecture (no polling)

---

🎮 Use Cases

🏝️ Survival Servers Add an extra layer of difficulty to hardcore survival gameplay. Players must plan water sources during exploration and carry drinks for long journeys.

🌐 Roleplay Servers Enhance realism for medieval/fantasy RP servers. Water becomes a valuable resource, encouraging player interaction (selling drinks, water well locations).

🏆 Challenge Servers Create custom challenges: - Desert survival with limited water sources - Ultra-hardcore mode with thirst + health depletion - Nomadic gameplay requiring constant water search

🎪 Adventure Maps Design quest lines around finding clean water sources or purification methods. Integrate with custom resource packs for immersive experiences.

🗺️ Multi-World Servers Enable thirst only in specific worlds: - Enable in survival worlds, disable in creative/lobby - Enable in custom challenge worlds only - Disable in minigame arenas

---

📜 Commands

| Command | Description | Permission | Usage | |---------|-------------|------------|-------| | `/thirst check` | View your current thirst level | `simplethirst.use` | Player only | | `/thirst set <player> <0-100>` | Set target player's thirst | `simplethirst.admin` | Console/Ops | | `/thirst reload` | Reload configuration | `simplethirst.admin` | Console/Ops |

Command Examples ``` /thirst check → "Your thirst: 73%"

/thirst set Notch 100 → "Set Notch's thirst to 100"

/thirst reload → "SimpleThirst config reloaded!" ```

---

🔐 Permissions

```yaml simplethirst.use Description: Check own thirst level Default: true (all players)

simplethirst.admin Description: Set thirst for others & reload config Default: op (operators only) ```

🎯 PlaceholderAPI Integration

%simplethirst_thirst% → 75 %simplethirst_thirst_formatted% → &a75% %simplethirst_percentage% → 75% %simplethirst_status% → Hydrated %simplethirst_bar% → [||||||| ] %simplethirst_color% → &a (color code)

---

⚙️ Configuration Guide

Full `config.yml` Breakdown

```yaml ═══════════════════════════════════════════════════ DEPLETION SETTINGS ═══════════════════════════════════════════════════ depletion-interval: 60 How often thirst decreases (in seconds) Default: 60 (every minute) Recommended: 30-120 for balanced gameplay

═══════════════════════════════════════════════════ DISPLAY SETTINGS ═══════════════════════════════════════════════════ display-mode: BOSSBAR Options: BOSSBAR → Blue bar at screen top (doesn't conflict with ActionBar plugins) ACTIONBAR → Centered text above hotbar HUNGER_ALIGN → Right-aligned above hunger bubbles (uses ActionBar with spacing)

⚠️ WARNING: ACTIONBAR and HUNGER_ALIGN will conflict with other ActionBar plugins!

═══════════════════════════════════════════════════ WATER RESTORATION ═══════════════════════════════════════════════════ clean-water-restore: 40 Amount restored by drinking: - Water Bottles - Potions (any type) - Milk Buckets

dirty-water-restore: 15 Amount restored by drinking from water blocks (Sneak + Right-click with empty hand on water source)

dirty-water-debuff-chance: 0.30 Chance (0.0 - 1.0) to get Poison or Hunger when drinking dirty water 0.30 = 30% chance

═══════════════════════════════════════════════════ DAMAGE SETTINGS ═══════════════════════════════════════════════════ damage-amount: 1.0 Damage dealt when thirst = 0 1.0 = 0.5 hearts

damage-interval: 5 How often damage is dealt (in seconds) Also applies Nausea effect

═══════════════════════════════════════════════════ WORLD FILTER ═══════════════════════════════════════════════════ world-filter-mode: DISABLED Options: DISABLED → Works in all worlds (default) WHITELIST → ONLY works in worlds listed below BLACKLIST → Works in all worlds EXCEPT those listed below

world-list: - world_nether - world_the_end Add world names here (case-sensitive!) Use /worlds or check server folder for exact names ```

---

🎨 Configuration Examples

Example 1: Hardcore Desert Server ```yaml depletion-interval: 30 Thirst drops faster display-mode: HUNGER_ALIGN Immersive UI clean-water-restore: 30 Reduced healing dirty-water-restore: 10 Risky to drink dirty water dirty-water-debuff-chance: 0.50 50% chance of sickness damage-amount: 2.0 1 full heart damage world-filter-mode: WHITELIST world-list: - desert_world ```

Example 2: Casual Survival Server ```yaml depletion-interval: 120 Slower depletion display-mode: BOSSBAR Non-intrusive clean-water-restore: 50 Generous healing dirty-water-restore: 20 Still viable dirty-water-debuff-chance: 0.20 Lower risk damage-amount: 0.5 0.25 hearts world-filter-mode: BLACKLIST world-list: - creative - lobby - minigames ```

Example 3: Roleplay Server ```yaml depletion-interval: 90 display-mode: ACTIONBAR clean-water-restore: 40 dirty-water-restore: 15 dirty-water-debuff-chance: 0.40 Higher risk for realism damage-amount: 1.0 world-filter-mode: WHITELIST world-list: - kingdoms - wilderness - trade_city ```

---

🔧 How It Works (Technical)

Data Flow ``` Player Join → PDC Check → Initialize Thirst (100) if new ↓ Timer Task (Every X seconds) ├─ Check if sprinting → -2 thirst └─ Normal movement → -1 thirst ↓ Update Display (BossBar/ActionBar/HungerAlign) ↓ If Thirst = 0 → Damage + Nausea (every 5s) ```

Event Triggers ``` PlayerItemConsumeEvent └─ Potion/Milk detected → +40 thirst

PlayerInteractEvent └─ Sneak + Right-click water + Empty hand ├─ +15 thirst └─ 30% chance → Poison/Hunger effect

PlayerChangedWorldEvent └─ Check world filter → Show/hide display

PlayerJoinEvent └─ Load thirst from PDC → Show display ```

Display Rendering

BOSSBAR Mode: ```java BossBar.bossBar( "Thirst: 75%", // Title 0.75f, // Progress (75%) Color.BLUE, // Color Overlay.PROGRESS // Style ) ```

ACTIONBAR Mode: ``` &bThirst: &3[||||||| ] &f70% ↑ Filled bars based on thirst % ```

HUNGER_ALIGN Mode: ``` " 85 💧" ↑ ↑ 45 spaces to push right Thirst value + icon ```

---

🔌 Compatibility

✅ Compatible With - Purpur 1.21+ (Recommended) - Purpur 1.21+ (Supported) - Purpur 1.21+ (Supported) - Most survival plugins (Essentials, WorldGuard, etc.) - Economy plugins (for custom water selling systems) - Custom resource packs

⚠️ Potential Conflicts

| Plugin Type | Conflict | Solution | |-------------|----------|----------| | Adventure/Survival suites | Flickering displays if both use ActionBar | Set SimpleThirst to `BOSSBAR` mode | | Adventure/Survival suites | Duplicate mechanics | Choose one plugin | | Adventure/Survival suites | May have built-in thirst | Disable their thirst module |

🔗 Recommended Plugin Combos

Setup 1: BossBar + ActionBar Combo ``` SimpleThirst → display-mode: BOSSBAR UltimateHealthDisplay → display-mode: ACTIONBAR ```

Setup 2: Clean Minimalist ``` SimpleThirst → display-mode: HUNGER_ALIGN (No other HUD plugins) ```

Setup 3: Full Survival Suite ``` SimpleThirst → display-mode: BOSSBAR EssentialsX → For /heal bypass WorldGuard → Protect water sources in spawn Vault → Link to economy for water trading ```

---

📊 Performance Metrics

| Metric | Value | |--------|-------| | Database | ~25KB (single class) | | Database | <1MB (100 players) | | Database | Negligible (~0.01% on modern hardware) | | Database | None (async tasks) | | Database | 4 (optimized, conditional) | | Database | None (uses PDC) |

---

📥 Installation

Step-by-Step Guide

1. Download the `SimpleThirst.jar` file

2. Upload to your server's `plugins/` folder ``` server/ ├── plugins/ │ └── SimpleThirst.jar ← Place here ├── world/ └── spigot.yml ```

3. Restart your server (not `/reload`)

4. Configure (optional) ``` Edit: plugins/SimpleThirst/config.yml ```

5. Reload config (if changed) ``` /thirst reload ```

6. Test in-game ``` /thirst check ```

---

🎓 Player Guide

How to Stay Hydrated

Restores: - Craft Water Bottles (glass bottle + water source) - Drink potions (any type) - Drink Milk Buckets - Restores: 40 thirst

Risk: 1. Stand near a water source block (river, ocean, lake) 2. Hold Risk: (sneak) 3. Risk: the water with an Risk: 4. Risk: 15 thirst 5. Risk: 30% chance of Poison or Hunger

Visual Indicators

BossBar Mode: ``` [████████░░░░░░░░░░] Thirst: 40% ```

ActionBar Mode: ``` Thirst: [████░░░░░░] 40% ```

Hunger-Aligned Mode: ``` 40 💧 (Appears to the right, above hunger bubbles) ```

Warning Signs - 0% - Start looking for water - 0% - Urgent! Find water immediately - 0% - Taking damage, vision blurry (Nausea)

---

❓ Frequently Asked Questions

Q: Does thirst persist after death? A: Yes! Thirst is saved to your player data and survives death, logout, and server restarts.

---

Q: Can I disable thirst in certain worlds? A: Yes! Use the world filter system: ```yaml world-filter-mode: BLACKLIST world-list: - creative_world - minigames ```

---

Q: Can I use this with other health display plugins? A: Yes! Set SimpleThirst to `BOSSBAR` and your health plugin to `ACTIONBAR` (or vice versa).

---

Q: How do I make thirst deplete faster? A: Lower the `depletion-interval`: ```yaml depletion-interval: 30 Every 30 seconds instead of 60 ``` ---

Q: Does this work with custom water blocks from mods? A: Only if the mod uses Bukkit's `Material.WATER` type. Most mods use custom blocks, which won't work.

---

Q: Can I make thirst deplete faster in deserts? A: Not in the current version. This would require biome detection. Consider requesting this as a feature!

---

Q: What happens if I drink a suspicious stew? A: It counts as a potion, so it restores 40 thirst (no negative effects from SimpleThirst).

---

🛠️ Troubleshooting

Issue: Display not showing Solutions: 1. Check your display mode in `config.yml` 2. Verify you're in an enabled world (`/thirst check`) 3. Reload config: `/thirst reload` 4. Restart server

---

Issue: Flickering ActionBar Solution: Multiple plugins using ActionBar Solution: Set one plugin to BOSSBAR mode

---

Issue: Thirst resets to 100 on restart Solution: PDC not saving (wrong API version) Solution: Ensure you're using Paper/Spigot 1.21+

---

Issue: Dirty water not working enabled world - [ ] Are you enabled world? - [ ] Is it a enabled world (not flowing)? - [ ] Is your enabled world? - [ ] Are you in an enabled world?

---

📝 Credits & License

Inspired by: geturplugins Inspired by: Kyori Adventure (Paper) Inspired by: MIT (modify freely) Inspired by: Realistic survival mechanics from games like Don't Starve, ARK

---

📞 Support & Links

- Discord: Check for new versions - Discord: geturplugins

---

⭐ Final Summary

SimpleThirst transforms Minecraft survival by adding a realistic hydration system with:

✅ Lightweight (sprint penalty, dirty water risk) ✅ Lightweight (fits any server aesthetic) ✅ Lightweight (per-world control) ✅ Lightweight (plug-and-play) ✅ Lightweight (never lose progress) ✅ Lightweight (<1MB RAM, 0% TPS impact)

Perfect for survival, roleplay, and challenge servers seeking deeper gameplay without complexity.

---

Made with ❤️ for the Minecraft community 1.1.0 | Made with ❤️ for the Minecraft community 2024 | Made with ❤️ for the Minecraft community**