KuhArmorTrimGUI

A GUI-based armor trim unlocking, purchasing, and progression system for Minecraft servers.

Give your players full control over their armor's appearance with an intuitive in-game GUI. Players can browse armor types, unlock trim patterns and materials, purchase cosmetics with in-game currency, and automatically apply their selected trims.

Server admins get full control over pricing, unlock requirements, season passes, protection rules, and customization — all through configuration files and commands.

• Compatibility: Paper 1.21.9+ and Folia
• Economy: Optional Vault integration
• Permissions: Optional LuckPerms integration
• Storage: Local YAML files — no database required

---

How It Works

1. Open the GUI — Players use /armortrims or /armtrm to access the menu.
2. Choose your style — Browse armor pieces, trim patterns, and trim materials.
3. Unlock or purchase — Unlock content through progression, admin grants, permissions, or in-game currency.
4. Confirm your selection — A confirmation screen displays the selected items, unlock status, and price.
5. Apply your trims — The plugin applies the selected appearance when the required conditions are met.
6. Keep your progress — Unlocks and selections persist across relogs and server restarts.
7. Manage seasons — Server admins can configure seasonal content, exclusive unlocks, and time-limited season passes.

---

Features

GUI & Customization

• Clean, multi-page GUI for browsing armor pieces, trim patterns, and trim materials.
• Purchase confirmation screens with item previews, unlock status, and pricing.
• Progress screen showing unlocked and total counts, active seasons, and pass status.
• Clear trims directly through the GUI.
• Configurable GUI layout, item order, page size, sounds, and messages.

Unlocks & Progression

• Unlock individual armor pieces, trim patterns, and trim materials.
• Configure separate prices for armor types, armor pieces, trim patterns, trim materials, and season passes.
• Grant individual unlocks or everything at once through admin commands.
• Support for permission-based unlocks.
• Automatically apply selected trims on player join and inventory changes.
• Persistent unlocks and selections across relogs and server restarts.

Season Passes

• Create unlimited custom seasons with individual settings.
• Configure prices, durations, and start delays.
• Offer exclusive content through season-specific unlocks.
• Automatically expire passes after their configured duration.
• Configure unlocks by category, including wildcard support.

Trim Protection

• Block manual armor trim changes at smithing tables.
• Sanitize armor on pickup, drop, death, and supported container interactions.
• Configure protection rules individually.
• Enforce unlock requirements and restore selected appearances through auto-apply.

Economy & Permissions

• Vault Economy (optional): Charge players using their server's economy.
• LuckPerms (optional): Mirror unlocks into permission nodes for easier management.
• Standalone mode: The plugin works without either dependency.

Fully Configurable

• Customize every message and GUI text through messages.yml.
• Adjust prices through prices.yml.
• Configure seasons in seasons.yml.
• Control unlock requirements, protection rules, sounds, and display order.
• Run on Folia with region-safe scheduling.

---

Dependencies

Plugin	Purpose	Required
Vault	Economy integration	No
LuckPerms	Permission synchronization	No

Neither dependency is required. Without Vault, economy features are disabled. Without LuckPerms, unlock data is managed by KuhArmorTrimGUI itself.

---

Commands

Command	Description
/armortrims	Open the armor trim GUI
/armortrims reload	Reload the configuration
/armortrims info <player>	View a player's unlocks and selections
/armortrims unlock <player> piece <armor> <piece>	Unlock an armor piece
/armortrims unlock <player> trim <id>	Unlock a trim pattern
/armortrims unlock <player> material <id>	Unlock a trim material
/armortrims unlock <player> all	Unlock everything
/armortrims lock <player> <type> <id>	Remove a specific unlock
/armortrims lock <player> all	Remove all unlocks
/armortrims givepass <player> <season>	Give a season pass
/armortrims removepass <player> <season>	Remove a season pass

Command alias: /armtrm

---

Permissions

Permission	Default	Description
kuharmortrgui.use	true	Open the GUI
kuharmortrgui.admin	op	Access admin commands
kuharmortrgui.reload	op	Reload the configuration
kuharmortrgui.admin.unlock	op	Manage unlocks
kuharmortrgui.admin.lock	op	Remove unlocks
kuharmortrgui.admin.givepass	op	Grant season passes
kuharmortrgui.admin.removepass	op	Remove season passes
kuharmortrgui.admin.info	op	View player information
kuharmortrgui.unlock.trim.<id>	false	Permission-based trim unlock
kuharmortrgui.unlock.trim-material.<id>	false	Permission-based trim material unlock
kuharmortrgui.unlock.piece.<armor>.<piece>	false	Permission-based armor piece unlock
kuharmortrgui.season.<season>	false	Season-specific access

---

Default Pricing

All prices can be customized in prices.yml.

Category	Default Price Range
Armor materials	0–25,000 coins
Armor pieces	0–5,000 coins
Trim patterns	1,000–1,750 coins
Trim materials	500–3,000 coins
Season pass	45,000 coins

The currency name and individual prices are configurable.

---

Supported Content

Armor Types

7 armor types:

• Leather
• Chainmail
• Copper
• Iron
• Gold
• Diamond
• Netherite

Trim Patterns

18 supported patterns:

Sentry · Dune · Coast · Wild · Ward · Eye · Vex · Tide · Snout · Rib · Wayfinder · Shaper · Host · Raiser · Flow · Bolt · Silence · Spire

Trim Materials

11 supported materials:

Iron · Gold · Diamond · Lapis · Emerald · Netherite · Redstone · Amethyst · Quartz · Copper · Resin

---

Configuration

All settings can be customized without modifying the source code.

config.yml

• Enable or disable economy integration and set the currency name.
• Choose which unlock categories are required.
• Customize armor and trim material display order.
• Configure season pass pricing and duration.
• Enable or disable protection rules.
• Configure auto-apply behavior.
• Customize GUI page size, confirmation screens, and save behavior.

seasons.yml

• Create unlimited seasons with custom display names.
• Set season durations and start delays.
• Define season-specific unlocks by category.
• Use wildcards for bulk unlock rules.
• Enable or disable individual passes and set their prices.

prices.yml

• Configure prices for armor types and pieces.
• Set individual trim pattern and trim material prices.
• Set season pass prices.

messages.yml

• Customize all chat messages and GUI text.
• Configure purchase, unlock, selection, and error messages.
• Use color codes with the & prefix.
• Customize sounds for purchases, unlocks, errors, GUI interactions, resets, and season events.

---

Storage

Player data is stored locally as YAML files in:

plugins/KuhArmorTrimGUI/data/

No external database is required.

Data is saved when:

• A player quits.
• The plugin reloads.
• An unlock, lock, or purchase operation occurs.

---

Support & Feedback

Found a bug or have a suggestion?

Join the Discord and open a ticket <3.