⚡ IceAttributes | ❄️ The Ultimate Attribute System

WHAT IS ICE ATTRIBUTES?
IceAttributes is a complete RPG-style upgrade system for your server.
Players earn currency, browse a beautiful in-game shop, and purchase
permanent upgrades that apply real effects to their character:
❤️ Extra hearts. ⚡ Faster attacks. Quicker movement. A bigger body (Scale).
Permanent potion effects. ⭐ Even custom permission perks.
But unlike most "stat shop" plugins, everything in IceAttributes is
driven by plain YAML files. You never touch Java code. As a server owner you
can invent brand-new attributes, mix three different currencies, build
rank-gated premium perks, design your own GUI layouts, and rewrite every
single message — without ever recompiling anything.
[HR][/HR]
THE GAMEPLAY LOOP (How it works)
1. Players open the shop → [/attributes] or [/iceattributes shop]
A categorized, paginated menu shows every attribute you configured. Each item
live-updates its appearance based on the player's state:

• ✅ Available — clickable, shows price & next level
• Owned — glowing, shows current level, upgradeable
• Max Level — fully upgraded, nothing more to buy
• Locked — missing a requirement (shows exactly WHICH one!)
• No Funds — can't afford it right now
• ⛔ Unsupported — needs a newer MC version (e.g. Scale on 1.17)
• ❌ Disabled — admin temporarily turned it off

2. They click an attribute
An optional confirmation menu opens first: current level → new level, price,
currency, everything shown before a single coin is spent.
3. Validation runs (in this exact order):
enabled → version support → permission → requirements → currency →
purchase limit → max level → cancellable AttributePurchaseEvent.
If anything fails, the player is told exactly why — and
zero currency is touched.
4. Payment is withdrawn, purchase is saved
The database write is transactional. If the save fails (disk error,
shutdown race), the money is automatically refunded — a failed
purchase can never eat a player's money.
5. The effect applies instantly
Modifier is attached (stable UUID — never duplicated on rejoin), a
configurable sound + title + action bar + particle burst plays , the GUI
refreshes, and the purchase is written into history.
6. They show off ️
Selected attributes appear on their public Profile GUI, and can be announced
in chat with hover text. Players love flexing max-level upgrades!
[HR][/HR]
⚔️ THE ATTRIBUTE SYSTEM
Supported built-in types:

• ❤️ MAX_HEALTH — bonus hearts (extra hearts render automatically)
• MOVEMENT_SPEED — permanent speed bonus
• ⚔️ ATTACK_DAMAGE — melee damage
• ️ ATTACK_SPEED — swing speed
• ️ ARMOR & ARMOR_TOUGHNESS — damage reduction
• KNOCKBACK_RESISTANCE — tank those punches
• LUCK — loot table luck
• FOLLOW_RANGE — mob aggro range
• SCALE — player size (requires MC 1.20.5+, safely skipped below)
• JUMP_STRENGTH — jump height (requires MC 1.20.5+)
• POTION_EFFECT — ANY permanent potion effect (Haste, Speed, Night Vision...)
• ⭐ PERMISSION — grants a permission node while owned
• ️ CUSTOM — register your own handler via the API!
  
  
  
  
  
  
  

Every attribute definition supports:

• Unique ID, display name, description (MiniMessage)
• Attribute type + operation (ADD_NUMBER / ADD_SCALAR / MULTIPLY_SCALAR_1)
• Flat value or level progression (initial value, increment, max level)
• Price + currency (Vault / PlayerPoints / Premium Coin)
• Purchase permission + purchase limits + repeatable flag
• Required previous attribute (unlock trees! )
• Timed expiration (rent attributes for X seconds!)
• Custom GUI item: material, name, lore, glow, custom model data, item flags
• Custom purchase sound + effects (title, action bar, particles)
• Category + shop slot ordering
• Profile visibility, icon, display name, sort priority
• Hidden flag, enabled/disabled flag

Example — a VIP-only Scale attribute in 20 lines of YAML:


That's it. The engine is fully generic — admins create content, not code.
[HR][/HR]
THE CURRENCY SYSTEM (3 currencies, zero setup)

• VAULT — hooks into any economy plugin (EssentialsX, CMI, Coins...). Optional & auto-detected.
• PLAYER_POINTS — hooks into PlayerPoints if installed. Optional & auto-detected.
• PREMIUM COIN — built-in currency stored in our own database. Always available.

Premium Coin features:

• Persistent SQLite-backed balances
• Start balance, max balance & negative-balance config options
• Full admin management: [/iceattributes premiumcoins give|take|set]
• Works for offline players too! (data loads on demand)
• Cancellable PremiumCoinChangeEvent for developers
• GUI balance display + PlaceholderAPI placeholder

Every attribute chooses its own currency — build a shop where some
upgrades cost money, some cost points, and the best ones cost Premium Coins!
[HR][/HR]
️ THE REQUIREMENTS ENGINE
Attribute-gating with AND / OR logic. Mix and match:

• permission — requires a permission node
• luckperms-group — requires a LuckPerms group (rank gating!)
• placeholder — PlaceholderAPI condition (equals / contains / regex)
• money — minimum Vault balance
• premium-coins — minimum coin balance
• player-points — minimum points
• ⚔️ attribute — requires another attribute at a level
• world — only purchasable in certain worlds

Every failed requirement shows a customizable, translated message —
players always know exactly what they're missing. No mystery locks. ️
[HR][/HR]
️ THE SHOP GUI (100% configurable)
Built from gui.yml — no hardcoded layout exists anywhere in the plugin.

• Custom titles (MiniMessage, live page numbers: "Shop (2/3)")
• Custom rows (1-6), custom attribute slots with ranges like [10-16, 19-25]
• Unlimited categories with configurable slots & icons
• Pagination with smart previous/next buttons (auto-hide on edges)
• Live balance displays for every available currency
• Decorative items & filler panes at any slot
• Per-state appearance overrides (material/name/lore/glow for each of the 7 states)
• Click sounds, page sounds, purchase & error sounds — all configurable
• Conditional items: hide by config path, permission, or page position
• Dynamic title refresh — page numbers update as players browse!

Every item supports: material, amount, MiniMessage name & lore, glow,
custom model data, item flags, enchantments — with placeholders everywhere.
[HR][/HR]
THE PROFILE SYSTEM
Every player gets a showcase-ready profile: [/profile] or [/profile <player>]

• Player head with stats: total attributes, total levels, featured picks
• Featured attributes pinned to the top with a golden glow
• Owned attributes with levels, values & categories
• Optional purchase history (last N purchases with prices & dates)
• Optional Premium Coin / money balance display

You control privacy — the admin decides what's public:
[HR][/HR]
THE SHOWCASE SYSTEM (Show off!)
Let your players flex their achievements:

• Open [/iceattributes showcase] → click owned attributes to feature them
• Featured attributes glow on the profile, locked ones show as locked
• Configurable maximum slots (default 6)
• [/iceattributes showcase <attribute>] announces in chat with
  hover text showing the attribute details!
• Cancellable AttributeShowcaseChangeEvent for developers
• Chat broadcast mode (configurable) — announce to the whole server!

[HR][/hr]
️ STORAGE & PERFORMANCE (Built for production)

• SQLite storage, 100% async — zero SQL on the main thread
• WAL journal + single DB thread = no "database is locked" errors
• Full transactional saves (players, attributes, showcase, coins, history)
• Cached player data — instant reads, dirty-flag writes
• ⏱️ Configurable auto-save interval (default 5 min) + save on quit & shutdown
• Stable modifier UUIDs — relog never duplicates modifiers
• Memory-safe: attachments cleaned on quit, menus untracked on close
• ️ Driver auto-detection: Paper libraries loader, Spigot's internal driver,
  or a manual libs/ folder — works everywhere
• Repository-based storage layer — MySQL/MariaDB can be added without
  touching business logic

[HR][/HR]
✨ MINIMESSAGE + LANGUAGES
Every message, title, GUI name and lore supports full MiniMessage:

• English and Persian language files included
• Both are comprehensive — 100+ message keys covering every situation
• Switch with one line: language: fa — with safe English fallback
• Persian file is written natively (proper RTL wording), not machine-translated

[HR][/HR]
PLACEHOLDERAPI INTEGRATION
Built-in placeholders (PAPI optional — everything else works without it):
Plus: all plugin messages/GUIs accept any external PAPI placeholder —
use placeholders from other plugins inside our lore, requirements & messages!
[HR][/HR]
ADMIN TOOLKIT
Complete control over every player:

• ✔️ Works on offline players (data loads on demand)
• ✔️ Permission-aware smart tab completion (player names, attribute IDs, categories)
• ✔️ Live effects: online targets get modifiers applied instantly
• ✔️ Safe reload — re-reads YAML & re-applies without kicking anyone

[HR][/HR]
DEVELOPER API
Register your own extensions from any plugin:
Events (all where sensible are cancellable):

• ⚔️ AttributePurchaseEvent — fired before payment; cancel to block
• ⬆️ AttributeUpgradeEvent — fired after success
• ️ AttributeRemoveEvent — fired before removal
• PremiumCoinChangeEvent — fired before balance changes
• ⭐ AttributeShowcaseChangeEvent — fired before showcase changes

[HR][/HR]
INSTALLATION

1. Drop IceAttributes.jar into the plugins/ folder (~1 MB!)
2. Start the server — all config files generate automatically
3. Customize attributes.yml, gui.yml, messages
4. Run /iceattributes reload — done!

Requirements: ✅ Java 17+ ✅ MC 1.17–1.21.x ✅ No hard dependencies
Optional: Vault + economy ✦ PlayerPoints ✦ LuckPerms ✦ PlaceholderAPI
[HR][/HR]
WHAT THE CONFIGS CONTAIN
config.yml — database, language, debug, all currency settings,
premium coin rules, purchase behavior (confirmation, cooldowns, broadcast),
profile privacy, showcase limits, default effects & sounds
attributes.yml — 14 complete example attributes shipped:
Max Health, Movement Speed, Attack Damage, Attack Speed, Armor, Armor
Toughness, Luck, Knockback Resistance, Scale, VIP-only Scale, permanent
Haste & Speed potions, VIP Perks, Jump Strength — covering all three
currencies and every requirement type. Copy → edit → done!
gui.yml — every menu's title, rows, slots, layouts, items, states,
navigation, balance displays, decorations, sounds
langs/en.yml + fa.yml — every player-facing message with MiniMessage
[HR][/HR]
[HR][/HR]