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.