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.