MythicCustomizedWeapons 使用文档 - MMOItems 装备强化系统

插件介绍

它不是“改个名字加个星”

源码里会把强化结果写回物品的等级数据、Lore、显示名，以及 MMOItems 的相关 NBT 标签，属于真正改装备数值的强化系统。

MythicCustomizedWeapons 是一个面向 MMOItems + MythicLib 生态的装备强化插件，运行于 Paper 1.20+。玩家通过 /enhance 打开强化 GUI，把可强化的 MMOItems 武器或护甲放进去，再放入强化石、保护石、强化券，就可以进行强化。

从源码行为来看，插件的核心机制是：每次成功强化会从装备当前已有的可强化属性里随机抽取 1 项进行成长；失败时则可能保持不变、降级，或者直接破碎。保护石可以按配置阻止降级/破碎，强化券则按不同券种提高成功率。

插件还提供了强化成功/失败/破碎消息、30/50/80/100 级里程碑全服公告、100 级标题广播、烟花特效、自定义 GUI 布局，以及 ItemsAdder 标题偏移兼容。

说人话：把 MMOItems 装备丢进 GUI，塞强化石，点一下。成了就涨 1 级并随机涨 1 条属性，没成就看配置决定是保级、掉级还是碎掉。

它适合什么服务器

RPG / 刷装服

和 MMOItems 体系天然配套，适合做长期养成、装备追求、材料消耗和战力成长。

经济消耗场景

强化石、保护石、强化券都可以当作商城道具、活动奖励或副本产出，形成稳定的资源回收链。

主要功能

GUI 强化流程：玩家通过图形界面完成装备放入、材料校验、点击强化，不需要记复杂命令。
仅强化 MMOItems 装备：源码会检测 MMOITEMS_ITEM_TYPE 和 MMOITEMS_ITEM_ID 标签，避免原版杂项误入。
随机单属性成长：成功时从物品当前已有且已配置成长规则的属性里随机选 1 项增长。
武器与护甲双模板：武器和护甲有独立的最大等级、成功率、成长公式、降级规则和破碎概率。
保护石机制：可配置失败时防降级、防破碎，以及是否在失败后消耗保护石。
多种强化券：支持多种券种，不同券提供不同成功率加成，适合做普通券、高级券、满成券等梯度。
里程碑公告：默认提供 30、50、80、100 级以及满级公告，100 级还支持全服标题与烟花。
自定义 GUI：强化界面布局、按钮材质、标题文本、动态说明、帮助按钮、消息文本都可改。
ItemsAdder 标题偏移：可选兼容 ItemsAdder 字体偏移；未安装时会自动回退纯文本标题。
强化数据持久化：强化等级与累计成长通过 PersistentDataContainer 保存，并同步更新 Lore / 显示名 / MMOItems NBT。

强化机制

成功时会发生什么

强化等级 +1，并从装备当前已有的可强化属性里随机选择 1 项增长。增长值按照 base + scale * 等级 计算，再被 min / max 限制。随后插件会更新装备名称前缀、Lore、动态属性显示和 MMOItems 相关 NBT。

失败时会发生什么

先判定是否破碎，再判定是否降级；如果两个惩罚都没触发，就是单纯失败但保级。保护石开启时可以按配置阻止降级或破碎。强化券不保底，只负责提高成功率。

项目	默认行为	来源
武器最大强化等级	`100`	`enhance.yml` 的 `weapon.max-level`
护甲最大强化等级	`100`	`enhance.yml` 的 `armor.max-level`
强化石消耗	按等级区间变化	`materials.enhance-stone.cost`
成功率加成	来自强化券	`materials.enhance-coupons.*.success-rate-bonus`
保护效果	防降级 / 防破碎 / 失败消耗	`materials.protection-stone.effects`
里程碑公告	30 / 50 / 80 / 100 / 满级	`enhance_ui.yml` 的 `messages.*`

按源码判断，真正能被强化增长的前提不是“你在配置里写了这个属性”，而是“物品本身就带这个属性标签”。也就是说，这个系统更像是给现有 MMOItems 装备做强化，而不是凭空给装备追加全新属性。

命令列表

主命令：/enhance（别名：/enh、/qianghua）

命令	说明	权限
`/enhance`	打开强化界面	`mythiccustomizedweapons.use` 或 `mythiccustomizedweapons.enhance`
`/enhance open`	打开强化界面	`mythiccustomizedweapons.use` 或 `mythiccustomizedweapons.enhance`
`/enhance help`	显示帮助信息	无额外要求

当前命令实现是玩家专用，控制台无法直接打开 GUI。源码里没有实现 /enhance reload 子命令。

权限节点

权限	说明	默认
`mythiccustomizedweapons.use`	基础使用权限，可打开强化系统	所有玩家
`mythiccustomizedweapons.enhance`	强化权限，可打开强化系统	所有玩家
`mythiccustomizedweapons.reload`	预留的重载权限节点，当前版本未接入对应命令	OP
`mythiccustomizedweapons.*`	全部权限合集	OP

使用教程

安装前置插件

先确保服务器里已经安装 MMOItems 和 MythicLib。缺少任意一个，插件会在启动时自检失败并自动禁用。

放入插件并启动服务器

把 MythicCustomizedWeapons.jar 放进 plugins 目录，首次启动后会自动生成 enhance.yml、enhance_ui.yml 和 ui.yml。

配置强化规则

在 enhance.yml 中设置武器/护甲最大等级、成功率、失败惩罚、成长属性、强化石成本、保护石效果和强化券加成。

准备 MMOItems 材料

根据配置中的 item-type 和 item-id，在 MMOItems 里准备强化石、保护石和强化券物品。

调整强化界面

按需要修改 enhance_ui.yml 中的 GUI 形状、按钮、说明文字、广播格式和标题偏移。

玩家开始强化

玩家输入 /enhance 打开界面，把 MMOItems 装备和材料放入对应槽位后点击强化按钮即可。

强化材料

插件默认围绕 3 类 MMOItems 材料运作：

材料	默认 ID	作用
强化石	`ENHANCE_STONE`	每次强化必耗，数量随目标等级提高
保护石	`PROTECTION_STONE`	可选材料，按配置阻止降级和破碎
强化券	`ENHANCE_COUPON*`	可选材料，提供成功率加成，不负责保底

YAML enhance.yml

materials:
  enhance-stone:
    item-id: ENHANCE_STONE
    item-type: MISCELLANEOUS
    cost:
      1-10: 1
      11-20: 2
      21-30: 3

  protection-stone:
    item-id: PROTECTION_STONE
    item-type: MISCELLANEOUS
    enabled: true
    effects:
      prevent-downgrade: true
      prevent-break: true
      consume-on-failure: true

  enhance-coupons:
    ENHANCE_COUPON:
      item-type: MISCELLANEOUS
      enabled: true
      success-rate-bonus: 10.0
      display-name: '§d普通强化券'

源码支持多种强化券并按物品 ID 识别，所以你可以很方便地做普通券、高级券、完美券、活动券等不同档位。

配置文件

强化逻辑主要配置在 plugins/MythicCustomizedWeapons/enhance.yml。下面是最关键的两个部分。

武器强化模板

YAML enhance.yml

weapon:
  supported-types:
    - SWORD
    - BOW
    - CROSSBOW
    - STAFF
    - WAND
    - DAGGER
    - SPEAR
  max-level: 100
  attribute-growth:
    ATTACK_DAMAGE:
      enabled: true
      base: 0.4
      scale: 0.06
      min: 0.2
      max: 1.0
    CRITICAL_STRIKE_CHANCE:
      enabled: true
      base: 0.2
      scale: 0.02
      min: 0.1
      max: 0.6
  success-rate:
    1-5: 95.0
    6-10: 90.0
    11-15: 85.0

护甲强化模板与失败惩罚

YAML enhance.yml

armor:
  supported-slots:
    - HELMET
    - CHESTPLATE
    - LEGGINGS
    - BOOTS
  max-level: 100
  attribute-growth:
    ARMOR:
      enabled: true
      base: 0.2
      scale: 0.03
      min: 0.1
      max: 0.5
    MAX_HEALTH:
      enabled: true
      base: 0.4
      scale: 0.06
      min: 0.2
      max: 1.0
  failure-penalty:
    downgrade: true
    can-break: true
    downgrade-levels:
      1-10: 1
      11-20: 2
      21-30: 3
    break-chance:
      1-10: 0.0
      21-30: 1.0
      41-50: 3.0

显示与属性名称映射

显示前缀、等级颜色和属性显示名配置在同一个文件里，例如：

YAML enhance.yml

display:
  level-prefix: '§6[+%level%] '
  level-colors:
    1-10: '§a'
    11-20: '§2'
    81-90: '§6'
    91-100: '§c'
  show-level: true
  attribute-names:
    ATTACK_DAMAGE: '攻击伤害'
    CRITICAL_STRIKE_CHANCE: '暴击几率'
    ARMOR: '护甲值'
    MAX_HEALTH: '最大生命值'

GUI 布局

界面配置在 plugins/MythicCustomizedWeapons/enhance_ui.yml。这个文件决定强化 GUI 的标题、槽位布局、按钮样式、动态说明文字和消息广播。

YAML enhance_ui.yml

enhance-gui:
  title_offset_enabled: true
  title: '§f%img_offset_-8%§f武器强化'
  title_offset_amount: 8.0
  fallback_title: '§6§l武器强化系统'
  size: 54

  shape:
    - '#########'
    - '#########'
    - '#W#MSP#I#'
    - '#########'
    - '#H#EEE#C#'
    - '#########'

  buttons:
    'W':
      display-name: '§e§l装备槽'
    'M':
      display-name: '§a§l强化石槽'
    'P':
      display-name: '§b§l保护石槽'
    'S':
      display-name: '§d§l强化券槽'
    'I':
      display-name: '§6§l强化信息'
    'E':
      display-name: '§a§l§n点击强化'

字符	用途
`W`	待强化装备槽
`M`	强化石槽
`P`	保护石槽
`S`	强化券槽
`I`	强化信息展示槽
`E`	强化按钮槽
`H`	帮助按钮
`C`	关闭按钮
`#`	装饰背景槽

ItemsAdder 不是强制依赖。若服务器没装 ItemsAdder，插件会自动移除 %img_offset_-8% 偏移占位并使用普通标题，不会因此报错退出。

依赖插件与环境

组件	是否必须	说明
Paper 1.20.1	必须	插件基于 Paper API 1.20 开发
Java 17+	必须	`pom.xml` 指定使用 Java 17 编译
MMOItems	必须	作为可强化装备与材料的物品来源
MythicLib	必须	提供 NBT 处理与 MMOItems 相关能力
ItemsAdder	可选	仅用于 GUI 标题偏移和更美观的字体展示
PlaceholderAPI	可选	在 Maven 依赖里保留了接口，但当前强化核心流程不依赖它运行

技术信息

项目	信息
插件名称	MythicCustomizedWeapons
版本	1.0
主命令	`/enhance`
命令别名	`/enh`、`/qianghua`
主类	`qq2865348875.mythicCustomizedWeapons.MythicCustomizedWeapons`
配置文件	`enhance.yml`、`enhance_ui.yml`、`ui.yml`
数据存储	`PersistentDataContainer` + MMOItems NBT/Lore 更新
构建方式	Maven + Shade Plugin
核心依赖版本	Paper API 1.20.1 / MythicLib 1.7.1-SNAPSHOT / MMOItems API 6.10-SNAPSHOT

常见问题

因为源码会检查物品是否带有 MMOItems 的类型与 ID 标签。这个插件只服务于 MMOItems 体系，不是给任意原版物品做强化。

不是。按当前源码逻辑，每次成功强化只会从物品当前已有的可强化属性里随机选 1 项增长，所以装备强化路线会带一点随机性。

强化石每次点击都会扣。强化券在成功、失败、降级、破碎这些结果里都会按逻辑消耗 1 个。保护石则只在启用且失败时按 consume-on-failure 配置决定是否消耗。

因为当前版本的 plugin.yml 里确实声明了 mythiccustomizedweapons.reload 权限，但命令执行类只实现了 open 和 help，没有接入真正的 reload 子命令。

不会。ItemsAdder 只是 GUI 标题偏移的可选增强项，未安装时会自动回退为普通标题文本。

如果你要把这个插件上架售卖，卖点别写成“强化系统”就完事。它真正值钱的点是：MMOItems 生态兼容、随机属性成长、材料经济闭环、GUI 可配置、公告与氛围感完整。

MythicCustomizedWeapons ¥288

插件介绍

它不是“改个名字加个星”

它适合什么服务器

RPG / 刷装服

经济消耗场景

主要功能

强化机制

成功时会发生什么

失败时会发生什么

命令列表

权限节点

使用教程

安装前置插件

放入插件并启动服务器

配置强化规则

准备 MMOItems 材料

调整强化界面

玩家开始强化

强化材料

配置文件

武器强化模板

护甲强化模板与失败惩罚

显示与属性名称映射

GUI 布局

依赖插件与环境

技术信息

常见问题