HatPlugin

Turn anything into your hat – instantly.

Made By Pingz0

A lightweight, optimized Paper 1.21+ plugin that lets players wear any item as a helmet with a single command. Built for performance, simplicity, and customization.

---

✨ Features

• 🎯 /hat Command Instantly equip the item in your hand as your helmet

• 🔄 Smart Item Swapping Automatically swaps your current helmet with the item in your hand

• ⏱ Configurable Cooldown Prevent spam with a customizable cooldown system

• 🔊 Custom Sounds Play different sounds for success and failure

• 💬 Fully Customizable Messages Supports color codes (&a, &c, etc.)

• ⚡ Actionbar Feedback Clean, modern UI feedback instead of chat spam

• 🔁 Live Config Reload Reload config instantly with /hat reload

• 🛡 Permission System

  • hat.use → Use /hat
  • hat.reload → Reload config

• 🚀 Lightweight & Optimized No unnecessary listeners, minimal performance impact

---

📦 Installation

1. Download the latest release
2. Place the .jar file into your /plugins/ folder
3. Start your server
4. Done ✅

---

⚙️ Configuration

Located at:

/plugins/HatPlugin/config.yml

Example:

# Cooldown between using /hat (seconds)
cooldown: 1

# Message on success
message: "&aNow wearing your item as a hat!"

# Message on failure (no item in hand)
failmessage: "&cYou need to hold an item!"

# Sound on failure
failsound: "ENTITY.VILLAGER.NO"

# Sound on success
sound: "ITEM_ARMOR_EQUIP_GENERIC"

---

📜 Commands

Command	Description	Permission
/hat	Equip item as helmet	hat.use
/hat reload	Reload config	hat.reload

---

🔐 Permissions

Permission	Default	Description
hat.use	true	Use the /hat command
hat.reload	op	Reload the config

---

🎮 How it works

• Hold any item in your hand
• Run /hat
• Your item becomes your helmet
• If you already have a helmet → it swaps automatically

---

⚡ Compatibility

• ✅ Paper 1.21+
• ❌ Spigot (not recommended)
• ❌ Bukkit (not supported)

---

🧠 Technical Notes

• Uses Paper API for best performance
• Safe sound parsing (prevents crashes from invalid config values)
• Optimized cooldown handling per player
• Clean code structure for easy expansion

---

🔥 Planned Features

• Blacklist certain items (e.g. shulker boxes)
• Per-world settings
• GUI-based hat selector
• Particle effects

---

💬 Support

If you find bugs or want new features:

• Open an issue
• Or contact the developer

---

📄 License

This project is licensed under the MIT License.