RoyItems

First Version 🌟 RoyItems v2026.1 — Initial Release

Welcome to the inaugural release of RoyItems, a next-generation MMORPG Custom Items & Stats engine engineered for Paper, Spigot, and Folia (Minecraft 1.21+ / 26.2+).

---

✨ Highlights & Core Features

⚔️ 16 Custom Stats & MMORPG Defense Engine

• Full Stat Spectrum: Added support for 16 custom MMORPG stats (attack-damage, defense, pve-defense, pvp-damage, critical-rate, critical-damage, lifesteal, armor-penetration, damage-reduction, cooldown-reduction, mana, etc.) alongside Vanilla attributes.
• Unified Math Formula: Calculated as Total = (Base + Flat) * (1 + Percent) with seamless raw number or percentage input.
• 3 Independent Defense Modes:
  • SIMPLE: Flat damage reduction with configurable floor damage.
  • MMORPG: Non-linear diminishing returns curve (Damage * scale / (scale + Defense)).
  • CUSTOM_LIMIT: Flat reduction bounded by hard minimum and maximum damage clamps.

📜 Dynamic Lore Formatting Engine

• Per-Stat Placeholders: Supports individual tags (e.g. #attack-damage#, #defense#) or aggregate #stats#.
• Smart Pruning: Lines containing missing or 0 stats disappear automatically without leaving dangling symbols or blank lines.
• Smart Divider #bar#: Automatically cleans up consecutive or trailing separator lines.
• Anti-Italic by Default: Eliminates unwanted Minecraft italics across item names, lore, and GUI text while honoring intentional <i> or &o formatting.
• Full Color Support: Adventure MiniMessage gradients (<gradient:...>), Hex colors (<#RRGGBB>), and legacy codes (&a, &c).

🔄 LiveUpdate Synchronization Engine

• Zero-Wipe Hot Reload: Updating items in item/<TYPE>.yml or running /ri reload instantly updates existing items in online player inventories and ender chests.
• Data Preservation: Retains socketed gems, active cooldowns, durability, and custom NBT/PDC.
• Sync Telemetry: Detailed synchronization reports sent to the sender and server console.

🖥️ Ingame GUI Editor

• Paginated MMOItems-Style Interface: Intuitive category browsing and multi-page property editing.
• Granular Stat Control: Dedicated editing buttons for every single stat, requirement, and attribute.
• Safe Chat Inputs: Color-coded prompts with regex validation, cancellation keywords (cancel, exit), and concurrent edit session locks.

💎 Gem Sockets, Sets, Tiers & Requirements

• Interactive Gem Socketing: Drag-and-drop gem placement with socket compatibility checks (Universal 1, Roman tiers, etc.).
• Tiers & Set Bonuses: Tier-colored borders and set completion attribute boosts.
• Item Requirements: Enforces Level, Class (MMOCore / AuraSkills), and Permissions before wielding.
• Item Expiration & Cooldowns: Real-time expiration dates and per-item ability cooldowns.

⚙️ Maintenance, Migration & Notifications

• Automated Config Migrator: Automatically compares config-version: 1 across config.yml, lang/message.yml, and gui/editor-gui.yml. Backs up outdated files (.bak) and recursively merges new keys without altering user values.
• Built-in Lore Wiki (lore-format/_example.yml): Authoritative documentation file listing all placeholders, custom stats, and syntax. Auto-restored if deleted; protected against unauthorized in-game usage.
• Admin-Only Update Checker: Asynchronous release alerts for Server Operators / royitems.admin on join and reload.
• bStats Telemetry: Integrated bStats metric tracking (Plugin ID: 34832).

---

📦 Platform & Compatibility

• Server Software: Paper, Spigot, Folia (Native multi-threaded region scheduler).
• Minecraft Version: 1.21.x – 26.2+
• Java Runtime: Java 21+
• Soft Dependencies: MMOCore, AuraSkills, Vault, PlaceholderAPI...