Hat Command

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:

```yaml

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.