[MD]
```
QuMo
GUI 逐条提取 / 原生附魔书 / 超上限附魔保留 / 物品身份保真 / 内置 36 项自检
不是简单地把附魔一键抹掉，而是一套围绕「把附魔变成附魔书」设计的可配置 GUI 系统。
适用于：生存服 / RPG服 / 养老服 / 经济服 / 附魔强化服 / Paper 与 Leaf 服务端
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
插件简介
QuMo 是一款面向 Paper / Purpur / Leaf 等服务端的 GUI 祛魔插件。
玩家打开 54 格界面，把装备放进中央槽位，界面会扫描出该装备上的全部附魔，
每条附魔显示为一个书本图标；点击勾选要提取的那些，确认后逐条扣费、从装备上移除，
并各自生成一本 Bukkit 原生附魔书放进玩家背包。
两个关键设计：
一、逐条勾选，而不是一键全拆
很多祛魔方案是「把附魔全抹掉」。QuMo 做成逐条勾选 —— 一件装备上有多条附魔时，
可以只取其中一条或几条，剩下的原样留在装备上。这让祛魔从「清空」变成了「挑选」。
二、装备全程留在玩家背包里
装备和槽位里的东西始终不离开玩家的物品栏，GUI 内只是槽位视图；
取走装备、关闭界面、掉线、死亡、插件重载这四条路径都会把装备还回玩家背包，
放不下就掉在脚下。归还时先清空槽位再给物品，顺序不可颠倒，避免复制。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
核心功能
- 逐条勾选提取，不是一键全拆
- 超上限附魔原样保留：锋利 30 拆出来还是锋利 30，不会被压回原版上限
- 支持把附魔书放进去，一本多附魔书可拆成多本单附魔书
- 联动原版附魔与 EcoEnchants，走同一套接口
- CraftEngine / MMOItems 物品拆完附魔后身份与数据不变
- 可配置在祛魔时清零铁砧的「修复惩罚」，解决装备「过于昂贵！」
- 三份配置覆盖功能开关、界面布局材质文案音效、全部提示文字
- 可选收费：Vault 或 PlayerPoints，可按附魔、按等级、按分组定价
- 内置 36 项自检，升级服务端后一键确认环境没坏
- 管理员指令对普通玩家完全隐藏，Tab 补全与帮助里都不出现
- 防复制设计：四条归还路径 + 先清空再归还
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
核心亮点
| 模块 | 说明 | 适合场景 |
| --- | --- | --- |
| 逐条勾选提取 | 一件装备上的附魔可以只取其中几条，其余保留在装备上 | 精细管理附魔，不破坏原装备 |
| 原生附魔书 | 生成的附魔书是 Bukkit 原生存储附魔，不是改名书或 lore 伪装书 | 兼容铁砧、交易、其他原版逻辑 |
| 超上限附魔保留 | 锋利 30 这类超限附魔拆出后等级原样保留 | 高强化服、RPG 服 |
| 物品身份保真 | CraftEngine / MMOItems 物品拆完附魔后 ID 与自定义数据不变 | 自定义物品服 |
| 数据组件保真 | 改写附魔不会连带改坏物品的其它数据组件 | Paper 版本升级后不易静默丢组件 |
| 铁砧兼容 | 可配置在祛魔时清零铁砧「修复惩罚」 | 解决装备「过于昂贵！」 |
| 附魔书输入 | 支持把附魔书放进去拆成单附魔书 | 附魔书回收 |
| 经济扣费 | 支持 Vault、PlayerPoints，也可配置为免费 | 金币服、点券服、免费服 |
| 附魔过滤 | 白名单 / 黑名单模式，限制哪些附魔允许被提取 | 保护核心附魔、活动附魔 |
| 物品过滤 | 按材质、CraftEngine ID、MMOItems ID 限制可祛魔的物品 | 绑定装备、礼包装备保护 |
| 界面全自定义 | 54 格布局、槽位、材质、名称、说明、音效全部可在 gui.yml 改 | 美化菜单、资源包服 |
| 内置自检 | /qm selftest 一键跑完 36 项回归 | 升级服务端后确认环境 |
| 权限隐藏 | 无权限玩家看不到管理员指令，Tab 补全与帮助里都不出现 | 防止玩家乱试管理指令 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
玩家如何使用
打开祛魔台：
代码：
/qm open
基础流程：
1. 把要祛魔的装备放进界面中央的装备槽
2. 界面扫描出该装备上的全部附魔，每条显示为一个书本图标
3. 点击要提取的附魔进行勾选（勾选后变绿色附魔书并发光）
4. 点击「确认祛魔」
5. 逐条扣费 → 附魔从装备上移除 → 每条生成一本独立附魔书进背包
小提示：
- 被规则禁止的附魔显示为灰色染料图标，点击会告诉你具体原因
- 取走装备或直接关闭界面，装备都会自动还给你
- 附魔条目一页放不下时会自动分页，用界面两侧的箭头翻页
- 支持一键全选 / 全不选
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
指令
代码：
/qm open
/qm list [页码]
/qm help
/qm reload
/qm give <玩家> <附魔> [等级]
/qm debug
/qm selftest
| 指令 | 说明 | 权限 |
| --- | --- | --- |
| /qm open | 打开祛魔台 | qumo.use |
| /qm list [页码] | 查看有哪些附魔可以被提取 | qumo.use |
| /qm help | 帮助 | qumo.use |
| /qm reload | 重载 config.yml / gui.yml / lang.yml，不需要重启 | qumo.admin |
| /qm give <玩家> <附魔> [等级] | 发放附魔书 | qumo.admin |
| /qm debug | 查看手上物品的识别结果 | qumo.admin |
| /qm selftest | 跑内置自检（36 项） | qumo.admin |
别名：/qumo、/qumotai、/祛魔台、/祛魔
没有 qumo.admin 权限的玩家不但用不了管理员指令，Tab 补全和帮助列表里也完全看不到它们。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
权限
| 权限 | 默认 | 说明 |
| --- | --- | --- |
| qumo.use | 所有玩家 | 打开祛魔台、使用 /qm 与 /qm list |
| qumo.open.others | OP | 用 /qm open <玩家> 给别人打开 |
| qumo.admin | OP | 重载配置、发放附魔书、debug、自检 |
| qumo.bypass.cost | 无 | 使用祛魔台不花钱 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
配置文件
路径：plugins/QuMo/ 首次启动自动生成三份
代码：
plugins/QuMo/config.yml
plugins/QuMo/gui.yml
plugins/QuMo/lang.yml
| 文件 | 内容 |
| --- | --- |
| config.yml | 功能开关、物品与附魔规则、费用 |
| gui.yml | 界面布局、槽位、材质、名称、说明、音效 |
| lang.yml | 全部提示文字 |
config.yml 主要选项：
代码：
enabled: true 总开关
limits:
open-to-players: true 是否对普通玩家开放
cooldown-ms: 800 两次祛魔之间的冷却（毫秒）
disabled-worlds: [] 禁止使用祛魔台的世界
max-enchants-per-use: -1 单次最多提取几条（-1 不限）
item:
require-enchantable: true 只允许本身可附魔的物品
require-has-enchant: true 只允许已带附魔的物品
allow-enchanted-book: false 是否允许把附魔书也放进去
blacklist-materials: [] 额外拒绝的材质
whitelist-materials: [] 只允许这些材质
craftengine: 自定义物品白名单与黑名单
mmoitems: 同上
enchant:
filter-mode: BLACKLIST 附魔过滤模式（NONE / BLACKLIST / WHITELIST）
blacklist: [] 附魔黑名单
whitelist: [] 附魔白名单
block-curses: false 是否禁止提取诅咒附魔
allow-above-max-level: true 是否允许提取超上限附魔
unsafe-book-levels: true 制书时是否绕过原版等级上限
keep-glint: false 提取后是否保留强制发光
cost:
enabled: false 收费总开关（默认免费）
settings:
selftest-on-startup: false 启用时自动跑一遍自检
三份配置全部带中文注释；改完执行 /qm reload 即刻生效，不用重启。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
附魔与物品过滤
附魔名单支持三种写法，效果等价，不用记前缀：
代码：
enchant:
blacklist: []
whitelist: []
# 下面三种写法都能匹配到同一条附魔
# wound
# minecraft:wound
# ecoenchants:wound
物品侧可以按材质、CraftEngine 物品 ID、MMOItems ID 分别设白名单与黑名单：
代码：
item:
blacklist-materials: []
whitelist-materials: []
craftengine:
allow: true
whitelist-ids: []
blacklist-ids: []
mmoitems:
allow: true
whitelist-ids: []
blacklist-ids: []
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
保真与防复制
| 保护项 | 说明 |
| --- | --- |
| 物品身份保真 | CraftEngine / MMOItems 物品拆完附魔后 ID 与自定义数据不变 |
| 数据组件保真 | 改写附魔不会连带改坏物品的其它数据组件 |
| 归还路径完整 | 关界面 / 掉线 / 死亡 / 插件重载，四条路径都会把装备还回背包 |
| 归还顺序 | 先把槽位清空再给物品，顺序不可颠倒，避免复制 |
| 背包满 | 放不下就掉在玩家脚下，不会凭空消失 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
内置自检
/qm selftest 会跑 36 项回归，覆盖：
- 运行环境与五个联动是否接入
- 三份配置文件能否解析、界面物品能否构建
- 附魔注册表可读性
- 原版附魔：识别 → 定价 → 制书 → 剥离 → 防复制校验
- 超上限附魔：高等级必须原样保留
- 附魔书输入：stored 附魔能读能删
- EcoEnchants：识别 / 制书 / 剥离 / 与原版附魔共存
- CraftEngine：加附魔 → 剥离 → CE ID 与数据必须不变
- 物品校验（纸张、无附魔物品、空槽、null）
- 界面槽位冲突检查、计费分组与取整
- 指令权限隐藏：普通玩家看不到管理员子指令
- 界面端到端渲染（真实 54 格 × 空槽 / 放装备 / 勾选三种状态）
- 铁砧兼容性：修复惩罚会被清零，且组件不会在操作中丢失
- 数据组件保真：改写附魔不会连带改坏其它组件
另外 config.yml 里的 settings.selftest-on-startup: true 可以让插件在启用时
自动跑一遍自检并打到控制台，适合升级后确认环境没坏。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
可选联动
| 联动 | 是否必须 | 用途 |
| --- | --- | --- |
| Vault + 经济插件 | 可选 | 使用金币扣费 |
| PlayerPoints | 可选 | 使用点券扣费 |
| EcoEnchants | 可选 | 识别与剥离 Eco 自定义附魔 |
| CraftEngine | 可选 | 保留自定义物品身份 |
| MMOItems + MythicLib | 可选 | 支持自定义物品 |
| PlaceholderAPI | 可选 | 占位符 |
全部不装时，原版附魔、原版材质、基础界面与免费模式仍然完全可用。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
安装说明
推荐环境：
| 项目 | 说明 |
| --- | --- |
| Java | Java 21 及以上 |
| 服务端 | Paper / Purpur / Leaf 等 Paper 系 |
| 经济 | Vault + 经济插件，或 PlayerPoints；也可以配置为免费 |
安装步骤：
1. 将 QuMo.jar 放入服务器 plugins 文件夹
2. （可选）把 DeluxeMenus菜单/fm.yml 覆盖到 plugins/DeluxeMenus/gui_menus/
注意：fm.yml 里有个「返回主菜单」按钮指向名为 menu 的菜单，
你没有这个菜单的话，把那一项删掉即可
3. 重启服务器
（不要用 PlugManX 热载本插件，原因见〈已知限制〉第 1 条）
4. 启动后生成 plugins/QuMo/ 配置目录，按需修改三份配置
5. 使用 /qm reload 重载配置，或重启服务器
6. 游戏内执行 /qm open 打开祛魔台
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
与同类插件的区别
站内已有其他祛魔插件，QuMo 的差异点在这四处：
1. 逐条勾选提取
不是「一键全拆」。一件装备上有多条附魔时，可以只取其中一条或几条，
剩下的原样留在装备上。
2. 超上限附魔原样保留
锋利 30 拆出来还是锋利 30，不会被压回原版上限。
3. 物品身份与数据组件保真
CraftEngine / MMOItems 物品拆完附魔后，ID 与自定义数据不变；
改写附魔也不会连带改坏物品的其它数据组件。
4. 内置 36 项自检
/qm selftest 一键跑完回归测试，升级服务端后用来确认环境没坏。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
已知限制
1. 不能用 PlugManX 热载
Leaf 26.x 把插件指令编进了 Brigadier 命令树。热载工具只会更新旧的 CommandMap，
命令节点仍指向已被卸载的实例，执行 /qm 会报 plugin is disabled。
请用重启的方式加载或更新本插件。
2. 原版附魔名在控制台显示英文
/qm list、/qm debug 里的原版附魔用的是可翻译组件，控制台没有客户端语言，
所以显示英文（Density、Swift Sneak）。游戏内界面会跟随玩家客户端语言显示中文。
3. EcoEnchants 的砂轮
EcoEnchants 自带 GrindstoneSupport，玩家可能通过砂轮免费洗掉 Eco 附魔。
如果这会绕开你的经济设计，请在 EcoEnchants/config.yml 里调整。
4. 首次启动可能因 PlaceholderAPI 的网络检查变慢
若装了 PlaceholderAPI，启动时会去访问 check.placeholderapi.com 做更新与扩展检查，
网络不通时会一直等到超时。把 plugins/PlaceholderAPI/config.yml 里的
check_updates 与 detect_malicious_expansions 改成 false 可以显著缩短启动时间
（cloud_enabled 保留，/papi ecloud download 仍可用）。改前先备份。
5. 升级后新增的配置项不会自动出现在老文件里
Bukkit 的 saveDefaultConfig() 只在文件不存在时生成，所以插件升级新增的选项
不会写进你已有的 config.yml。取值本身有兜底（缺键就用内置默认），功能不会坏；
插件在启用时会把这批缺失项打到控制台，想调整它们就删掉 config.yml 重新生成（先备份）。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
适合这些情况
- 你希望玩家能把装备上的附魔取出来，做成原生附魔书
- 你希望「挑着拆」而不是「一键全删」，保留装备的其余价值
- 你在用 CraftEngine / MMOItems 自定义物品，担心拆附魔把物品拆坏
- 你想解决装备「过于昂贵！」的修复惩罚问题
- 你想给附魔书产出接上经济消耗（可选收费）
- 你需要附魔白名单 / 黑名单，保护核心附魔与活动附魔
- 你希望升级服务端后能一键自查环境是否正常
不太适合这些情况
- 你只想要原版砂轮式的直接去掉附魔，不需要产出附魔书
- 你用的是纯 lore 附魔插件（本插件只读取真实 Bukkit 附魔，不猜 lore）
- 你希望所有附魔都能 100% 无损取出，不需要任何规则限制
- 你完全不打算改动任何配置，希望装上去就固定一种玩法
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
使用前建议
- 确认服务端为 Paper 系（Paper / Purpur / Leaf）
- 确认服务端使用 Java 21 及以上
- 如果要收费，先装好 Vault 与对应经济插件
- 如果要读取 Eco 附魔，确认 EcoEnchants 已正确安装并能正常显示附魔
- 更新插件前先备份 plugins/QuMo/ 配置目录
- 首次上线前用 /qm open 自己点一遍，确认界面观感符合预期
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[/MD]
