⚔️ RoyItems — Next-Generation MMORPG Custom Items Engine

Empower your Minecraft server with an enterprise-grade MMORPG item system.
Create limitless custom weapons, armor, accessories, consumables, and gems with a dedicated stat engine, non-linear defense formulas, drag-and-drop gem socketing, real-time item expiration, and a sleek paginated in-game GUI editor. Built natively for Minecraft 1.21.4+ with full Folia multi-threading support.

🌟 Why Choose RoyItems?

Crafting a balanced, memorable MMORPG experience requires more than basic lore lines or vanilla attribute modifiers. RoyItems was engineered from the ground up to provide server administrators and game designers with total creative control, bulletproof performance, and seamless administration.

• 🔄 Revolutionary LiveUpdate Engine: Never worry about balance updates again. When you adjust stats in your YAML files and run /ri reload, RoyItems automatically scans online player inventories and ender chests, instantly updating items to the latest version while safely preserving slotted gems, durability, and expiration timers.
• 🛡️ Advanced 3-Mode Defense Engine: Say goodbye to broken armor math. Choose between Simple subtraction, MMORPG diminishing returns (ensuring players with low attack still deal partial damage to high-defense bosses), or Custom Min/Max damage limits.
• 💎 Interactive Drag & Drop Gem Sockets: Players can drop gems directly onto equipment in their inventory to socket them. Define universal sockets (1), specialized sockets (A), or multi-gem sockets (ABC).
• 🖥️ Modern Paginated In-Game GUI Editor (/ri editor): Edit 100% of item properties in-game with intuitive Previous/Next page navigation, real-time live preview, chat input prompts, and anti-italic text enforcement.
• 🧵 Native Folia Multi-Threading Compatibility: Fully compatible with Folia's regionized multi-threaded ticking loop and standard Paper/Spigot pipelines with zero desync or thread contention.
• 📜 Intelligent Dynamic Lore Engine: Clean, modular lore templates with automated #bar# separator cleanup—no awkward double-dividers or trailing blank lines.

⚔️ Key Features in Detail

1. 14 Dedicated MMORPG Item Types

Every item belongs to a specific functional category that dictates how it behaves, where it can be equipped, and what mechanics it triggers:

2. Comprehensive RPG Stat Engine

RoyItems calculates player attributes using an industry-standard formula: $$\text{Total Stat} = (\text{Base} + \sum \text{Flat Modifiers}) \times (1 + \sum \text{Percentage Modifiers})$$

Supported Custom Stats:

• ⚔️ Attack Damage: Base physical melee damage.
• 🏹 Arrow Damage: Custom ranged projectile damage.
• ⚡ Attack Speed: Weapon swing and recovery speed.
• 🎯 Critical Rate: Chance to trigger a critical strike (e.g. 15%).
• 💥 Critical Damage: Bonus multiplier applied during critical hits (e.g. 50%).
• 🛡️ Defense: Core defense value routed through the active defense calculation engine.
• ⚔️ PvP Damage: Bonus damage dealt exclusively against other players.
• 🗡️ PvE Damage: Bonus damage dealt exclusively against monsters and bosses.
• 🛡️ PvP Defense: Resistance reducing incoming damage from players.
• 🛡️ PvE Defense: Resistance reducing incoming damage from monsters.
• 🔰 Damage Reduction: Direct percentage damage mitigation cap (e.g. 10%).
• ❤️ Max Health: Increases the player's maximum health pool.
• 👟 Movement Speed: Increases player sprint and walk speed.
• 🏋️ Knockback Resistance: Prevents players from being tossed by heavy blows.
• 🛡️ Vanilla Armor & Toughness: Seamlessly binds to Minecraft's modern attribute registry.

3. Next-Gen Defense System

Configure how damage mitigation works in config.yml:

combat:
  defense:
    # Choose: MMORPG, SIMPLE, or CUSTOM_LIMIT
    mode: "MMORPG"
    
    # Mode 1: SIMPLE (Flat Damage = Damage - Effective Defense)
    simple:
      floor-damage: 0.0

    # Mode 2: MMORPG (Non-Linear Diminishing Returns)
    # Formula: Final Damage = Damage * (scale / (scale + Effective Defense))
    mmorpg:
      scale: 100.0
      damage-factor: 1.0
      min-damage-floor: 1.0

    # Mode 3: CUSTOM_LIMIT (Strict Clamped Damage Boundaries)
    custom-limit:
      min-damage:
        enabled: true
        value: 2.0
      max-damage:
        enabled: false
        value: 100.0

• MMORPG Curve Advantage: Prevents high-tier armor from creating invincible players while guaranteeing that low-level attackers still deal meaningful chip damage.
• PvP & PvE Defense: Automatically calculates Effective Defense = Defense + (PvP/PvE Defense) depending on whether the attacker is a player or an entity.

4. Interactive Gem Socketing

Upgrade your equipment intuitively without clunky anvil mechanics:

1. Define socket layouts on gear (e.g. Universal 1, Specific RUBY, or Multiple ABC).
2. Pick up a GEM_STONE item on your cursor in the inventory.
3. Click directly onto the socketable equipment.
4. The gem is applied instantly, updating lore and player stats while preserving all other item properties!

5. Equipment Sets & Quality Tiers

• Item Tiers (item-tier.yml): Assign visual quality to your equipment (e.g., Common, Rare, Epic, Legendary, Mythic) with custom colors, display prefixes, and rarity weightings.
• Item Sets (item-set.yml): Reward players for wearing full armor sets. Configure multi-piece milestones (e.g., 2-piece and 4-piece bonuses) that unlock bonus stats like additional Max Health, Damage Reduction, or Critical Strike buffs.

6. Paginated In-Game GUI Editor (/ri editor)

Manage your entire item catalog without opening a single text editor:

• Type Dashboard: Browse items grouped by category with live item counts.
• Sequential Page Navigation: Switch smoothly between Page 1 (General & Display), Page 2 (Stats & Attributes), and Page 3 (Mechanics & Requirements).
• 100% Stat Coverage: Dedicated icons for each individual stat, enchantment, trim, model, and requirement.
• Live Preview Slot: See exact changes in real-time. Left-click the preview slot to receive a copy directly into your inventory!
• Anti-Italic Typography: Automatically disables Minecraft's default italic formatting on custom items unless explicitly configured.
• Admin Session Lock: Prevents multiple staff members from overwriting the same item simultaneously.

7. Real-Time Expiration & Cooldowns

• Timed Equipment (expired: 3 days / 1 month): Tracks countdowns via real-world epoch timestamps stored in the item's PersistentDataContainer (PDC). When expired, the item automatically disintegrates into particles upon being held or moved. Admins with royitems.item.expired.bypass are exempt.
• Right-Click Cooldowns: Assign cooldown timers to weapons, consumables, or voucher items to prevent spamming.

8. Custom Models, Trims & Visual Assets

RoyItems integrates with modern Minecraft customization pipelines:

• Minecraft 1.21.4+ Item Models: Set custom item model keys natively without breaking vanilla behavior.
• CustomModelData: Full support for classic numeric model data integers.
• Armor Trims: Configure trim materials (Netherite, Gold, Amethyst, etc.) and trim patterns (Silence, Vex, Coast, etc.).
• Leather Armor Dyes: Custom RGB hex color dying.
• Player Heads: Reference heads via HeadDatabase ID (hdb-<id>) or Base64 textures (basehead-<base64>).

📋 Commands & Permissions

Commands

💡 Tip: Use amount ranges like /ri give Steve SWORD excalibur 1-3 to award random drop amounts from mob kills or quest rewards!

Permissions

🧩 Verified Integrations

RoyItems integrates with your existing server infrastructure. All hooks are lightweight and load conditionally:

⚙️ Installation & Quick Start

1. Verify Requirements: Ensure your server runs on Paper, Purpur, or Folia running Minecraft 1.21.x+ (1.21.4+ recommended) on Java 21 or newer.
2. Download & Place: Place RoyItems.jar into your server's plugins/ directory.
3. Start Server: Boot your server to generate default files in plugins/RoyItems/.
4. Create Your First Item:
   • Method A (In-Game): Type /ri editor and create or customize items visually.
   • Method B (YAML): Open plugins/RoyItems/item/SWORD.yml and add a new item entry:

   excalibur:
     material: DIAMOND_SWORD
     name: "<gradient:#FFE066:#FF8800>&lExcalibur</gradient>"
     lore:
       - "&7The legendary blade of divine kings."
       - "&7Forged in celestial light."
     lore-format: weapon
     unbreakable: true
     glow: true
     stats:
       attack-damage: 28
       crit-rate: 25%
       crit-damage: 60%
       pvp-damage: 12
     item-tier: legendary
     item-set: dragon_slayer
     gem-socket:
       - "1"
       - "A"
     version: 1
   

5. Reload & Distribute: Run /ri reload to apply your changes. Test it in-game with /ri give @s SWORD excalibur 1.

❓ Frequently Asked Questions (FAQ)

📊 Plugin Statistics & Telemetry

RoyItems collects anonymous metrics through bStats. All telemetry is 100% anonymous, thread-safe, and Folia-compliant—gathering vital insights such as server software distribution, active integrations, defense mode selections, and item feature usage without ever impacting server performance or storing sensitive player data.

📈 Interested in real-time server versions, integration popularity, defense mode breakdowns, and item features? Explore the live interactive dashboard on the Official RoyItems bStats Page.

💬 Community & Support

Need assistance with item configuration, custom mechanics, or have a feature request? Join our active Discord server:

• 💬 Discord Support: https://discord.gg/zNpkXGFQRS
• 🐛 Bug Reports: Join our Discord support desk for priority assistance.

RoyItems is developed and maintained with passion for high-performance Minecraft MMORPG servers.