RoyItems

⚔️ 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:

Item Type	Description & Primary Use Case	Active Trigger / Equipment Slot
SWORD	Melee weapons with attack damage, critical strikes, and PvP/PvE scaling	Main Hand
ARMOR	Helmets, Chestplates, Leggings, and Boots supporting Armor Trims & Leather Dye	Head, Chest, Legs, Feet
BOW	Ranged bows applying custom arrow damage and ranged critical modifiers	Main Hand
CROSSBOW	High-impact ranged crossbows	Main Hand
STAFF	Magic casting staves triggering abilities, mana consumption, or Mythic skills	Main Hand
TOOL	Harvesting pickaxes, shovels, and axes with custom stats	Main Hand
GEM_STONE	Sockets upgrade stones slotted via drag-and-drop onto gear	Inventory Drag & Drop
CONSUMABLE	Potions, scrolls, and food granting timed potion effects and cooldowns	Right-Click
MATERIAL	Crafting resources and quest ingredients	Inventory
OFF_HAND	Shields, tomes, and off-hand defensive gear	Off Hand
WING	Gliders and wings (Elytra) enhancing flight velocity and protection	Chestplate Slot
VOUCHER	Claimable scrolls executing console commands with one-time use	Right-Click
TALISMAN	Passive relics granting bonuses simply by resting in the player's inventory	Inventory / Hand
PET	Companion summoning tokens and collectible pets	Inventory / Hand

---

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

Command	Arguments	Description	Default Permission
/ri help	—	Displays the interactive help menu	Everyone
/ri editor	—	Opens the paginated In-Game Item Editor GUI	royitems.command.editor (OP)
/ri reload	—	Reloads all configs and triggers LiveUpdate	royitems.command.reload (OP)
/ri give	<player|all> <type> <id> [amount]	Gives custom items (supports ranges like 1-3)	royitems.command.give (OP)
/ri take	<player|all> <type> <id> [amount]	Removes a specific custom item by ID	royitems.command.take (OP)
/ri drop	<player|all> <type> <id> [amount]	Spawns items naturally at a player's feet	royitems.command.drop (OP)
/ri drop	<world> <x> <y> <z> <type> <id> [amt]	Spawns items at specific world coordinates	royitems.command.drop (OP)

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

Permissions

Permission Node	Description	Default
royitems.admin	Grants full access to all RoyItems commands and administrative features	OP
royitems.command.help	Allows viewing command usage and help entries	True
royitems.command.editor	Allows opening and editing items via /ri editor	OP
royitems.command.reload	Allows reloading plugin configurations with /ri reload	OP
royitems.command.give	Allows distributing items to players	OP
royitems.command.take	Allows taking items from player inventories	OP
royitems.command.drop	Allows dropping custom items at players or coordinates	OP
royitems.item.expired.bypass	Prevents items from decaying/expiring in the player's inventory	OP

---

🧩 Verified Integrations

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

Plugin	Integration Type	Official Link	What it Enables
PlaceholderAPI	Soft Depend	Modrinth	Access player stats with %royitems_stat_<stat>% and hand item data
AuraSkills	Soft Depend	Modrinth	Skill level requirements (aura-skill, aura-skill-level) & mana scaling
WorldGuard	Soft Depend	Modrinth	Respects region protection, PvP flags, and item interaction boundaries
WorldEdit	Soft Depend	Modrinth	Region selection safety and block modification compatibility
FastAsyncWorldEdit	Soft Depend	Modrinth	Async schematic and regional verification
Oraxen	Soft Depend	SpigotMC	Seamless custom models, item definitions, and texture pack binding
Vault	Soft Depend	SpigotMC	Economy transactions, currency requirements, and shop compatibility
MMOCore	Soft Depend	SpigotMC	Player class checks (mmocore-class), level requirements, and mana
MythicMobs	Soft Depend	Modrinth	Execute Mythic skills via weapons/staves and assign items to mob drop tables
HeadDatabase	Soft Depend	SpigotMC	Direct head skin resolution via hdb-<id>
Nexo	Soft Depend	NexoMC	Native custom item models and resource pack components
ItemsAdder	Soft Depend	SpigotMC	Custom item models, custom armor, and texture integrations

---

⚙️ 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)

Does RoyItems cause server lag on high player counts?

Not at all. RoyItems stores item identifiers and dynamic data directly inside Minecraft's NBT PersistentDataContainer (PDC). It never performs slow, heavy string comparisons on lore or item names. In combat, stats are cached in memory (PlayerStatCache), ensuring calculations take sub-millisecond execution times.

Is Folia truly supported?

Yes! RoyItems contains a dedicated platform abstraction layer (PlatformScheduler) that routes all player and inventory operations through Folia's regional entity schedulers (runEntity / runLocation). It contains zero global-scheduler locking violations.

How does the LiveUpdate feature protect player gems?

When an item is rebuilt after an admin runs /ri reload, the LiveUpdate service reads the existing slotted gems, remaining expiration time, and durability from the item's PDC tags before applying the updated lore, base stats, and model from the configuration file. Your players will never lose their socketed gems!

Can I use Hex Colors and MiniMessage?

Yes. RoyItems has full native support for Adventure MiniMessage (e.g. <gradient:#ff0000:#00ff00>), standard Legacy color codes (e.g. &c, &l), and Hex color codes (e.g. &#FF5733).

Do custom items lose their formatting or look italicized?

No. RoyItems features automatic Anti-Italic protection across all generated items and editor GUI menus, ensuring text renders crisp, modern, and upright unless you purposefully specify italic formatting.

---

📊 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.