WaterloggedHoppers

# WaterloggedHoppers - Explosion-Proof Your Hoppers!

**Protect your precious hoppers from creepers and TNT with realistic waterlogging mechanics!**

[](https://www.minecraft.net/)
[](https://papermc.io/)
[](https://opensource.org/licenses/MIT)

---

## Overview

WaterloggedHoppers brings realistic hopper protection to your Minecraft server! Just like how you can waterlog stairs and slabs, you can now waterlog hoppers to make them explosion-resistant. Perfect for protecting your item sorting systems, mob farms, and automated storage from those pesky creepers!

### ✨ Key Features

- ️ **Explosion Protection** - Waterlogged hoppers survive creeper and TNT explosions
- **Realistic Mechanics** - Uses actual water buckets to waterlog/unwaterlog
- **Simple Controls** - Sneak + right-click with a water bucket
- **Reversible** - Remove water with an empty bucket to make hoppers destroyable again
- **Water Placement** - Breaking a waterlogged hopper leaves a water source block
- **Intuitive Feedback** - Clear action bar messages for all interactions
- ⚡ **Lightweight** - Optimized for performance on busy servers

---

## How to Use

### Waterlogging a Hopper (Protect)

1. **Hold a Water Bucket** in your main hand
2. **Sneak** (hold Shift)
3. **Right-click** the hopper
4. ✅ Hopper is now protected from explosions!

*You'll see: `Hopper waterlogged and protected!`*

### Removing Water (Unprotect)

1. **Hold an Empty Bucket** in your main hand
2. **Sneak** (hold Shift)
3. **Right-click** the waterlogged hopper
4. ✅ Water removed, hopper is now vulnerable again!

*You'll see: `Water removed from hopper!`*

### Breaking a Waterlogged Hopper

When you break a waterlogged hopper, it drops as a normal hopper item **and** leaves behind a water source block at that location - just like breaking a waterlogged block in vanilla Minecraft!

---

## Installation

### Requirements
- **Minecraft Version:** 1.21.1
- **Server Software:** Paper MC (or Paper-based forks like Purpur, Pufferfish)
- **Java Version:** 17 or higher

### Steps

1. Download the latest `WaterloggedHoppers.jar` file
2. Place it in your server's `plugins` folder
3. Restart your server
4. Done! No configuration needed!

---

## Use Cases

### Perfect For:

- **Item Sorting Systems** - Protect your complex redstone contraptions
- **Mob Farms** - Keep your collection hoppers safe from creeper raids
- **Base Defense** - Prevent griefing in faction/survival servers
- **Storage Systems** - Safeguard automated storage networks
- **Minigame Arenas** - Protect server infrastructure from TNT cannons

---

## ⚙️ Technical Details

### What Gets Protected?
- ✅ Creeper explosions
- ✅ TNT explosions
- ❌ Player breaking (normal behavior)
- ❌ Other explosion types (can be modified if needed)

### Data Storage
Protection status is stored using **Persistent Data Containers** (PDC), meaning:
- No external database required
- Protection persists through server restarts
- Data is tied to the hopper block itself
- Automatically cleaned up when hopper is destroyed

### Performance
- Minimal memory footprint
- No tick-based operations
- Event-driven architecture
- Cooldown system prevents spam
- Optimized for servers with 100+ players

---

## Troubleshooting

### "Nothing happens when I right-click!"
- ✅ Make sure you're **sneaking** (holding Shift)
- ✅ Check you're using the correct bucket (water bucket to protect, empty to unprotect)
- ✅ Verify you're clicking with your **main hand**

### "My hopper still exploded!"
- ⚠️ Was it waterlogged? Check by trying to remove water with an empty bucket
- ⚠️ Some explosion types might not be covered - this protects against creepers and TNT only

### "The plugin isn't loading!"
- ✅ Confirm you're running Paper MC 1.21.1 or compatible fork
- ✅ Check server console for error messages
- ✅ Verify Java 17+ is installed

---

## ️ For Server Owners

### Permissions
Currently, this plugin has **no permission nodes** - all players can waterlog hoppers. If you need permission restrictions, please request this feature!

### Commands
No commands needed! This plugin is purely interaction-based for simplicity.

### Compatibility
- ✅ Works with most protection plugins (WorldGuard, GriefPrevention, etc.)
- ✅ Compatible with hopper-related plugins
- ✅ No known conflicts with major plugins

---

## Performance Tips for Large Servers

For servers with 200+ concurrent players:

1. Monitor the plugin's performance using Timings/Spark
2. Consider limiting the number of waterlogged hoppers per chunk (future feature) [added for this new patch]
3. The plugin auto-cleans cooldown data every 5 minutes

---

## Support & Feedback

Found a bug? Have a feature request? Want to contribute?

- Contact: * [email protected]*
- Suggest features: * [email protected]*
- ⭐ Rate & review if you love it!