原创 工具 EnchForge 现代化的高等级附魔插件 适合长期服务器 3.18

[MD] # EnchForge 附魔书生成器 EnchForge 是一个兼容 **Purpur 1.20.1** 的附魔书生成与高阶铁砧插件。它把管理员发放附魔书、玩家使用高等级附魔书、书合书升级限制、高阶强化消耗与失败惩罚集中到一套中文图形界面流程中，适合长期生存服、养老服和需要控制高等级附魔流通节奏的服务器。 当前项目版本：**3.18** ## 适用场景 - 管理员希望通过图形界面给在线玩家发放指定附魔、指定等级和指定数量的附魔书。 - 服务器允许玩家使用高等级附魔书，但不希望玩家通过原版铁砧无限低成本升级。 - 长期服希望高阶附魔消耗材料、经验和货币，并带有可配置成功率。 - 服务器希望所有操作提示、界面文本、配置说明都保持中文。 - 其他插件希望通过接口接入特殊附魔书生成逻辑。 ## 环境要求 | 项目 | 要求 | | --- | --- | | 服务端 | Purpur 1.20.1 | | Java | Java 17 或更高版本 | | 构建工具 | Maven | | 经济支持 | 可选，支持通过 Vault 软接入经济服务 | > Vault 不是强制依赖。未安装 Vault 或经济插件时，插件仍可启动；如果启用了高阶铁砧货币消耗，则需要服务器提供可用的 Vault Economy 服务，或在配置中关闭货币消耗。 ## 核心功能 - **全图形界面操作**：`/enchforge` 和 `/ef` 只负责打开主界面，所有功能都在界面内完成。 - **原版附魔书生成**：选择附魔、等级、数量和目标玩家后发放附魔书。 - **全部原版附魔书生成**：一键为目标玩家生成所有原版附魔的原版等级书，适合测试和管理员维护。 - **特殊附魔书生成**：其他插件可注册特殊附魔提供器，由 EnchForge 统一展示和发放。 - **附魔列表查看**：分页查看服务器当前注册的原版附魔，点击条目可直接进入生成界面。 - **在线玩家选择**：所有发放操作都可在界面中选择目标玩家。 - **配置热加载**：有权限的管理员可在主界面点击“重载配置”。 - **高等级铁砧应用**：玩家可把高等级附魔书应用到装备或附魔书上，结果达到阈值时进入高阶铁砧界面。 - **基岩版高阶弹窗**：安装 Geyser/Floodgate 时，基岩版玩家会自动弹出高阶铁砧确认窗口，不依赖结果槽点击。 - **书合书升级限制**：可配置书与书合并规则和升级上限，避免无限合成滚雪球。 - **高阶铁砧资源判定**：按结果等级、改动附魔数量和同级升阶次数计算材料、经验、货币和成功率。 - **失败惩罚机制**：失败后按配置消耗资源，并对原物品进行耐久损耗或附魔书降级。 ## 安装方式 1. 确认服务器为 Purpur 1.20.1，并使用 Java 17 或更高版本运行。 2. 将构建得到的 `enchforge-3.18.jar` 放入服务器 `plugins` 目录。 3. 启动服务器，插件会自动生成默认配置文件。 4. 按服务器需求修改配置。 5. 在游戏内使用 `/enchforge` 或 `/ef` 打开图形界面。 如需使用货币消耗： 1. 安装 Vault。 2. 安装任意能注册 Vault Economy 服务的经济插件。 3. 保持配置项 `anvil.risk.currency-enabled: true`。 如不需要货币消耗： ```yml anvil: risk: currency-enabled: false ``` ## 命令 | 命令 | 说明 | | --- | --- | | `/enchforge` | 打开 EnchForge 图形界面 | | `/ef` | `/enchforge` 的别名 | 插件没有子命令。输入附加参数时，插件会提示改用图形界面操作。 ## 权限 | 权限 | 默认 | 说明 | | --- | --- | --- | | `enchforge.use` | 管理员 | 允许打开并使用 EnchForge 图形界面中的发放、列表和选择功能 | | `enchforge.reload` | 管理员 | 允许在图形界面内热加载配置 | 玩家只需要正常使用铁砧应用已获得的附魔书，不需要 `enchforge.use` 权限。 ## 图形界面使用说明 ### 主界面 打开命令： ```text /enchforge /ef ``` 主界面会展示当前最高附魔等级、单次生成数量上限、书合书升级上限和高阶界面触发等级，并提供以下入口： - 生成原版附魔书 - 生成全部原版附魔书 - 生成特殊附魔书 - 查看附魔列表 - 重载配置 - 关闭界面 ### 生成原版附魔书 流程： 1. 在附魔选择界面选择一个原版附魔。 2. 设置等级。 3. 设置数量。 4. 选择目标玩家。 5. 点击“获取附魔书”。 等级支持： - `-10` - `-1` - `+1` - `+10` - 设置为最高等级 `255` - 点击“当前等级”后通过铁砧输入精确等级 数量支持： - `-16` - `-1` - `+1` - `+16` - 设置为配置允许的最大数量 ### 生成全部原版附魔书 该功能会为目标玩家生成所有原版附魔的所有原版等级书。例如某个附魔原版最高等级为 5，则会生成该附魔的 1 到 5 级附魔书。 适合用于： - 测试附魔书显示效果 - 检查服务器当前注册的原版附魔 - 管理员整理奖励或维护物品 ### 生成特殊附魔书 特殊附魔书来自其他插件注册的 `CustomEnchantmentProvider`。 如果没有任何插件注册特殊附魔，界面会显示“暂无特殊附魔提供器”。如果已经接入扩展插件，界面会分页展示特殊附魔提供器，并允许设置等级、数量和目标玩家。 ### 查看附魔列表 附魔列表会分页展示服务器当前注册的原版附魔。点击列表中的附魔项，可以直接进入该附魔的生成设置界面。 列表页容量由以下配置控制： ```yml features: list: enabled: true page-size: 8 ``` ## 铁砧等级输入说明 在“生成原版附魔书”或“生成特殊附魔书”界面中点击“当前等级”，会打开一个铁砧输入界面。 输入规则： - 只允许输入纯数字。 - 范围固定为 `1` 到 `255`。 - 输入为空、包含文字或符号、小于 1、超过 255 时不会生效。 - 合法输入会显示绿色“完成”按钮。 - 非法输入会显示红色“无法完成”按钮，并提示原因。 - 点击中间槽或右侧结果槽的完成按钮后，只会设置等级，不会直接发放附魔书。 - 关闭铁砧输入界面会取消本次输入并返回原界面，原等级保持不变。 ## 玩家铁砧应用规则 玩家可以把 EnchForge 发放的高等级附魔书放入原版铁砧使用。插件会在铁砧准备结果时重新计算附魔结果，并进行安全限制。 ### 装备加书 - 目标物品放左侧，附魔书放右侧。 - 默认只允许附魔应用到原版支持的物品上。 - 默认会遵守附魔冲突规则。 - 若配置 `anvil.allow-unsafe-any-item: true`，则允许把附魔强制应用到原版不支持的物品上。 - 结果等级不能超过 `limits.max-enchantment-level`。 - 结果等级达到高阶触发等级时，会转入高阶铁砧界面。 ### 书合书 默认允许附魔书与附魔书合并，但会受配置限制。 ```yml anvil: block-book-merge: false merge-same-level-plus-one: true merge-upgrade-max-level: 10 ``` 规则说明： - `block-book-merge: true`：完全禁止书与书合并。 - `merge-same-level-plus-one: true`：同一种附魔合并时按等级相加。 - `merge-upgrade-max-level`：通过合并升级得到的结果等级上限。 示例： | 输入 | 结果 | | --- | --- | | 1 级 + 1 级 | 2 级 | | 1 级 + 2 级 | 3 级 | | 2 级 + 4 级 | 6 级 | | 合并结果超过上限 | 限制到 `merge-upgrade-max-level` | 已经存在的更高等级附魔书不会因为合并上限而被强制降级，但非法或超过全局最高等级的结果会被拦截。 ## 高阶铁砧说明 当铁砧结果达到以下等级时，会进入高阶铁砧界面： ```yml anvil: advanced-gui: enabled: true trigger-level: 6 bedrock-forms: enabled: true ``` 默认 `trigger-level: 6`，表示结果等级达到 6 级及以上时进入高阶铁砧。 如果服务器安装 Geyser/Floodgate，且 `anvil.bedrock-forms.enabled: true`，基岩版玩家在铁砧准备出高阶结果后会自动转入 Bedrock 弹窗确认流程；Java 版玩家仍通过原版铁砧结果槽点击进入高阶 GUI。 高阶铁砧会显示： - 待强化物品 - 消耗附魔书 - 强化结果预览 - 最高结果等级 - 改动附魔数量 - 同级升阶次数 - 成功率 - 所需材料 - 所需经验等级 - 所需货币 - 失败规则 - 确认按钮 - 取消并返还按钮 ### 二次确认 高阶铁砧的确认按钮需要点击两次： 1. 第一次点击只进入确认状态，不会消耗任何资源。 2. 第二次点击才会扣除资源并进行成功率判定。 如果资源不足，确认按钮会显示为资源不足状态，点击不会执行强化。 关闭界面或点击取消，会返还装备和附魔书。 ### 材料消耗 默认主材料为紫水晶碎片： ```yml anvil: risk: material: AMETHYST_SHARD material-display-name: "紫水晶碎片" min-material-amount: 2 material-level-step: 5 max-material-amount: 32 ``` 主材料数量计算方向： - 结果等级越高，材料越多。 - 改动附魔数量越多，材料越多。 - 同级升阶次数越多，材料越多。 - 最终数量不会超过 `max-material-amount`。 默认额外材料： | 材料 | 显示名 | 解锁等级 | 单种上限 | | --- | --- | --- | --- | | `LAPIS_LAZULI` | 青金石 | 6 | 32 | | `ECHO_SHARD` | 回响碎片 | 11 | 16 | | `NETHER_STAR` | 下界之星 | 16 | 8 | | `DRAGON_BREATH` | 龙息 | 21 | 16 | 额外材料会随等级逐步加入，让高阶强化消耗更多材料种类，而不是只无限堆叠一种材料。 ### 成功率 默认配置： ```yml anvil: risk: base-success-chance: 55.0 level-success-penalty: 4.0 extra-enchantment-penalty: 8.0 min-success-chance: 3.0 ``` 成功率计算方向： - 基础成功率为 `base-success-chance`。 - 结果等级超过 5 后，每提升一定等级会降低成功率。 - 改动附魔数量和同级升阶次数越多，成功率越低。 - 最低不会低于 `min-success-chance`。 ### 经验消耗 默认配置： ```yml anvil: risk: min-experience-cost: 5 experience-level-step: 7 max-experience-cost: 39 ``` 经验等级会随结果等级和强化复杂度增加，最高默认限制为 39 级，避免出现原版“过于昂贵”导致无法使用的情况。 ### 货币消耗 默认配置： ```yml anvil: risk: currency-enabled: true currency: "生存币" currency-display-name: "生存币" min-currency-cost: 50000.0 currency-level-step: 5 max-currency-cost: 500000000.0 ``` 货币规则： - 5 级及以下不收货币。 - 6 级开始收取 `min-currency-cost`。 - 每经过 `currency-level-step` 个等级，货币需求翻倍。 - 改动附魔数量和同级升阶次数会提高费用。 - 最终费用不会超过 `max-currency-cost`。 如果 `currency-enabled: true`，但 Vault 经济服务不可用，高阶铁砧会阻止确认并给出提示。 ### 成功与失败 成功时： - 扣除材料。 - 扣除经验。 - 扣除货币。 - 消耗附魔书。 - 给玩家发放强化结果。 失败时： - 默认消耗材料、经验、货币和附魔书。 - 原装备会损失一部分耐久，但不会被插件直接损坏到完全破坏。 - 如果原物品是附魔书，则其中的附魔等级会降低 1 级；降级后没有附魔时会被吞噬。 - 如果配置关闭某类失败消耗，则对应资源会保留或返还。 失败消耗配置： ```yml anvil: risk: consume-material-on-failure: true consume-book-on-failure: true consume-experience-on-failure: true consume-currency-on-failure: true ``` ## 重要配置项 默认配置位于： ```text src/main/resources/config.yml ``` 服务器运行后对应文件位于插件数据目录。 ### 限制配置 ```yml limits: max-give-amount: 255 max-enchantment-level: 255 ``` | 配置项 | 说明 | | --- | --- | | `limits.max-give-amount` | 图形界面单次允许发放的最大数量，范围 1 到 255 | | `limits.max-enchantment-level` | 允许生成和铁砧应用的最高附魔等级，范围 1 到 255 | ### 功能开关 ```yml features: list: enabled: true page-size: 8 notify-target-on-receive: true drop-overflow: true ``` | 配置项 | 说明 | | --- | --- | | `features.list.enabled` | 是否启用附魔列表界面 | | `features.list.page-size` | 附魔列表每页展示数量，读取时限制在 4 到 20 | | `features.notify-target-on-receive` | 目标玩家收到附魔书时是否额外提示 | | `features.drop-overflow` | 背包空间不足时是否把无法放入的附魔书掉落到玩家脚下 | ### 附魔书显示 ```yml book-style: enabled: true vanilla-name: "&e附魔书" vanilla-lore: - "&7%enchant_name% %level_roman%" special-name: "&6附魔书" special-lore: - "&7%special_name% %level_roman%" ``` 可用占位符： | 类型 | 占位符 | | --- | --- | | 原版附魔书 | `%enchant_name%`、`%namespace_key%`、`%level%`、`%level_roman%` | | 特殊附魔书 | `%special_name%`、`%special_id%`、`%level%`、`%level_roman%` | ### 铁砧配置 ```yml anvil: enabled: true allow-unsafe-any-item: false block-book-merge: false merge-same-level-plus-one: true merge-upgrade-max-level: 10 ``` | 配置项 | 说明 | | --- | --- | | `anvil.enabled` | 是否启用高等级附魔书铁砧应用增强 | | `anvil.allow-unsafe-any-item` | 是否允许把附魔强制应用到原版不支持的物品上 | | `anvil.block-book-merge` | 是否完全阻止附魔书与附魔书合并 | | `anvil.merge-same-level-plus-one` | 是否启用同种附魔合并时等级相加 | | `anvil.merge-upgrade-max-level` | 通过合并升级时的结果等级上限 | | `anvil.bedrock-forms.enabled` | 是否为 Geyser/Floodgate 基岩版玩家启用高阶铁砧弹窗确认 | ### 消息配置 所有提示、报错、命令反馈、界面说明和热加载反馈都集中在 `messages` 节点中，可按服务器风格修改。 修改配置后，可在主界面点击“重载配置”生效。重载会取消未完成的高阶铁砧界面，并返还其中的装备和附魔书，避免旧配置继续参与扣费。 ## Vault 经济兼容 插件通过反射方式软接入 Vault 经济服务： - 未安装 Vault 时，插件不会因此启动失败。 - 安装 Vault 但没有经济服务时，启用货币消耗的高阶铁砧会阻止确认。 - 插件不绑定任何单一经济插件。 - 只要经济插件向 Bukkit 服务管理器注册了 Vault Economy 服务，EnchForge 就可以检查余额并扣款。 - 配置中的 `currency` 主要作为货币标识和显示用途；Vault 常见实现通常是单货币服务。 ## PlugMan 与热加载说明 插件已针对重复启停和热加载做兼容处理： - `onLoad()` 会保存默认配置并读取设置。 - `onEnable()` 会重新绑定命令、补全器和监听器。 - 图形界面重载配置前，会返还未完成高阶铁砧界面中的物品。 - 插件关闭时，会返还未完成高阶铁砧界面中的物品。 - 插件关闭时，会清理 EnchForge 图形界面会话和铁砧等级输入状态。 - 插件关闭时，会清空自定义附魔注册表，避免旧实例残留。 仍然建议优先使用 EnchForge 主界面中的“重载配置”，不要频繁整插件热加载。 ## 扩展接口 其他插件可以通过 EnchForge 的注册中心接入特殊附魔书提供器。 核心接口： ```java package awa.uxu.enchforge.api; import org.bukkit.inventory.ItemStack; public interface CustomEnchantmentProvider { String getId(); int getMaxLevel(); String getDisplayName(); ItemStack createBook(int level); } ``` 注册要求： - `getId()` 会去除首尾空白并转为小写。 - ID 只允许小写字母、数字和下划线。 - 重复 ID 会注册失败。 - `createBook(int level)` 返回 `null` 表示生成失败。 - EnchForge 会为生成出的特殊附魔书应用配置中的显示名称和 Lore。 注册入口： ```java EnchForgePlugin enchForge = (EnchForgePlugin) Bukkit.getPluginManager().getPlugin("EnchForge"); if (enchForge != null) { enchForge.customRegistry().register(provider); } ``` 如果扩展插件可能被单独热加载或 EnchForge 被单独重载，请监听 `EnchForgeReadyEvent`，并在事件中重新注册提供器。EnchForge 每次启用完成后都会发送该事件。 ## 构建方式 在项目根目录执行： ```bash mvn test mvn clean package ``` 构建完成后，插件产物位于： ```text target/enchforge-3.18.jar ``` 版本号以以下两个文件为准，并且必须保持一致： - `pom.xml` - `src/main/resources/plugin.yml` ## 项目结构 ```text src/main/java/awa/uxu/enchforge ├─ api 自定义附魔扩展接口 ├─ command 命令入口、图形界面和附魔书发放服务 ├─ config 配置与消息读取 ├─ economy Vault 经济软接入 ├─ listener 铁砧应用、高阶铁砧和风险策略 └─ util 附魔文本、附魔书显示和 Lore 工具 src/main/resources ├─ plugin.yml 插件声明、命令和权限 └─ config.yml 默认配置 ``` ## 管理员建议 - 长期服建议保留高阶铁砧和失败惩罚，不建议关闭所有失败消耗。 - 如果服务器经济通胀严重，可以提高 `min-currency-cost` 或降低 `currency-level-step`。 - 如果玩家反馈高阶附魔过难，可以提高 `base-success-chance` 或 `min-success-chance`。 - 如果材料过于单一，建议调整 `extra-materials`，让不同等级段消耗不同资源。 - 如果只想允许管理员发放书，不想让玩家书合书升级，可以设置 `anvil.block-book-merge: true`。 - 如果服务器没有 Vault 经济服务，建议关闭 `anvil.risk.currency-enabled`。 [/MD]





结果附魔等级超过5级（可配置）后，会跳转UI至高阶铁砧