🌊 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.

**Version:** 1.0.0
**API:** Paper/Spigot 1.21+
**Dependencies:** None
**Size:** ~25KB

---

✨ Key Features

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

- **Two Water Sources**
- 🧪 **Clean 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 |
|------|----------|-------|----------|
| **BOSSBAR** | Top of screen | Blue progress bar | Combining with ActionBar plugins |
| **ACTIONBAR** | Above hotbar | `Thirst: [████░░░░░░] 40%` | Centered HUD display |
| **HUNGER_ALIGN** | Above hunger bar | `85 💧` (right-aligned) | Mimicking vanilla UI |

🌍 World Management
- **Three Filter Modes**:
- `DISABLED` - Works in all worlds (default)
- `WHITELIST` - Only enabled in specified worlds
- `BLACKLIST` - Disabled in specified worlds
- **Auto-Hide Display** 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
- **Paper 1.21+** (Recommended)
- **Spigot 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 |
|-------------|----------|----------|
| **Other ActionBar plugins** | Flickering displays if both use ActionBar | Set SimpleThirst to `BOSSBAR` mode |
| **Custom thirst plugins** | 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 |
|--------|-------|
| **File Size** | ~25KB (single class) |
| **RAM Usage** | <1MB (100 players) |
| **CPU Impact** | Negligible (~0.01% on modern hardware) |
| **TPS Impact** | None (async tasks) |
| **Event Handlers** | 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

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

**Method 2: Dirty Water (Risky)**
1. Stand near a water source block (river, ocean, lake)
2. Hold **SHIFT** (sneak)
3. **Right-click** the water with an **empty hand**
4. **Restores:** 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
- **Below 30%** - Start looking for water
- **Below 10%** - 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
**Cause:** Multiple plugins using ActionBar
**Solution:** Set one plugin to BOSSBAR mode

---

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

---

Issue: Dirty water not working
**Checklist:**
- [ ] Are you **sneaking**?
- [ ] Is it a **water source block** (not flowing)?
- [ ] Is your **hand empty**?
- [ ] Are you in an **enabled world**?

---

📝 Credits & License

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

---

📞 Support & Links

- **Updates:** Check for new versions
- **Discord:** geturplugins

---

⭐ Final Summary

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

✅ **Smart mechanics** (sprint penalty, dirty water risk)
✅ **3 display modes** (fits any server aesthetic)
✅ **World filtering** (per-world control)
✅ **Zero dependencies** (plug-and-play)
✅ **Persistent data** (never lose progress)
✅ **Lightweight** (<1MB RAM, 0% TPS impact)

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

---

**Version:** 1.1.0 | **Last Updated:** 2024 | Made with ❤️ for the Minecraft community

Need a server to run NoMinecartTnt?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting

SimpleThirstt