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. **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-re