👑 HyroCosmetics — Advanced 3D Cosmetics Engine

HyroCosmetics is a high-performance, next-generation 3D cosmetics plugin built specifically for modern Paper / Purpur (1.20 - 1.21.x) Minecraft servers. Powered by Minecraft's native Display Entities, it provides butter-smooth 144+ FPS motion tracking without causing server tick lag or trailing delay!

---

✨ Features

🎒 1. Real-Time 3D Motion Tracking

• Smooth Client-Side Tracking: Backpacks, wings, and balloons are dynamically attached with zero trailing lag.
• Natural Sneak & Pose Tilting: Cosmetics dynamically tilt when players sneak or change pitch, matching their body orientation naturally.

🎩 2. Non-Destructive Wearable System

• Players can equip custom 3D hats without losing their armor!
• Netherite, Diamond, and other helmets can still be worn while displaying custom cosmetic models.

👁️ 3. Smart First-Person Anti-Obstruction

• Intelligently detects camera angles and automatically hides bulky wings or hats when looking down or in first-person view.
• Keeps the player's screen 100% clean and unobstructed for PvP, mining, and building.

📦 4. Universal Custom Model Support

• Compatible out-of-the-box with ItemsAdder, Nexo, Oraxen, and standard vanilla CustomModelData.
• Easily configure custom offsets, rotations, scales, and positions for each individual model.

💰 5. Integrated Economy Shop & Vouchers

• Wardrobe Shop: Players can preview and purchase cosmetics using server currency via Vault.
• Physical Vouchers: Convert any cosmetic into a tradeable physical item voucher with persistent NBT/PDC data.
• High-Performance Database: Fast, thread-safe player data storage powered by SQLite and HikariCP connection pooling.

---

🎭 Supported Cosmetic Types

Category	Description
Hats	3D head accessories that sync seamlessly with player pitch and yaw.
Backpacks	Custom backpacks mounted cleanly behind the player with sneak tilt.
Wings	Animated wings placed across the upper shoulder blades.
Balloons	Cute 3D companions floating above and behind the player.
Hand Items	Custom off-hand accessories and floating handheld props.
Trails & Effects	Dynamic particle effects following player steps and movements.

---

⌨️ Commands & Permissions

Command	Permission	Description
/cosmetics	hyrocosmetics.use	Opens the 3D Cosmetics Wardrobe GUI
/cosmetics viewself	hyrocosmetics.use	Toggles 3D cosmetic visibility for first-person / F5
/cosmetics unequip	hyrocosmetics.use	Unequips your current active cosmetic
/cosmetics reload	hyrocosmetics.admin	Reloads all configurations and model caches

Aliases: /hc, /wardrobe, /topi, /cosmetic

---

⚙️ Requirements & Installation

Requirements:

• Server Software: PaperMC or Purpur (1.20 - 1.21.x)
• Java Version: Java 21 or newer
• Optional Dependencies:
  • Vault (Required only if you use economy features)
  • ItemsAdder / Nexo / Oraxen (For custom 3D model packs)

Quick Installation:

1. Download the latest HyroCosmetics.jar from the Versions tab.
2. Place the jar file inside your server's plugins/ folder.
3. Restart your server to generate the configuration files.
4. Customize config.yml to adjust model offsets, messages, and permissions to your liking!