⚔️ RoyItems — 高级 MMORPG 自定义物品引擎
🌟 概览
欢迎使用 RoyItems,这是一款高性能、现代化的 MMORPG 自定义物品与属性引擎,专为运行在 Paper、Purpur、Folia、Leaf 和 Spigot 上的 Minecraft 1.21+ 服务器打造。
无论你运营的是庞大的 SkyBlock 网络、硬核的 MMORPG 领域、竞争激烈的 Factions 服务器,还是紧密协作的生存社区,RoyItems 都能提供前所未有的强大功能、灵活性和架构可靠性。
💡 RoyItems 的独特之处
- 🚀 100% 独立架构: 运行无需任何依赖项。没有臃肿的前置库或强制框架依赖——只需将 JAR 放入插件文件夹即可运行。
- ⚡ 原生支持 Folia & Leaf 多线程: 围绕异步数据解析和区域感知调度(
PlatformScheduler)构建。大规模操作、广域挖掘和实时库存更新可流畅运行,无任何区域线程阻塞或刻延迟。
- 🛡️ 零 NMS 反射: 严格基于清晰、向前兼容的 Paper API 和 PersistentDataContainer (PDC) 存储构建。可在 Minecraft 小版本间平滑更新,而不会破坏物品数据或等待数周的反射补丁。
- ⚔️ 独立的 MMORPG 属性与防御计算: 具备 17 种可扩展的自定义属性:
$$\text{总属性} = (\text{基础值} + \sum \text{固定加成}) \times \left(1 + \sum \text{百分比加成}\right)$$
在不干扰原版 Minecraft 护甲上限、韧性上限或属性修饰符上限的情况下运行。
- 🔄 热重载 LiveUpdate: 随时修改物品配置、层级、描述文本格式或合成配方。运行
/ri reload 会自动更新在线玩家库存、盔甲槽、副手和末影箱中的现有物品,同时保留自定义耐久度、插槽宝石和附魔。
- 🎨 支持 Minecraft 1.21+ 可装备组件: 原生支持现代 Equippable 组件,无缝地将来自 Nexo 和自定义资源包的 2D 自定义盔甲模型直接渲染到玩家角色模型上。
🚀 功能特性
RoyItems 采用模块化游戏机制套件设计,旨在提升服务器的玩家进度和经济系统:
1. 📦 14 种专用物品原型
每个自定义物品都被分配了一个功能类型,决定了其装备位置、激活方式及适用规则:
- 近战与远程武器:
SWORD(剑)、BOW(弓)、CROSSBOW(弩)和 STAFF(法杖),支持自定义攻击速度、暴击率扩展、箭矢速度和右键魔法施放。
- 防御装备与外观:
ARMOR(头盔、胸甲、护腿、靴子)支持 2D 自定义装备模型,OFF_HAND(盾牌/法球),WING(滑翔翼/鞘翅),以及 COSMETIC(装饰性)物品。
- 采集与挖掘:
TOOL(工具)原型支持广域水平切片(mine-radius)。
- 进度、经济与插槽:
GEM_STONE(宝石)用于镶嵌,TALISMAN(护符)用于被动库存属性增益,CONSUMABLE(消耗品)用于食物和药水增益,MATERIAL(材料)用于合成配方,以及 VOUCHER(凭证)用于交互式货币奖励。
2. ⛏️ 广域挖掘半径且无实体延迟
- 严格的水平 2D 切片 ($Y = Y_0$): 仅在破坏方块周围的水平层进行挖掘(第 1 级:$3\times 3$,第 2 级:$5\times 5$,第 3 级:$7\times 7$,第 4 级:$9\times 9$,第 5 级:$11\times 11$)。绝不会挖出深垂直洞或意外破坏天花板/地板建筑。
- 幽灵方块消除: 立即在 48 格半径内广播权威的客户端多播
sendBlockChange 数据包,随后在区域调度器上进行 1 刻延迟的物理后验证。
- AdvancedOreGen 原位再生: 检测 SkyBlock 生成器方块(栅栏-水、圆石、玄武岩),并通过 AdvancedOreGen 触发原位矿石再生,而不会将方块变为 AIR,从而保护流体流动不会变成黑曜石。
- Direct ExtraStorage 批量处理: 将所有收集的掉落物直接存入内存中的玩家 ExtraStorage 保险箱,绕过地面物品实体,完全消除实体掉落延迟峰值。
- 线程安全的活跃挖掘锁定: 并发锁定活跃坐标,以防止重复方块破坏、物品复制漏洞或多个玩家同时挖掘时的流体物理死锁。
3. 🎁 动态标题抽奖与多货币优惠券
- 空气与方块交互: 在主手或副手中,对着空空气或任意方块右键即可激活优惠券,无需瞄准实体。
- 动态标题动画: 在展示奖励之前,播放滚动的标题序列,支持自定义音效、粒子爆发和动态音调。
- 多货币充值: 直接集成 Vault(金钱)、PlayerPoints(点数)和 ExcellentEconomy(多货币余额)。
- 安全的原子交易: 如果经济提供商不可用或交易失败,优惠券将自动退款,确保物品零损失。
- 命令自动化: 支持占位符(
#player#、#amount#、#currency#),按顺序执行多条控制台或玩家命令。
4. 💎 实时动态描述与套装加成
- 动态描述引擎: 装备、附魔或镶嵌宝石时,描述会实时更新。支持 MiniMessage、十六进制颜色(
&#RRGGBB)以及传统格式代码。
- 动态
#set# 描述: 当装备或卸下盔甲部件时,套装物品会实时切换显示激活或未激活的套装加成描述。
- 宝石镶嵌: 可配置插槽数量(
sockets: 3)、允许的宝石类型,并提供交互式拖放或镶嵌台 GUI。
5. 🎯 基于数据包的训练假人与 DPS 计量器
- 虚拟战斗测试: 生成基于数据包的战斗训练假人(
/ri dummy spawn <id> [mob_type]),用于测试真实玩家伤害、暴击和武器每秒伤害(DPS)。
- 浮动全息计量器: 实时浮动全息图显示当前打击伤害、最大伤害以及每 5 秒间隔的 DPS。
- 零实体延迟: 假人使用虚拟数据包实体,无需持续的实体计时或 AI 寻路计算。
6. 🛠️ 游戏内交互式 GUI 编辑器
- 输入
/ri edit 打开全面的 GUI 编辑器,直接在 Minecraft 游戏中浏览、检查、创建和配置自定义物品,无需触碰原始 YAML 文件。
📥 安装
安装 RoyItems 不到 60 秒:
- 验证要求:
- 服务器软件:Paper、Purpur、Folia、Leaf 或 Spigot(Minecraft 1.21+)。
- Java 运行时:Java 21 或更高版本。
- 下载发行版:
- 从 Modrinth 下载最新的
RoyItems-2026.1.8.jar。
- 验证依赖项:
- RoyItems 没有必需的依赖项。你不需要安装任何外部库。
- 如果你希望使用经济功能、技能或自定义模型,请确保安装了可选的软依赖项(例如 Vault、Nexo、ExtraStorage)。
- 放入插件目录:
- 将
RoyItems-2026.1.8.jar 放入服务器的 plugins/ 文件夹中。
- 启动服务器:
- 引导或重启你的服务器。检查控制台输出是否包含:
[RoyItems] Initializing RoyItems v2026.1.8...
[RoyItems] Successfully loaded custom items and crafting stations.
- 自定义配置:
- RoyItems 会在
plugins/RoyItems/ 中自动生成干净、默认的配置。
- 通过 YAML 文件或在游戏内使用
/ri edit 编辑设置。使用 /ri reload 即时应用更改。
- 故障排除提示:
- UnsupportedClassVersionError: 确保你的启动脚本使用 Java 21+(
java -version)。
- Permission Denied: 确保你的权限插件(例如 LuckPerms)为服务器管理员分配了
royitems.admin 权限。
💻 命令
RoyItems 在 /royitems 下提供了一个直观的命令系统(简写别名:/ri):
| 命令语法 |
参数与选项 |
所需权限 |
描述 |
/ri help |
[page] |
royitems.command.help |
查看交互式命令帮助和使用说明。 |
/ri reload |
— |
royitems.command.reload |
重新加载所有配置、物品、语言并运行 LiveUpdate。 |
/ri editor |
— |
royitems.command.editor |
打开交互式游戏内 GUI 物品与工作台编辑器。 |
/ri checkupdate |
— |
royitems.command.checkupdate |
检查 Modrinth 上是否有新的 RoyItems 发布。 |
/ri give |
<player|all> <type> <id> [amt] |
royitems.command.give |
直接将自定义物品给予某位玩家或所有在线玩家。 |
/ri take |
<player|all> <type> <id> [amt] |
royitems.command.take |
从某位玩家或所有在线玩家处移除自定义物品。 |
/ri drop |
<player|all> <type> <id> [amt] |
royitems.command.drop |
在某位玩家的位置掉落自定义物品。 |
/ri drop |
<world> <x> <y> <z> <type> <id> [amt] |
royitems.command.drop |
在世界特定坐标处掉落自定义物品。 |
/ri station open |
<id> [player] |
royitems.command.station.open |
为你自己或目标玩家打开特定的工作台 GUI。 |
/ri station list |
— |
royitems.command.station.list |
打开交互式工作台列表概览 GUI。 |
/ri station create |
<id> |
royitems.command.station.create |
在 crafting-station/ 中生成一个新的工作台模板文件。 |
/ri station delete |
<id> |
royitems.command.station.delete |
永久删除一个工作台及其 YAML 文件。 |
/ri dummy spawn |
<id> [mob_type] |
royitems.command.dummy |
在你所在的位置生成一个基于数据包的 DPS 训练假人。 |
/ri dummy despawn |
<id|all> |
royitems.command.dummy |
移除特定的训练假人或所有活跃的假人。 |
🔑 权限
⚡ 动态权限统计(LuckPerms 集成)
直接向玩家等级或组授予固定值或百分比属性加成,无需玩家穿戴或手持物品:
royitems.player.stats.<stat>.<value> # 固定值提升(例如 +25 防御力)
royitems.player.stats.<stat>.<value>% # 百分比提升(例如 +15% 攻击伤害)
| 权限节点示例 |
目标属性 |
生效效果 |
royitems.player.stats.attack-damage.10 |
攻击伤害 |
为所有近战攻击提供 +10 固定攻击伤害。 |
royitems.player.stats.max-health.40 |
最大生命值 |
提供 +40 固定最大生命值(额外增加 2 整排心形图标)。 |
royitems.player.stats.defense.25 |
防御力 |
提供 +25 固定减伤值,用于减免所受伤害。 |
royitems.player.stats.crit-rate.15% |
暴击率 |
暴击几率增加 +15%。 |
royitems.player.stats.movement-speed.10% |
移动速度 |
在所有世界中提供 +10% 的移动速度加成。 |
royitems.player.stats.pvp-damage.12% |
PvP 伤害 |
对玩家造成的伤害增加 +12%。 |
royitems.player.stats.generic.scale.1.2 |
原版缩放比例 |
玩家模型尺寸增大 20%(适用于 Minecraft 1.21+ 的属性)。 |
🛡️ 管理员与命令权限
| 权限节点 |
描述 |
默认访问权限 |
royitems.admin |
对所有 RoyItems 命令、编辑器菜单及绕过机制拥有完全通配符访问权限。 |
仅限 OP |
royitems.command.help |
允许查看 /ri help。 |
仅限 OP |
royitems.command.reload |
允许通过 /ri reload 重新加载配置。 |
仅限 OP |
royitems.command.editor |
允许通过 /ri editor 访问游戏内 GUI 编辑器。 |
仅限 OP |
royitems.command.checkupdate |
允许通过 /ri checkupdate 检查插件版本。 |
仅限 OP |
royitems.command.give |
允许通过 /ri give 发放自定义物品。 |
仅限 OP |
royitems.command.take |
允许通过 /ri take 收回自定义物品。 |
仅限 OP |
royitems.command.drop |
允许通过 /ri drop 在玩家处或指定坐标掉落物品。 |
仅限 OP |
royitems.command.station |
所有工作台管理命令的父级权限。 |
仅限 OP |
royitems.command.station.open |
允许通过 /ri station open 打开工作台。 |
仅限 OP |
royitems.command.station.list |
允许通过 /ri station list 列出所有工作台。 |
仅限 OP |
royitems.command.station.create |
允许通过 /ri station create 创建工作台。 |
仅限 OP |
royitems.command.station.delete |
允许通过 /ri station delete 删除工作台。 |
仅限 OP |
royitems.command.dummy |
允许生成或移除战斗训练假人。 |
仅限 OP |
royitems.item.expired.bypass |
允许绕过限时自定义物品的过期限制。 |
仅限 OP |
royitems.station.<station_id> |
若已配置,访问特定工作台所需的权限。 |
可配置 |
royitems.item.use.<type>.<id> |
若已配置,使用或消耗某物品所需的权限。 |
可配置 |
🏷️ 占位符
🌐 PlaceholderAPI 集成 (%royitems_...%)
RoyItems 提供了内置的 PlaceholderAPI 扩展,支持用于 HUD、计分板、TAB 列表和聊天插件:
| 占位符 |
返回值 |
描述 |
%royitems_stat_<stat>% |
数字(例如 125.5) |
返回玩家针对 <stat> 计算得出的总值(装备 + 权限)。 |
%royitems_stat_attack-damage% |
数字(例如 45.0) |
返回总近战攻击伤害。 |
%royitems_stat_defense% |
数字(例如 80.0) |
返回总防御减伤值。 |
%royitems_stat_max-health% |
数字(例如 60.0) |
返回玩家的最大生命值属性。 |
%royitems_stat_crit-rate% |
数字(例如 25%) |
返回玩家的暴击概率百分比。 |
%royitems_stat_mine-radius% |
数字(例如 2) |
返回当前广域水平挖掘半径等级。 |
%royitems_hand_type% |
字符串(例如 SWORD) |
返回主手所持自定义物品的 ItemType。 |
%royitems_hand_id% |
字符串(例如 excalibur) |
返回所持物品的唯一配置 ID。 |
%royitems_hand_name% |
文本(例如 Excalibur) |
返回所持物品的格式化显示名称。 |
%royitems_hand_tier% |
字符串(例如 LEGENDARY) |
返回所持物品的稀有度层级 ID。 |
%royitems_hand_version% |
数字(例如 2) |
返回所持物品的持久化版本号。 |
📜 内部动态战利品文本占位符 (lore-format/*.yml)
这些占位符会在物品战利品文本模板中进行评估,并实时渲染:
| Lore 占位符 |
渲染输出 |
上下文 / 描述 |
#name# |
String |
物品格式化后的显示名称。 |
#type# |
String |
格式化后的类型显示名称(例如 Melee Weapon、Armor Equipment)。 |
#tier# |
String |
格式化后的稀有度等级名称(例如 &6Legendary)。 |
#tier-color# |
Color code |
分配给物品等级的颜色格式化代码。 |
#set# |
Text block |
动态套装描述文本(在激活与未激活的套装加成之间切换)。 |
#set-name# |
String |
已分配套装的官方显示名称。 |
#lore# |
Text lines |
用户自定义的物品描述行。 |
#stats# |
Block of lines |
根据 stat-format.yml 格式化的 MMORPG 属性列表。 |
#stat_<stat_name># |
Number |
物品上特定属性的直接数值。 |
#enchantments# |
Block of lines |
格式化后的附魔列表(支持 Vanilla 和 EcoEnchants)。 |
#sockets# |
Block of lines |
视觉插槽指示器,包含已填充宝石详情与空槽位。 |
#requirements# |
Block of lines |
等级、职业和权限要求,并根据是否满足动态着色。 |
#durability# |
String |
当前自定义耐久度与最大耐久度(例如 1,250/1,500)。 |
#bar# |
String |
描述文本格式化模板中定义的视觉分隔线或进度条。 |
#cooldown# |
String |
法杖、消耗品或凭证的冷却持续时间(秒)。 |
#expiration# |
String |
临时物品的过期倒计时计时器或日期。 |
#mine-radius# |
String (例如 3×3) |
格式化后的水平区域切割维度。 |
#unbreakable# |
String |
如果物品配置为不可破坏时显示的标签指示器。 |
📦 物品类型
RoyItems 支持 14 种不同的物品类型,每种都有严格的装备槽位验证:
| 物品类型 |
默认槽位 |
有效装备槽位 |
主要角色与特殊机制 |
SWORD |
HAND |
HAND (主手) |
近战战斗武器。提供攻击性战斗属性、生命窃取和暴击。 |
ARMOR |
Auto |
HEAD, CHEST, LEGS, FEET |
防御装备。支持可装备的 2D 模型、防御属性和套装加成。 |
BOW |
HAND |
HAND (主手) |
远程弓。应用箭矢伤害、拉弓速度倍率和远程暴击。 |
CROSSBOW |
HAND |
HAND (主手) |
重型远程弩,具有自定义穿透力和投射物属性。 |
STAFF |
HAND |
HAND (主手) |
魔法施的法杖。支持右键施法、法力消耗和冷却时间。 |
TOOL |
HAND |
HAND (主手) |
挖掘工具(镐、斧、铲、锄),带有 mine-radius 切割功能。 |
GEM_STONE |
None |
仅插槽 |
可嵌入装备中的宝石,用于提升固定值或百分比属性。 |
CONSUMABLE |
HAND |
HAND (主手) |
可食用物品,施加自定义药水效果和生命值恢复,并带有冷却时间。 |
MATERIAL |
None |
背包 / 配方 |
在制作站配方中使用的特殊原料。 |
OFF_HAND |
OFF_HAND |
OFF_HAND (副手) |
防御盾牌、魔法球以及次要副手属性增益器。 |
WING |
CHEST |
CHEST (胸甲) |
滑翔翼和鞘翅,支持自定义耐久度和飞行属性。 |
VOUCHER |
HAND |
HAND, OFF_HAND (空中与方块) |
消耗型奖励卷轴,授予货币、命令和称号抽奖。 |
PET |
None |
背包 / 同伴 |
同伴物品,提供实用便利功能和视觉效果。 |
TALISMAN |
None |
被动背包 |
饰品护符,只需放置在玩家背包中即可赋予被动属性。 |
📊 物品属性
RoyItems 包含 17 种内置 MMORPG 属性,分为战斗、防御、实用性和世界交互四类:
| 属性标识符 |
默认图标与名称 |
修改类型 |
原版映射 |
游戏功能与机制 |
attack-damage |
⚔ 攻击伤害 |
固定值 / % |
generic.attack_damage |
近战攻击时造成的基础物理伤害。 |
arrow-damage |
🏹 箭矢伤害 |
固定值 / % |
无(自定义) |
从弓和弩发射的箭矢所附加的额外伤害。 |
max-health |
❤ 最大生命值 |
固定值 / % |
generic.max_health |
平滑增加玩家的最大生命心数。 |
attack-speed |
⚡ 攻击速度 |
固定值 / % |
generic.attack_speed |
武器挥动恢复速度和战斗打击频率。 |
crit-rate |
🎯 暴击率 |
固定值 / % |
无(自定义) |
触发暴击的概率百分比(0% 至 100%)。 |
crit-damage |
💥 暴击伤害 |
固定值 / % |
无(自定义) |
触发暴击时应用的额外伤害乘数。 |
defense |
🛡 防御 |
固定值 / % |
无(自定义) |
独立的 MMORPG 防御公式,用于减免所有受到的伤害。 |
pvp-damage |
⚔ PvP 伤害 |
固定值 / % |
无(自定义) |
仅在 PvP 中对其他玩家造成额外伤害。 |
pve-damage |
🗡 PvE 伤害 |
固定值 / % |
无(自定义) |
仅对敌对怪物和地牢生物造成额外伤害。 |
pvp-defense |
🛡 PvP 防御 |
固定值 / % |
无(自定义) |
仅在受到来自玩家的伤害时应用的伤害减免。 |
pve-defense |
🛡 PvE 防御 |
固定值 / % |
无(自定义) |
仅在受到来自怪物的伤害时应用的伤害减免。 |
damage-reduction |
🔰 伤害减免 |
固定值 / % |
无(自定义) |
直接应用于最终受到伤害的固定百分比减免。 |
armor |
🛡 护甲 |
固定值 / % |
generic.armor |
Minecraft 原版护甲防御值。 |
armor-toughness |
🛡 护甲韧性 |
固定值 / % |
generic.armor_toughness |
用于减免高伤害打击的原版护甲韧性值。 |
knockback-resistance |
🏋 击退抗性 |
固定值 / % |
generic.knockback_resistance |
抵抗来自打击和爆炸的物理击退效果。 |
movement-speed |
👟 移动速度 |
固定值 / % |
generic.movement_speed |
玩家行走和冲刺的速度倍率。 |
mine-radius |
⛏ 挖掘半径 |
等级 (1–5+) |
无(自定义) |
水平二维平面区域的挖掘维度(等级 1: $3\times 3$,等级 2: $5\times 5$)。 |
⚙️ 配置
RoyItems 在 plugins/RoyItems/ 目录内以模块化、整洁的 YAML 目录结构组织配置:
plugins/RoyItems/
├── config.yml # 核心插件设置、战斗公式、性能及更新
├── item-tier.yml # 物品稀有度等级、自定义聊天颜色和掉落光晕轮廓
├── item-set.yml # 盔甲套装加成、装备阈值和动态描述
├── items/ # 按原型分组的模块化物品定义文件
│ ├── SWORD.yml # 近战剑类和匕首
│ ├── ARMOR.yml # 头盔、胸甲、护腿和靴子
│ ├── BOW.yml # 远程弓类
│ ├── CROSSBOW.yml # 远程弩类
│ ├── STAFF.yml # 魔法法杖
│ ├── TOOL.yml # 采集工具(镐、铲、斧、锄)
│ ├── GEM_STONE.yml # 可镶嵌的宝石和符文
│ ├── CONSUMABLE.yml # 食物和药水消耗品
│ ├── TALISMAN.yml # 被动背包饰品
│ ├── VOUCHER.yml # 经济、奖励和指令卷轴
│ └── WING.yml # 鞘翅和滑翔翼
├── crafting-station/ # 带有配方链和 NPC 链接的自定义工作台文件
│ └── blacksmith.yml # 示例多页铁匠铺工作台
├── lore-format/ # 通用和按类型划分的描述格式化模板
│ ├── default.yml # 通用后备描述模板
│ ├── weapon.yml # 武器专用描述布局
│ └── armor.yml # 盔甲专用描述布局
├── gui/ # 用于菜单和工作台浏览器的游戏内 GUI 布局
│ ├── editor-gui.yml # 游戏内物品编辑器 GUI
│ ├── crafting-station-list.yml
│ └── crafting-station-detail.yml
└── lang/ # 多语言本地化文件
├── en-US.yml # 英语 (美国)
├── vi-VN.yml # 越南语 (Tiếng Việt)
├── de-DE.yml # 德语 (Deutsch)
├── es-ES.yml # 西班牙语 (Español)
├── ja-JP.yml # 日语 (日本語)
├── ko-KR.yml # 韩语 (한국어)
└── ru-RU.yml # 俄语 (Русский)
以下是标准的默认配置。点击每个部分以展开:
📄 点击展开:config.yml (核心设置与战斗引擎)
# ==============================================================================
# ROYITEMS — 配置引擎
# ==============================================================================
config-version: 2
# 常规设置
debug: false
# 当前使用的本地化语言:
# 支持:en-US, vi-VN, de-DE, ja-JP, ko-KR, ru-RU, es-ES
language: en-US
# 当存在多个 MMORPG 提供商时的首选提供商 (MMOCore, AuraSkills, Auto)
mana-provider: Auto
# 性能调优
performance:
# 检查物品过期的频率(秒级,低开销)
expiration-check-interval: 20
# 周期性应用药水效果的频率(秒级)
potion-effect-interval: 3
# ==============================================================================
# 更新检查器 (检查 Modrinth 上的新版本)
# ==============================================================================
update-checker:
enabled: true
notify-admins-on-join: true
==============================================================================
战斗与自定义防御系统
==============================================================================
combat:
defense:
# 模式:MMORPG、SIMPLE(简单)或 CUSTOM_LIMIT(自定义上限)
mode: MMORPG
# MMORPG 公式:damage = rawDamage * (100 / (100 + defense))
mmorpg-constant: 100.0
# 自定义上限模式设置
custom-limit:
defense-cap: 500.0
max-reduction-percentage: 80.0
# 减轻来自 MythicMobs 技能机制的伤害
mitigate-mythic-skills: true
==============================================================================
实时更新系统(在 /ri reload 时更新玩家背包中的物品)
==============================================================================
live-update:
enabled: true
preserve:
enchantments: true
gems: true
durability: true
custom-lore: true
display-name: false
lore: false
tier: false
==============================================================================
挖掘半径机制与高级矿石生成集成
==============================================================================
mine-radius:
enabled: true
activation-chance: 100.0
cooldown-ms: 0
limits:
max-radius-tier: 5
max-blocks-per-break: 150
extra-storage:
auto-deposit: true
drop-leftover-to-world: true
advanced-ore-gen:
auto-regenerate: true
==============================================================================
抽奖券与货币映射
==============================================================================
voucher:
gacha:
enabled: true
duration-ticks: 30
interval-ticks: 2
sound-roll: "BLOCK_NOTE_BLOCK_PLING"
sound-finish: "UI_TOAST_CHALLENGE_COMPLETE"
particle: "FIREWORK"
particle-count: 35
currencies:
vault:
name: "Money"
symbol: "$"
format: "#,##0.##"
playerpoints:
name: "Points"
symbol: "✪"
format: "#,##0"
</details>
<details>
<summary><b>📄 点击展开:item-tier.yml(稀有度等级与发光轮廓)</b></summary>
```yaml
# ==============================================================================
# ROYITEMS — 物品等级配置
# ==============================================================================
config-version: 2
common:
display-name: "&fCommon"
color: "&f"
weight: 1
drop-color: WHITE
uncommon:
display-name: "&aUncommon"
color: "&a"
weight: 2
drop-color: GREEN
rare:
display-name: "&9Rare"
color: "&9"
weight: 3
drop-color: BLUE
epic:
display-name: "&5Epic"
color: "&5"
weight: 4
drop-color: DARK_PURPLE
legendary:
display-name: "&6Legendary"
color: "&6"
weight: 5
drop-color: GOLD
mythic:
display-name: "&dMythic"
color: "&d"
weight: 6
drop-color: RED
📄 点击展开:item-set.yml(动态套装加成与描述文本)
# ==============================================================================
# ROYITEMS — 物品套装配置
# ==============================================================================
dragon_slayer:
display-name: "&6Dragon Slayer Set"
required-pieces: 2
lore:
active:
- "&6Set: Dragon Slayer &a[Active]"
- "&7(2) &a+15 Attack Damage, +10% Crit Rate"
- "&7(4) &a+35 Attack Damage, +50% Crit Damage, +20 PvP Damage"
inactive:
- "&8Set: Dragon Slayer &c[Inactive]"
- "&8(2) +15 Attack Damage, +10% Crit Rate"
- "&8(4) +35 Attack Damage, +50% Crit Damage, +20 PvP Damage"
bonuses:
2:
attack-damage: 15.0
crit-rate: 10.0
4:
attack-damage: 35.0
crit-damage: 50.0
pvp-damage: 20.0
📄 点击展开:items/SWORD.yml(示例近战武器定义)
items:
excalibur:
type: SWORD
name: "<gradient:#FFD700:#FFA500>Excalibur</gradient>"
material: NETHERITE_SWORD
item-tier: LEGENDARY
item-set: dragon_slayer
item-model: "royitems:weapon/excalibur"
unbreakable: true
stats:
attack-damage:
flat: 35.0
percent: 0.15
critical-rate:
flat: 20.0
critical-damage:
flat: 50.0
life-steal:
flat: 5.0
gem-sockets:
max: 3
enchantments:
sharpness: 6
unbreaking: 3
requirements:
level: 50
permission: "royitems.equip.excalibur"
lore-format: "weapon"
📄 点击展开:items/ARMOR.yml(示例 2D 自定义护甲定义)
items:
galaxy_chestplate:
type: ARMOR
name: "<gradient:#9B5DE5:#F15BB5>Galaxy Chestplate</gradient>"
material: NETHERITE_CHESTPLATE
item-tier: MYTHIC
item-set: dragon_slayer
# Minecraft 1.21+ 可装备组件模型(Nexo 资源包资产)
equipment-model: "nexo:galaxy_chestplate"
stats:
defense:
flat: 45.0
percent: 0.10
max-health:
flat: 30.0
pve-defense:
flat: 15.0
gem-sockets:
max: 2
unbreakable: true
lore-format: "armor"
📄 点击展开:items/VOUCHER.yml(示例标题抽奖券)
items:
money_pouch:
type: VOUCHER
name: "<gradient:#00F5D4:#00BBF9>Mysterious Money Pouch</gradient>"
material: PAPER
item-tier: RARE
custom-model-data: 1005
reward:
currency: "VAULT"
min: 1000.0
max: 50000.0
commands:
- "broadcast &aPlayer &e#player# &ajust unboxed &6$#amount# &afrom a Money Pouch!"
cooldown: 5
📄 点击展开:crafting-station/blacksmith.yml(自定义合成站)
title: "<gold><bold>Royal Blacksmith</bold></gold>"
size: 54
# 与 NPC 插件直接集成(右键点击 NPC 打开)
fancynpcs:
- "blacksmith_npc"
citizens:
- 10
phoenixnpcs:
- "blacksmith_npc"
navigation:
prev-page:
slot: 48
material: SPECTRAL_ARROW
name: "<#FFD166>◀ 上一页</#FFD166>"
next-page:
slot: 50
material: SPECTRAL_ARROW
name: "<#FFD166>下一页 ▶</#FFD166>"
recipes:
forge_excalibur:
slot: 22
output:
type: SWORD
id: excalibur
amount: 1
ingredients:
- material: NETHERITE_INGOT
amount: 8
- material: DIAMOND_BLOCK
amount: 4
- custom-item:
type: MATERIAL
id: dragon_core
amount: 1
cost:
vault: 50000.0
playerpoints: 500
📄 点击展开:lore-format/default.yml (背景文本模板布局)
format:
- "&7类型: &f#type#"
- "#bar#"
- "#stats#"
- "#bar#"
- "#sockets#"
- "#bar#"
- "#description#"
- "#bar#"
- "#requirements#"
- "#bar#"
- "&8#tier#"
stat-format:
positive: "&7#name#: &a+#value#"
negative: "&7#name#: &c-#value#"
percentage-positive: "&7#name#: &a+#value#%"
percentage-negative: "&7#name#: &c-#value#%"
bar: "&8&m------------------------"
🔌 集成支持
RoyItems 完全独立运行,无需任何依赖项。当服务器中存在以下插件时,RoyItems 会自动挂钩其官方 API 以激活扩展功能:
1. 💰 经济 & 货币提供商
2. ⚡ 数据包 & 核心优化
- PacketEvents: Modrinth 官方 — 高速数据包拦截器和客户端装备同步。
- ProtocolLib: GitHub 官方发布 — 异步数据包监听、训练假人数据包和自定义库存标题。
- PlaceholderAPI: 官方下载 — 背景文本中的通用占位符解析、凭证命令以及
%royitems_<stat>%。
3. ⚔️ RPG、技能 & 战斗引擎
4. 🌍 世界管理与领地
5. 🎨 自定义模型、纹理 & 物品
6. 👥 NPC 系统(制作站触发器)
7. 📦 挖矿、生成器与权限
- ExtraStorage: Modrinth 官方 — 为
mine-radius(挖矿半径)和存储材料合成提供直接零延迟的掉落物 deposit。
- AdvancedOreGen: SpigotMC 历史列表 — 在广域挖矿期间,用于 SkyBlock 圆石/栅栏生成器的原地矿石再生。(注:此处引用的是历史列表资源)。
- LuckPerms: 官方下载 — 基于动态权限的玩家数据统计及自动组统计继承。
📈 插件统计数据
RoyItems 通过 bStats(插件 ID:34832)收集完全匿名的使用遥测数据。
绝不会收集或传输任何敏感的玩家或服务器数据。遥测数据追踪以下内容:
- 活跃服务器软件(Paper / Folia / Purpur / Spigot)
- Minecraft 与 Java 运行时版本
- 注册的自定义物品总数及各原型(Archetype)的物品数量
- 活跃的生态集成模块(15 个已验证模块)
- 战斗防御模式(MMORPG / Simple / Custom)
👉 在 bStats 官方仪表板查看完整统计数据
(服务器管理员可以随时通过在 plugins/bStats/config.yml 中设置 enabled: false 来退出遥测数据收集)。
💬 社区与源代码
🔗 在 GitHub 上查看源代码与问题反馈
•
💬 加入官方社区并在 Discord 获取支持
由 .monleo 为全球 Minecraft 服务器创作者用心打造 ❤️
⚔️ RoyItems — Advanced MMORPG Custom Items Engine
🌟 OVERVIEW
Welcome to RoyItems, the high-performance, modern MMORPG Custom Items and Attributes Engine engineered specifically for Minecraft 1.21+ servers running on Paper, Purpur, Folia, Leaf, and Spigot.
Whether you run a massive SkyBlock network, a hardcore MMORPG realm, a competitive Factions server, or a tight-knit Survival community, RoyItems delivers unprecedented power, flexibility, and architectural reliability.
💡 Why RoyItems Stands Apart
- 🚀 100% Standalone Architecture: Operates with ZERO required dependencies. No bloated prerequisite libraries or forced framework dependencies—just drop the JAR in and play.
- ⚡ Folia & Leaf Native Multi-Threading: Built around asynchronous data parsing and region-aware scheduling (
PlatformScheduler). Large-scale operations, wide-area mining, and real-time inventory updates run smoothly with zero region thread stalls or tick lag.
- 🛡️ Zero NMS Reflection: Built strictly on clean, forward-compatible Paper APIs and PersistentDataContainer (PDC) storage. Updates smoothly across Minecraft minor versions without breaking item data or waiting weeks for reflection patches.
- ⚔️ Independent MMORPG Stat & Defense Calculations: Features 17 custom stats that scale deterministically:
$$\text{Total Stat} = (\text{Base} + \sum \text{Flat}) \times \left(1 + \sum \text{Percent}\right)$$
Operates without interfering with vanilla Minecraft armor limits, toughness caps, or attribute modifier caps.
- 🔄 Hot-Reload LiveUpdate: Modify item configurations, tiers, lore formats, or crafting recipes on the fly. Running
/ri reload automatically updates existing items across online player inventories, armor slots, offhands, and enderchests while preserving custom durability, slotted gems, and enchantments.
- 🎨 Minecraft 1.21+ Equippable Component Support: Native support for modern Equippable components, seamlessly rendering 2D custom armor models from Nexo and custom resource packs directly onto player character models.
🚀 FEATURES
RoyItems is engineered with a modular suite of gameplay mechanics designed to elevate your server's player progression and economy:
1. 📦 14 Specialized Item Archetypes
Every custom item is assigned a functional type governing where it can be equipped, how it activates, and what rules apply:
- Melee & Ranged Weapons:
SWORD, BOW, CROSSBOW, and STAFF with custom attack speed, critical strike scaling, arrow velocity, and right-click magic casting.
- Defensive Gear & Vanity:
ARMOR (Head, Chest, Legs, Feet) supporting 2D custom equipment models, OFF_HAND (Shields/Orbs), WING (Gliders/Elytra), and COSMETIC items.
- Harvesting & Excavation:
TOOL archetypes supporting wide-area horizontal slicing (mine-radius).
- Progression, Economy & Sockets:
GEM_STONE for socketing, TALISMAN for passive inventory stat boosts, CONSUMABLE for food and potion buffs, MATERIAL for crafting recipes, and VOUCHER for interactive currency rewards.
2. ⛏️ Wide-Area Mine Radius with Zero Entity Lag
- Strict Horizontal 2D Slicing ($Y = Y_0$): Mines only on the horizontal layer around the broken block (Tier 1: $3\times 3$, Tier 2: $5\times 5$, Tier 3: $7\times 7$, Tier 4: $9\times 9$, Tier 5: $11\times 11$). Never carves deep vertical holes or breaks ceiling/floor builds accidentally.
- Ghost Block Elimination: Immediately broadcasts authoritative multi-client
sendBlockChange packets within a 48-block radius, followed by a 1-tick delayed post-physics verification on the Region Scheduler.
- AdvancedOreGen In-Place Regeneration: Detects SkyBlock generator blocks (fence-water, cobble, basalt) and triggers in-place ore regeneration via AdvancedOreGen without turning blocks into AIR, protecting fluid flows from turning into obsidian.
- Direct ExtraStorage Batching: Deposits all collected drops directly into the player's ExtraStorage vault in memory, bypassing ground item entities and completely eliminating entity drop lag spikes.
- Thread-Safe Active Mining Locks: Concurrently locks active coordinates to prevent duplicate block breaks, item duplication exploits, or fluid physics lockups when multiple players mine simultaneously.
3. 🎁 Animated Title Gacha & Multi-Currency Vouchers
- Air & Block Interaction: Right-click anywhere—into the open air or against a block—with either the Main Hand or Off Hand to activate vouchers without targeting entities.
- Dynamic Title Animation: Displays a rolling title sequence with customizable sound effects, particle bursts, and dynamic pitches before revealing the awarded prize.
- Multi-Currency Deposits: Direct integration with Vault (Money), PlayerPoints (Points), and ExcellentEconomy (multi-currency balances).
- Safe Atomic Transactions: If an economy provider is unreachable or a transaction fails, the voucher is refunded automatically with zero item loss.
- Command Automation: Execute multiple console or player commands sequentially with placeholder support (
#player#, #amount#, #currency#).
4. 💎 Real-Time Dynamic Lore & Set Bonuses
- Dynamic Lore Engine: Lore updates on the fly when equipping, enchanting, or socketing gems. Supports MiniMessage, Hex colors (
&#RRGGBB), and legacy formatting.
- Dynamic
#set# Lore: Armor set items dynamically switch between active and inactive set bonus descriptions in real time as pieces are equipped or unequipped.
- Gem Socketing: Configurable socket counts (
sockets: 3), allowed gem types, and interactive drag-and-drop or socketing table GUIs.
5. 🎯 Packet-Based Training Dummies & DPS Meters
- Virtual Combat Testing: Spawn packet-based combat training dummies (
/ri dummy spawn <id> [mob_type]) to test real player damage, critical strikes, and weapon DPS.
- Floating Holographic Meters: Real-time floating holograms display current strike damage, maximum damage, and DPS over 5-second intervals.
- Zero Entity Lag: Dummies use virtual packet entities, requiring no persistent entity ticking or AI pathfinding calculations.
6. 🛠️ Ingame Interactive GUI Editor
- Open the comprehensive GUI editor with
/ri edit to browse, inspect, create, and configure custom items directly in-game without touching raw YAML files.
📥 INSTALLATION
Setting up RoyItems takes less than 60 seconds:
- Verify Requirements:
- Server Software: Paper, Purpur, Folia, Leaf, or Spigot (Minecraft 1.21+).
- Java Runtime: Java 21 or newer.
- Download Release:
- Download the latest
RoyItems-2026.1.8.jar from Modrinth.
- Verify Dependencies:
- RoyItems has ZERO required dependencies. You do not need to install any external libraries.
- If you wish to use economy features, skills, or custom models, ensure your optional soft dependencies (e.g. Vault, Nexo, ExtraStorage) are installed.
- Place in Plugins Directory:
- Place
RoyItems-2026.1.8.jar into your server's plugins/ folder.
- Start Your Server:
- Boot or restart your server. Check console for:
[RoyItems] Initializing RoyItems v2026.1.8...
[RoyItems] Successfully loaded custom items and crafting stations.
- Customize Configurations:
- RoyItems automatically generates clean, default configurations in
plugins/RoyItems/.
- Edit settings via YAML or in-game using
/ri edit. Apply changes instantly with /ri reload.
- Troubleshooting Tips:
- UnsupportedClassVersionError: Ensure your startup script uses Java 21+ (
java -version).
- Permission Denied: Ensure your permission plugin (e.g. LuckPerms) assigns
royitems.admin to server administrators.
💻 COMMANDS
RoyItems provides an intuitive command system under /royitems (shorthand alias: /ri):
| Command Syntax |
Arguments & Parameters |
Required Permission |
Description |
/ri help |
[page] |
royitems.command.help |
View interactive command help and usage instructions. |
/ri reload |
— |
royitems.command.reload |
Reload all configurations, items, language, and run LiveUpdate. |
/ri editor |
— |
royitems.command.editor |
Open the interactive Ingame GUI Item & Station Editor. |
/ri checkupdate |
— |
royitems.command.checkupdate |
Check for new RoyItems releases on Modrinth. |
/ri give |
<player|all> <type> <id> [amt] |
royitems.command.give |
Give custom items directly to a player or all online players. |
/ri take |
<player|all> <type> <id> [amt] |
royitems.command.take |
Remove custom items from a player or all online players. |
/ri drop |
<player|all> <type> <id> [amt] |
royitems.command.drop |
Drop custom items at a player's location. |
/ri drop |
<world> <x> <y> <z> <type> <id> [amt] |
royitems.command.drop |
Drop custom items at exact world coordinates. |
/ri station open |
<id> [player] |
royitems.command.station.open |
Open a specific Crafting Station GUI for yourself or a target player. |
/ri station list |
— |
royitems.command.station.list |
Open the interactive Crafting Station list overview GUI. |
/ri station create |
<id> |
royitems.command.station.create |
Generate a new crafting station template file in crafting-station/. |
/ri station delete |
<id> |
royitems.command.station.delete |
Permanently delete a crafting station and remove its YAML file. |
/ri dummy spawn |
<id> [mob_type] |
royitems.command.dummy |
Spawn a virtual packet-based DPS training dummy at your location. |
/ri dummy despawn |
<id|all> |
royitems.command.dummy |
Despawn a specific training dummy or all active dummies. |
🔑 PERMISSIONS
⚡ Dynamic Permission Stats (LuckPerms Integration)
Grant flat or percentage attribute bonuses directly to player ranks or groups without requiring players to wear or hold items:
royitems.player.stats.<stat>.<value> # Flat value boost (e.g. +25 Defense)
royitems.player.stats.<stat>.<value>% # Percentage boost (e.g. +15% Attack Damage)
| Permission Node Example |
Target Stat |
Applied Effect |
royitems.player.stats.attack-damage.10 |
Attack Damage |
Grants +10 flat attack damage to all melee attacks. |
royitems.player.stats.max-health.40 |
Max Health |
Grants +40 flat maximum health (2 full extra rows of hearts). |
royitems.player.stats.defense.25 |
Defense |
Grants +25 flat defense mitigation against incoming damage. |
royitems.player.stats.crit-rate.15% |
Critical Rate |
Increases critical strike chance by +15%. |
royitems.player.stats.movement-speed.10% |
Movement Speed |
Grants +10% movement speed boost across all worlds. |
royitems.player.stats.pvp-damage.12% |
PvP Damage |
Increases damage dealt against players by +12%. |
royitems.player.stats.generic.scale.1.2 |
Vanilla Scale |
Increases player model size by 20% (Minecraft 1.21+ attribute). |
🛡️ Administrative & Command Permissions
| Permission Node |
Description |
Default Access |
royitems.admin |
Full wildcard access to all RoyItems commands, editor menus, and bypasses. |
OP Only |
royitems.command.help |
Permission to view /ri help. |
OP Only |
royitems.command.reload |
Permission to reload configurations via /ri reload. |
OP Only |
royitems.command.editor |
Permission to access the in-game GUI editor via /ri editor. |
OP Only |
royitems.command.checkupdate |
Permission to check plugin version via /ri checkupdate. |
OP Only |
royitems.command.give |
Permission to give custom items via /ri give. |
OP Only |
royitems.command.take |
Permission to revoke custom items via /ri take. |
OP Only |
royitems.command.drop |
Permission to drop items at players or coordinates via /ri drop. |
OP Only |
royitems.command.station |
Parent permission for all crafting station management commands. |
OP Only |
royitems.command.station.open |
Permission to open crafting stations via /ri station open. |
OP Only |
royitems.command.station.list |
Permission to list all crafting stations via /ri station list. |
OP Only |
royitems.command.station.create |
Permission to create crafting stations via /ri station create. |
OP Only |
royitems.command.station.delete |
Permission to delete crafting stations via /ri station delete. |
OP Only |
royitems.command.dummy |
Permission to spawn or despawn combat training dummies. |
OP Only |
royitems.item.expired.bypass |
Bypass expiration date restrictions on timed custom items. |
OP Only |
royitems.station.<station_id> |
Permission required to access a specific crafting station if configured. |
Configurable |
royitems.item.use.<type>.<id> |
Permission requirement to wield or consume an item if configured. |
Configurable |
🏷️ PLACEHOLDERS
🌐 PlaceholderAPI Integration (%royitems_...%)
RoyItems provides a built-in PlaceholderAPI expansion for HUDs, Scoreboards, TAB lists, and chat plugins:
| Placeholder |
Return Value |
Description |
%royitems_stat_<stat>% |
Number (e.g. 125.5) |
Returns player's calculated total value for <stat> (Gear + Perms). |
%royitems_stat_attack-damage% |
Number (e.g. 45.0) |
Returns total melee attack damage. |
%royitems_stat_defense% |
Number (e.g. 80.0) |
Returns total defense mitigation value. |
%royitems_stat_max-health% |
Number (e.g. 60.0) |
Returns player's maximum health attribute. |
%royitems_stat_crit-rate% |
Number (e.g. 25%) |
Returns player's critical strike probability percentage. |
%royitems_stat_mine-radius% |
Number (e.g. 2) |
Returns current wide-area horizontal mining radius level. |
%royitems_hand_type% |
String (e.g. SWORD) |
Returns the custom ItemType of the item held in the Main Hand. |
%royitems_hand_id% |
String (e.g. excalibur) |
Returns the unique configuration ID of the held item. |
%royitems_hand_name% |
Text (e.g. Excalibur) |
Returns the formatted display name of the held item. |
%royitems_hand_tier% |
String (e.g. LEGENDARY) |
Returns the rarity tier ID of the held item. |
%royitems_hand_version% |
Number (e.g. 2) |
Returns the persistent version number of the held item. |
📜 Internal Dynamic Lore Placeholders (lore-format/*.yml)
These placeholders are evaluated in item lore templates and rendered in real time:
| Lore Placeholder |
Rendered Output |
Context / Description |
#name# |
String |
Formatted display name of the item. |
#type# |
String |
Formatted type display name (e.g. Melee Weapon, Armor Equipment). |
#tier# |
String |
Formatted rarity tier name (e.g. &6Legendary). |
#tier-color# |
Color code |
Color formatting code assigned to the item's tier. |
#set# |
Text block |
Dynamic Item Set lore (switches between active and inactive set bonus). |
#set-name# |
String |
Official display name of the assigned Item Set. |
#lore# |
Text lines |
User-defined custom item description lines. |
#stats# |
Block of lines |
Rendered MMORPG stats list formatted according to stat-format.yml. |
#stat_<stat_name># |
Number |
Direct value of a specific stat on the item. |
#enchantments# |
Block of lines |
Formatted enchantments list (supports Vanilla & EcoEnchants). |
#sockets# |
Block of lines |
Visual socket indicators with filled gem details and empty slots. |
#requirements# |
Block of lines |
Level, class, and permission requirements with dynamic satisfied coloring. |
#durability# |
String |
Current custom durability vs max durability (e.g. 1,250/1,500). |
#bar# |
String |
Visual divider or progress bar defined in lore formatting templates. |
#cooldown# |
String |
Cooldown duration in seconds for staves, consumables, or vouchers. |
#expiration# |
String |
Expiration countdown timer or date for temporary items. |
#mine-radius# |
String (e.g. 3×3) |
Formatted horizontal area slicing dimension. |
#unbreakable# |
String |
Unbreakable tag indicator if item is configured unbreakable. |
📦 ITEM TYPES
RoyItems supports 14 distinct item types, each with strict equipment slot validation:
| Item Type |
Default Slot |
Valid Equipment Slots |
Primary Role & Special Mechanics |
SWORD |
HAND |
HAND (Main Hand) |
Melee combat weapons. Grants offensive combat stats, life-steal, and crit. |
ARMOR |
Auto |
HEAD, CHEST, LEGS, FEET |
Defensive equipment. Supports Equippable 2D models, defense stats, and set bonuses. |
BOW |
HAND |
HAND (Main Hand) |
Ranged bows. Applies arrow damage, draw speed multipliers, and ranged crits. |
CROSSBOW |
HAND |
HAND (Main Hand) |
Heavy ranged crossbows with custom piercing and projectile stats. |
STAFF |
HAND |
HAND (Main Hand) |
Magical casting staves. Supports right-click spell casting, mana costs, and cooldowns. |
TOOL |
HAND |
HAND (Main Hand) |
Excavation tools (Pickaxes, Axes, Shovels, Hoes) with mine-radius slicing. |
GEM_STONE |
None |
Socket Only |
Socketable gems embedded into gear to boost flat or percentage stats. |
CONSUMABLE |
HAND |
HAND (Main Hand) |
Edible items applying custom potion effects and health restoration with cooldowns. |
MATERIAL |
None |
Inventory / Recipe |
Specialized ingredients used in Crafting Station recipes. |
OFF_HAND |
OFF_HAND |
OFF_HAND (Offhand) |
Defensive shields, magical orbs, and secondary offhand stat boosters. |
WING |
CHEST |
CHEST (Chestplate) |
Gliders and Elytras supporting custom durability and flight attributes. |
VOUCHER |
HAND |
HAND, OFF_HAND (Air & Block) |
Consumable reward scrolls granting currency, commands, and title gacha. |
PET |
None |
Inventory / Companion |
Companion items providing utility perks and aesthetic effects. |
TALISMAN |
None |
Passive Inventory |
Accessory charms granting passive stats simply by sitting in player inventory. |
📊 ITEM STATS
RoyItems includes 17 built-in MMORPG stats, categorized into combat, defense, utility, and world interaction:
| Stat Identifier |
Default Icon & Name |
Modifier Type |
Vanilla Mapping |
Gameplay Function & Mechanics |
attack-damage |
⚔ Attack Damage |
Flat / % |
generic.attack_damage |
Base physical damage dealt during melee attacks. |
arrow-damage |
🏹 Arrow Damage |
Flat / % |
None (Custom) |
Bonus damage applied to arrows fired from bows and crossbows. |
max-health |
❤ Max Health |
Flat / % |
generic.max_health |
Increases player maximum health hearts smoothly. |
attack-speed |
⚡ Attack Speed |
Flat / % |
generic.attack_speed |
Weapon swing recovery speed and combat strike frequency. |
crit-rate |
🎯 Critical Rate |
Flat / % |
None (Custom) |
Percentage probability (0% to 100%) to score a critical strike. |
crit-damage |
💥 Critical Damage |
Flat / % |
None (Custom) |
Bonus damage multiplier applied upon triggering a critical strike. |
defense |
🛡 Defense |
Flat / % |
None (Custom) |
Independent MMORPG defense formula mitigating all incoming damage. |
pvp-damage |
⚔ PvP Damage |
Flat / % |
None (Custom) |
Extra damage dealt exclusively against other players in PvP. |
pve-damage |
🗡 PvE Damage |
Flat / % |
None (Custom) |
Extra damage dealt exclusively against hostile monsters and dungeon mobs. |
pvp-defense |
🛡 PvP Defense |
Flat / % |
None (Custom) |
Damage mitigation applied exclusively when taking damage from players. |
pve-defense |
🛡 PvE Defense |
Flat / % |
None (Custom) |
Damage mitigation applied exclusively when taking damage from mobs. |
damage-reduction |
🔰 Damage Reduction |
Flat / % |
None (Custom) |
Direct flat percentage reduction applied to final incoming damage. |
armor |
🛡 Armor |
Flat / % |
generic.armor |
Vanilla Minecraft armor defense value. |
armor-toughness |
🛡 Armor Toughness |
Flat / % |
generic.armor_toughness |
Vanilla Minecraft armor toughness mitigating high-damage blows. |
knockback-resistance |
🏋 Knockback Res |
Flat / % |
generic.knockback_resistance |
Resistance to physical knockback from strikes and explosions. |
movement-speed |
👟 Movement Speed |
Flat / % |
generic.movement_speed |
Player walking and sprinting speed multiplier. |
mine-radius |
⛏ Mine Radius |
Level (1–5+) |
None (Custom) |
Horizontal 2D plane area mining dimension (Level 1: $3\times 3$, Level 2: $5\times 5$). |
⚙️ CONFIGURATION
RoyItems organizes configurations in a modular, clean YAML directory structure inside plugins/RoyItems/:
plugins/RoyItems/
├── config.yml # Core plugin settings, combat formulas, performance, and updates
├── item-tier.yml # Item rarity tiers, custom chat colors, and drop glow outlines
├── item-set.yml # Armor set bonuses, equipment thresholds, and dynamic lore
├── items/ # Modular item definition files grouped by archetype
│ ├── SWORD.yml # Melee swords and daggers
│ ├── ARMOR.yml # Helmets, chestplates, leggings, and boots
│ ├── BOW.yml # Ranged bows
│ ├── CROSSBOW.yml # Ranged crossbows
│ ├── STAFF.yml # Magic staves
│ ├── TOOL.yml # Harvesting tools (Pickaxes, Shovels, Axes, Hoes)
│ ├── GEM_STONE.yml # Socketable jewels and runes
│ ├── CONSUMABLE.yml # Food and potion consumables
│ ├── TALISMAN.yml # Passive inventory charms
│ ├── VOUCHER.yml # Economy, reward, and command scrolls
│ └── WING.yml # Elytras and gliders
├── crafting-station/ # Custom Crafting Station files with recipe chains & NPC links
│ └── blacksmith.yml # Sample multi-page Blacksmith station
├── lore-format/ # Universal and per-type lore formatting templates
│ ├── default.yml # Universal fallback lore template
│ ├── weapon.yml # Weapon-specific lore layout
│ └── armor.yml # Armor-specific lore layout
├── gui/ # Ingame GUI layouts for menus and station browsers
│ ├── editor-gui.yml # Ingame item editor GUI
│ ├── crafting-station-list.yml
│ └── crafting-station-detail.yml
└── lang/ # Multi-language localization files
├── en-US.yml # English (US)
├── vi-VN.yml # Vietnamese (Tiếng Việt)
├── de-DE.yml # German (Deutsch)
├── es-ES.yml # Spanish (Español)
├── ja-JP.yml # Japanese (日本語)
├── ko-KR.yml # Korean (한국어)
└── ru-RU.yml # Russian (Русский)
Below are standard default configurations. Click each section to expand:
📄 Click to expand: config.yml (Core Settings & Combat Engine)
# ==============================================================================
# ROYITEMS — CONFIGURATION ENGINE
# ==============================================================================
config-version: 2
# General settings
debug: false
# Active localization language:
# Supported: en-US, vi-VN, de-DE, ja-JP, ko-KR, ru-RU, es-ES
language: en-US
# Provider preference when multiple MMORPG providers exist (MMOCore, AuraSkills, Auto)
mana-provider: Auto
# Performance tuning
performance:
# Frequency in seconds for item expiration check (low overhead)
expiration-check-interval: 20
# Frequency in seconds for periodic potion effect application
potion-effect-interval: 3
# ==============================================================================
# UPDATE CHECKER (Checks Modrinth for new releases)
# ==============================================================================
update-checker:
enabled: true
notify-admins-on-join: true
# ==============================================================================
# COMBAT & CUSTOM DEFENSE SYSTEM
# ==============================================================================
combat:
defense:
# Mode: MMORPG, SIMPLE, or CUSTOM_LIMIT
mode: MMORPG
# MMORPG formula: damage = rawDamage * (100 / (100 + defense))
mmorpg-constant: 100.0
# Custom limit mode settings
custom-limit:
defense-cap: 500.0
max-reduction-percentage: 80.0
# Mitigate incoming damage from MythicMobs skill mechanics
mitigate-mythic-skills: true
# ==============================================================================
# LIVE UPDATE SYSTEM (Updates items across player inventories on /ri reload)
# ==============================================================================
live-update:
enabled: true
preserve:
enchantments: true
gems: true
durability: true
custom-lore: true
display-name: false
lore: false
tier: false
# ==============================================================================
# MINE RADIUS MECHANICS & ADVANCED ORE GEN INTEGRATION
# ==============================================================================
mine-radius:
enabled: true
activation-chance: 100.0
cooldown-ms: 0
limits:
max-radius-tier: 5
max-blocks-per-break: 150
extra-storage:
auto-deposit: true
drop-leftover-to-world: true
advanced-ore-gen:
auto-regenerate: true
# ==============================================================================
# VOUCHER GACHA & CURRENCY MAPPING
# ==============================================================================
voucher:
gacha:
enabled: true
duration-ticks: 30
interval-ticks: 2
sound-roll: "BLOCK_NOTE_BLOCK_PLING"
sound-finish: "UI_TOAST_CHALLENGE_COMPLETE"
particle: "FIREWORK"
particle-count: 35
currencies:
vault:
name: "Money"
symbol: "$"
format: "#,##0.##"
playerpoints:
name: "Points"
symbol: "✪"
format: "#,##0"
📄 Click to expand: item-tier.yml (Rarity Tiers & Glow Outlines)
# ==============================================================================
# ROYITEMS — ITEM TIER CONFIGURATION
# ==============================================================================
config-version: 2
common:
display-name: "&fCommon"
color: "&f"
weight: 1
drop-color: WHITE
uncommon:
display-name: "&aUncommon"
color: "&a"
weight: 2
drop-color: GREEN
rare:
display-name: "&9Rare"
color: "&9"
weight: 3
drop-color: BLUE
epic:
display-name: "&5Epic"
color: "&5"
weight: 4
drop-color: DARK_PURPLE
legendary:
display-name: "&6Legendary"
color: "&6"
weight: 5
drop-color: GOLD
mythic:
display-name: "&dMythic"
color: "&d"
weight: 6
drop-color: RED
📄 Click to expand: item-set.yml (Dynamic Set Bonus & Lore)
# ==============================================================================
# ROYITEMS — ITEM SET CONFIGURATION
# ==============================================================================
dragon_slayer:
display-name: "&6Dragon Slayer Set"
required-pieces: 2
lore:
active:
- "&6Set: Dragon Slayer &a[Active]"
- "&7(2) &a+15 Attack Damage, +10% Crit Rate"
- "&7(4) &a+35 Attack Damage, +50% Crit Damage, +20 PvP Damage"
inactive:
- "&8Set: Dragon Slayer &c[Inactive]"
- "&8(2) +15 Attack Damage, +10% Crit Rate"
- "&8(4) +35 Attack Damage, +50% Crit Damage, +20 PvP Damage"
bonuses:
2:
attack-damage: 15.0
crit-rate: 10.0
4:
attack-damage: 35.0
crit-damage: 50.0
pvp-damage: 20.0
📄 Click to expand: items/SWORD.yml (Sample Melee Weapon Definition)
items:
excalibur:
type: SWORD
name: "<gradient:#FFD700:#FFA500>Excalibur</gradient>"
material: NETHERITE_SWORD
item-tier: LEGENDARY
item-set: dragon_slayer
item-model: "royitems:weapon/excalibur"
unbreakable: true
stats:
attack-damage:
flat: 35.0
percent: 0.15
critical-rate:
flat: 20.0
critical-damage:
flat: 50.0
life-steal:
flat: 5.0
gem-sockets:
max: 3
enchantments:
sharpness: 6
unbreaking: 3
requirements:
level: 50
permission: "royitems.equip.excalibur"
lore-format: "weapon"
📄 Click to expand: items/ARMOR.yml (Sample 2D Custom Armor Definition)
items:
galaxy_chestplate:
type: ARMOR
name: "<gradient:#9B5DE5:#F15BB5>Galaxy Chestplate</gradient>"
material: NETHERITE_CHESTPLATE
item-tier: MYTHIC
item-set: dragon_slayer
# Minecraft 1.21+ Equippable Component model (Nexo resource pack asset)
equipment-model: "nexo:galaxy_chestplate"
stats:
defense:
flat: 45.0
percent: 0.10
max-health:
flat: 30.0
pve-defense:
flat: 15.0
gem-sockets:
max: 2
unbreakable: true
lore-format: "armor"
📄 Click to expand: items/VOUCHER.yml (Sample Title Gacha Voucher)
items:
money_pouch:
type: VOUCHER
name: "<gradient:#00F5D4:#00BBF9>Mysterious Money Pouch</gradient>"
material: PAPER
item-tier: RARE
custom-model-data: 1005
reward:
currency: "VAULT"
min: 1000.0
max: 50000.0
commands:
- "broadcast &aPlayer &e#player# &ajust unboxed &6$#amount# &afrom a Money Pouch!"
cooldown: 5
📄 Click to expand: crafting-station/blacksmith.yml (Custom Crafting Station)
title: "<gold><bold>Royal Blacksmith</bold></gold>"
size: 54
# Direct integration with NPC plugins (Open by right-clicking NPC)
fancynpcs:
- "blacksmith_npc"
citizens:
- 10
phoenixnpcs:
- "blacksmith_npc"
navigation:
prev-page:
slot: 48
material: SPECTRAL_ARROW
name: "<#FFD166>◀ Previous Page</#FFD166>"
next-page:
slot: 50
material: SPECTRAL_ARROW
name: "<#FFD166>Next Page ▶</#FFD166>"
recipes:
forge_excalibur:
slot: 22
output:
type: SWORD
id: excalibur
amount: 1
ingredients:
- material: NETHERITE_INGOT
amount: 8
- material: DIAMOND_BLOCK
amount: 4
- custom-item:
type: MATERIAL
id: dragon_core
amount: 1
cost:
vault: 50000.0
playerpoints: 500
📄 Click to expand: lore-format/default.yml (Lore Template Layout)
format:
- "&7Type: &f#type#"
- "#bar#"
- "#stats#"
- "#bar#"
- "#sockets#"
- "#bar#"
- "#description#"
- "#bar#"
- "#requirements#"
- "#bar#"
- "&8#tier#"
stat-format:
positive: "&7#name#: &a+#value#"
negative: "&7#name#: &c-#value#"
percentage-positive: "&7#name#: &a+#value#%"
percentage-negative: "&7#name#: &c-#value#%"
bar: "&8&m------------------------"
🔌 INTEGRATIONS
RoyItems runs completely standalone with ZERO required dependencies. When any of the following plugins are present on your server, RoyItems automatically hooks into their official APIs to activate extended capabilities:
1. 💰 Economy & Currency Providers
- Vault: SpigotMC Official — Server economy balances, crafting costs, and monetary voucher rewards.
- PlayerPoints: SpigotMC Official — Point currency transactions, gacha vouchers, and recipe point costs.
- ExcellentEconomy: SpigotMC Official — Multi-currency economy support, custom currency vouchers, and symbols.
2. ⚡ Packets & Core Optimization
- PacketEvents: Modrinth Official — High-speed packet interceptor and client-side equipment synchronization.
- ProtocolLib: GitHub Official Releases — Asynchronous packet listening, training dummy packets, and custom inventory titles.
- PlaceholderAPI: Official Downloads — Universal placeholder parsing in lore, voucher commands, and
%royitems_<stat>%.
3. ⚔️ RPG, Skills & Combat Engines
- MythicMobs: MythicCraft Official — Intercepts Mythic skill mechanic damage with MMORPG defense mitigation.
- MMOCore: SpigotMC Official — Player level, class requirements, and combat stat formulas.
- AuraSkills: Modrinth Official — Skill level requirements and RPG attribute stat synchronization.
- EcoEnchants: GitHub Official Releases — Resolves EcoEnchants custom enchantments inside
#enchantments# lore.
4. 🌍 World Management & Claims
- WorldGuard: EngineHub Official — Region flags, block-break protection, and combat safety checks.
- WorldEdit: EngineHub Official — Selection handling and schematic generation.
- FastAsyncWorldEdit: Modrinth Official — Asynchronous world modifications and zero-lag schematic loading.
5. 🎨 Custom Models, Textures & Items
- Nexo: NexoMC Official — Full custom item models, glyph GUI titles, and Equippable 2D custom armor models.
- ItemsAdder: ItemsAdder Official — Custom block recognition, custom item model data, and furniture compatibility.
- Oraxen: GitHub Official Releases — Custom item resolution, mechanics compatibility, and model pack IDs.
- HeadDatabase: SpigotMC Official – Arcaniax — Custom player heads for GUI navigation, crafting station icons, and ingredients.
6. 👥 NPC Systems (Crafting Station Triggers)
- Citizens: Citizens Official — Open crafting stations by right-clicking configured Citizens NPC IDs.
- FancyNpcs: Modrinth Official — Open crafting stations via interaction packets with FancyNPCs.
- PhoenixNPCs: Phoenix Plugins Official — Open crafting stations by interacting with configured PhoenixNPCs.
7. 📦 Mining, Generators & Permissions
- ExtraStorage: Modrinth Official — Direct zero-lag drop deposits for
mine-radius and storage ingredient crafting.
- AdvancedOreGen: SpigotMC Historical Listing — In-place ore regeneration for SkyBlock cobble/fence generators during wide-area mining. (Note: Historical listing reference).
- LuckPerms: Official Downloads — Dynamic permission-based player stats and automatic group stat inheritance.
📈 PLUGIN STATISTICS
RoyItems collects completely anonymous usage telemetry via bStats (Plugin ID: 34832).
No sensitive player or server data is ever collected or transmitted. Telemetry tracks:
- Active Server Software (Paper / Folia / Purpur / Spigot)
- Minecraft & Java Runtime Version
- Total Registered Custom Items & Items by Archetype
- Active Ecosystem Integrations (15 verified modules)
- Combat Defense Mode (MMORPG / Simple / Custom)
👉 View Full Statistics on bStats Official Dashboard
(Server administrators can opt out anytime by setting enabled: false in plugins/bStats/config.yml).
💬 COMMUNITY & SOURCE CODE
🔗 View Source Code & Issues on GitHub
•
💬 Join Official Community & Support on Discord
Crafted with ❤️ for Minecraft Server Creators worldwide by .monleo
评论 0
登录后参与评分
还没有评论,来抢沙发吧