- 版权类型
- 转载
- 插件中文名
- 锻卷强化 | 装备星级强化、淬炼与分支成长
- 插件英文名
- emakistrengthen equipment star enhancement tempering branch growth
- 支持的核心 [服务端]
- Folia
- 语言支持
- 中文(简体)
- 适配Minecraft版本 [Java]
- 1.21
[MD]
# 锻卷强化 | 装备星级强化、淬炼与分支成长
EmakiStrengthen 是 Emaki 系列的 GUI 装备强化模块。玩家将装备与所需材料放入强化台，模块按目标星级滚动成功率，结果直接写入装备的 PDC 强化层，再由 EmakiCoreLib 重建最终名称和 lore 显示。每一个星级、材料、成功率、失败结果与成长分支均通过 YAML 配置定义。
模块不存在任何硬编码逻辑。单条配方可以从 +1 一路跑到可配置的最高星级，在每个步骤上独立指定材料与概率，在里程碑星级解锁新属性和技能，并支持多条成长分支的嵌套分叉，还可向全服广播高星成就。属性增益只在显式声明 `ea_attribute` 时才写入真实战斗数值，展示文本与实际属性因此永远保持一致。
## 核心特性
- **逐星级精细配置** — 每个星级拥有独立的材料、成功率、属性增益、技能、名称/lore 变更以及成功/失败触发动作。默认配方提供完整的 +1 至 +12 曲线：材料从 1 块铜锭逐步扩展至 16 块，火药从 2 至 32，高星级还需要回声碎片和下界材料。
- **越挫越强的淬炼机制** — 每次失败都会积累淬炼层数，使下次成功率提升（默认每层 +5%），最高叠加至上限（默认 4 层），并有最终成功率封顶（默认 90%）。特定材料还可额外赋予淬炼层数。
- **保护材料** — 将某种材料标记为保护材料后，失败不再导致星级下降或装备销毁。默认配方使用金粒作为保护材料，设置为仅检测不消耗（`amount -1`），且完全可选。
- **失败结果可自由配置** — 失败时可按配方独立设定：保留当前星级、降低 N 星、归零或销毁，每种结果均有独立的动作钩子。
- **嵌套分支成长** — 配方可在指定星级分叉出多条命名分支，分支内还可再次分叉。每条分支写入各自的属性、技能和显示内容；所选路径锁定在装备状态中，无法更改。
- **里程碑属性与技能** — 特定星级可解锁新属性行并绑定技能。默认配方在 +5 解锁暴击率、+8 解锁额外伤害、+10 解锁暴击伤害、+12 解锁穿甲加成与终极技能。
- **强化前实时预览** — GUI 在玩家确认操作前显示当前成功率、费用和所需材料。
- **保底连续失败触发必定成功** — 可选的保底机制在配置的连续失败次数后强制触发一次成功，随后重置计数。
## 功能详解
### 星级系统与成功率
- 星级范围从 +1 到每条配方独立配置的上限（`limits.max_star`，默认 12）。
- 全局成功率表作为后备，各配方可覆盖每个星级的具体概率。
- 默认曲线：+1/+2 为 100%，+3 为 95%，+5 为 75%，+7 为 45%，+9 为 22%，+10 为 14%，+11 为 8%，+12 为 4%。
- `success_chance_cap` 限制叠加淬炼加成后的最终成功率上限（默认 90%）。
### 逐星级阶段配置
- 每个星级是一个独立配置块，包含可选的里程碑名称、效果列表、所需材料以及成功/失败动作。
- 材料在每个星级单独列出，配置 `item_sources` 和 `amount`；默认配方在每个星级上均调整用量。
- `amount -1` 表示仅检测该材料是否存在而不消耗；配合 `optional` 使玩家无需强制持有。
### 每星级的五类效果
- `variables` — lore 渲染用的表达式变量，单独使用不写入真实属性。
- `ea_attribute` — 显式写入真实的 EmakiAttribute PDC 属性数值，是战斗数值的唯一来源，确保展示与实际完全对应。
- `es_skill` — 在该星级绑定 EmakiSkills 技能（+5 绑定暴击被动，+12 绑定终极技能）。
- `lore_action` — 编辑装备 lore。
- `name_action` — 编辑装备名称。
### 淬炼（锻印）
- 失败的尝试会积累淬炼层数，每层提升下次成功率。
- `max_temper` 限制淬炼层数上限，`success_chance_cap` 限制加成后的成功率上限。
- `temper_boost` 材料可额外赋予淬炼层数（示例配方在 +12 阶段使用药水作为该材料）。
- `%temper_color%` 占位符在淬炼层数大于零时将淬炼行显示为红色，否则为绿色。
### Lore 与名称成长策略
- +1 时配方追加全新的属性行；从 +2 起使用带锚点的 `replace_line`，确保每条属性始终只对应一行 lore。
- 里程碑星级会先更新现有行，再追加新属性行，对应新解锁的属性。
- 全局 `name_actions` 在名称后追加" [+星级]"后缀；全局 `lore_actions` 在每次成功时在首行插入渐变色强化行和淬炼行。
- 完整支持 MiniMessage 格式，包括渐变色。
### 失败结果与保护机制
- 结果分支：成功（星级 +1，重置保底计数，可能触发里程碑）、保留、降低 N 星、销毁、受保护。
- 每种结果拥有独立的动作钩子：`success`、`failure_keep`、`failure_downgrade`、`failure_destroy`、`protected`、`guarantee`。
- 保底机制在配置的连续失败次数后强制触发一次成功。
### 分支成长树
- `fork_after_star` 在指定星级后弹出分支选择界面（设为 -1 则禁用分叉）。
- 分支支持嵌套：内置示例分叉为「锋利」与「重击」两路，其中「锋利」路再次分叉为「致命」与「迅捷」。
- 每条分支拥有独立的 `display_name`、星级配置与子分支，写入不同的属性、技能和显示内容。
- 所选分支路径保存在装备状态中，之后无法变更。
- 默认分支均在最终星级解锁各自专属的终极技能。
### 匹配规则
- `source_ids` — 精确绑定到指定的 EmakiItem / ItemSource ID，推荐使用。
- `slot_groups` — 按粗粒度装备类型匹配（weapon / armor / offhand / generic）。
- `lore_contains` — 按 lore 文本匹配。
- `stats_any` — 匹配已携带指定属性的装备。
### 广播与里程碑
- 里程碑标记记录每个星级首次达成的时间，确保同一件装备不会重复广播。
- 本地广播（可配置触发星级阈值与广播半径）和全服广播（可配置触发阈值）用于宣告高星成就。
- 广播消息支持 `%player%`、`%star%`、`%item%` 和 `%recipe%` 占位符。
### 经济系统
支持每条配方独立配置多种货币，每种货币可设置提供者（如 Vault）、基础费用和费用公式（示例配方使用 `base_cost * star`）。
### 预览、转移与运行时工具
- GUI 预览槽在玩家确认前实时显示成功率、费用和所需材料。
- 运行时转移服务可将装备的强化状态（星级 / 淬炼 / 分支 / 里程碑）迁移到另一件装备上。
- 修改配方后，使用测试道具执行热重载并验证结果。
### 与 Emaki 套件的分层显示
- 强化数据写入装备的强化层，叠加在锻造层之上而非覆盖。
- EmakiCoreLib 的组装系统从所有层重建最终的名称和 lore。
- 安装 EmakiAttribute 后，每个星级可贡献真实的 PDC 属性，参与实时战斗计算。
### JavaScript 扩展
- 强化脚本模块暴露概率规则钩子（`registerChanceRule`），可调整成功率、失败后星级、失败后淬炼层数及保护逻辑，支持优先级排序，结果钳制在 0–100 之间。
- 结果钩子（`onResult`）在强化结算后执行，可用于发放奖励或触发广播。
- 内置示例脚本演示了 VIP 玩家 +2.5% 成功率的规则实现。
### 公开 API
- 支持读取星级、检查强化资格、执行强化、重建显示，以及监听成功 / 失败 / 降星 / 受保护事件。
- `StrengthenResult` 返回替换原装备的新道具；强化逻辑在主线程上运行。
## 命令
主命令 /emakistrengthen，别名 /estrengthen。
| 命令 | 说明 |
|------|------|
| /estrengthen `help` | 显示帮助 |
| /estrengthen `open` | 打开强化 GUI |
| /estrengthen `reload` | 重载配方、GUI、语言文件及运行时资源 |
| /estrengthen `inspect [player]` | 查看手持装备的强化层数据与匹配配方 |
| /estrengthen `refresh [player]` | 刷新手持装备的显示 |
| /estrengthen `setstar <star> [recipe]` | 设置手持装备的星级 |
| /estrengthen `clearstate` | 清除手持装备的强化层数据 |
| /estrengthen `clearcrack` | 清除手持装备的淬炼层数 |
| /estrengthen `givecatalyst <material> [amount] [player]` | 发放强化材料 |
| /estrengthen `debug <status\|player\|module\|all>` | 查看运行时调试信息 |
## 权限
| 权限节点 | 说明 | 默认 |
|----------|------|------|
| `emakistrengthen.use` | 使用强化 GUI 及基础命令 | 所有玩家 |
| `emakistrengthen.reload` | 重载配置 | OP |
| `emakistrengthen.debug` | 调试命令 | OP |
| `emakistrengthen.admin` | 管理员命令 | OP |
## PlaceholderAPI
扩展标识符 `emakistrengthen`，读取主手物品数据：
| 占位符 | 说明 |
|--------|------|
| `%emakistrengthen_mainhand_star%` | 当前星级 |
| `%emakistrengthen_mainhand_temper%` | 当前淬炼层数 |
| `%emakistrengthen_mainhand_crack_level%` | 淬炼层数（旧字段名） |
| `%emakistrengthen_mainhand_max_star%` | 配方最高星级 |
| `%emakistrengthen_mainhand_recipe%` | 匹配的配方 ID |
| `%emakistrengthen_mainhand_eligible%` | 装备是否可强化 |
| `%emakistrengthen_mainhand_success_rate%` | 当前成功率 |
| `%emakistrengthen_mainhand_success_count%` | 成功次数 |
| `%emakistrengthen_mainhand_failure_count%` | 失败次数 |
## 兼容性与依赖
| 项目 | 要求 |
|------|------|
| Java | 25 |
| Bukkit API | 1.21 |
| 服务端 | Spigot / Paper 及下游分支 |
| Folia | 支持 |
| 必须依赖 | EmakiCoreLib |
| 可选依赖 | EmakiAttribute、PlaceholderAPI |
## 安装与快速开始
1. 先安装 EmakiCoreLib.jar（必须依赖）。
2. 将 EmakiStrengthen.jar 放入 `plugins/` 目录。
3. 启动服务端，自动生成默认配方、GUI、语言文件和主配置。
4. 通过 `match.source_ids` 将配方绑定到目标装备，按需调整星级、材料、概率和分支，然后执行重载。
5. 用真实装备测试完整流程：成功、失败、保护、淬炼、星级写入与属性写入。
## 相关链接
[Documentation](https://jiuwu02.github.io/Emaki_Series/) | [Discord](https://discord.gg/FV4GFQbvCM) | [QQ Group](https://qm.qq.com/q/GqGrzHp0wU)
[/MD]
# 锻卷强化 | 装备星级强化、淬炼与分支成长
EmakiStrengthen 是 Emaki 系列的 GUI 装备强化模块。玩家将装备与所需材料放入强化台，模块按目标星级滚动成功率，结果直接写入装备的 PDC 强化层，再由 EmakiCoreLib 重建最终名称和 lore 显示。每一个星级、材料、成功率、失败结果与成长分支均通过 YAML 配置定义。
模块不存在任何硬编码逻辑。单条配方可以从 +1 一路跑到可配置的最高星级，在每个步骤上独立指定材料与概率，在里程碑星级解锁新属性和技能，并支持多条成长分支的嵌套分叉，还可向全服广播高星成就。属性增益只在显式声明 `ea_attribute` 时才写入真实战斗数值，展示文本与实际属性因此永远保持一致。
## 核心特性
- **逐星级精细配置** — 每个星级拥有独立的材料、成功率、属性增益、技能、名称/lore 变更以及成功/失败触发动作。默认配方提供完整的 +1 至 +12 曲线：材料从 1 块铜锭逐步扩展至 16 块，火药从 2 至 32，高星级还需要回声碎片和下界材料。
- **越挫越强的淬炼机制** — 每次失败都会积累淬炼层数，使下次成功率提升（默认每层 +5%），最高叠加至上限（默认 4 层），并有最终成功率封顶（默认 90%）。特定材料还可额外赋予淬炼层数。
- **保护材料** — 将某种材料标记为保护材料后，失败不再导致星级下降或装备销毁。默认配方使用金粒作为保护材料，设置为仅检测不消耗（`amount -1`），且完全可选。
- **失败结果可自由配置** — 失败时可按配方独立设定：保留当前星级、降低 N 星、归零或销毁，每种结果均有独立的动作钩子。
- **嵌套分支成长** — 配方可在指定星级分叉出多条命名分支，分支内还可再次分叉。每条分支写入各自的属性、技能和显示内容；所选路径锁定在装备状态中，无法更改。
- **里程碑属性与技能** — 特定星级可解锁新属性行并绑定技能。默认配方在 +5 解锁暴击率、+8 解锁额外伤害、+10 解锁暴击伤害、+12 解锁穿甲加成与终极技能。
- **强化前实时预览** — GUI 在玩家确认操作前显示当前成功率、费用和所需材料。
- **保底连续失败触发必定成功** — 可选的保底机制在配置的连续失败次数后强制触发一次成功，随后重置计数。
## 功能详解
### 星级系统与成功率
- 星级范围从 +1 到每条配方独立配置的上限（`limits.max_star`，默认 12）。
- 全局成功率表作为后备，各配方可覆盖每个星级的具体概率。
- 默认曲线：+1/+2 为 100%，+3 为 95%，+5 为 75%，+7 为 45%，+9 为 22%，+10 为 14%，+11 为 8%，+12 为 4%。
- `success_chance_cap` 限制叠加淬炼加成后的最终成功率上限（默认 90%）。
### 逐星级阶段配置
- 每个星级是一个独立配置块，包含可选的里程碑名称、效果列表、所需材料以及成功/失败动作。
- 材料在每个星级单独列出，配置 `item_sources` 和 `amount`；默认配方在每个星级上均调整用量。
- `amount -1` 表示仅检测该材料是否存在而不消耗；配合 `optional` 使玩家无需强制持有。
### 每星级的五类效果
- `variables` — lore 渲染用的表达式变量，单独使用不写入真实属性。
- `ea_attribute` — 显式写入真实的 EmakiAttribute PDC 属性数值，是战斗数值的唯一来源，确保展示与实际完全对应。
- `es_skill` — 在该星级绑定 EmakiSkills 技能（+5 绑定暴击被动，+12 绑定终极技能）。
- `lore_action` — 编辑装备 lore。
- `name_action` — 编辑装备名称。
### 淬炼（锻印）
- 失败的尝试会积累淬炼层数，每层提升下次成功率。
- `max_temper` 限制淬炼层数上限，`success_chance_cap` 限制加成后的成功率上限。
- `temper_boost` 材料可额外赋予淬炼层数（示例配方在 +12 阶段使用药水作为该材料）。
- `%temper_color%` 占位符在淬炼层数大于零时将淬炼行显示为红色，否则为绿色。
### Lore 与名称成长策略
- +1 时配方追加全新的属性行；从 +2 起使用带锚点的 `replace_line`，确保每条属性始终只对应一行 lore。
- 里程碑星级会先更新现有行，再追加新属性行，对应新解锁的属性。
- 全局 `name_actions` 在名称后追加" [+星级]"后缀；全局 `lore_actions` 在每次成功时在首行插入渐变色强化行和淬炼行。
- 完整支持 MiniMessage 格式，包括渐变色。
### 失败结果与保护机制
- 结果分支：成功（星级 +1，重置保底计数，可能触发里程碑）、保留、降低 N 星、销毁、受保护。
- 每种结果拥有独立的动作钩子：`success`、`failure_keep`、`failure_downgrade`、`failure_destroy`、`protected`、`guarantee`。
- 保底机制在配置的连续失败次数后强制触发一次成功。
### 分支成长树
- `fork_after_star` 在指定星级后弹出分支选择界面（设为 -1 则禁用分叉）。
- 分支支持嵌套：内置示例分叉为「锋利」与「重击」两路，其中「锋利」路再次分叉为「致命」与「迅捷」。
- 每条分支拥有独立的 `display_name`、星级配置与子分支，写入不同的属性、技能和显示内容。
- 所选分支路径保存在装备状态中，之后无法变更。
- 默认分支均在最终星级解锁各自专属的终极技能。
### 匹配规则
- `source_ids` — 精确绑定到指定的 EmakiItem / ItemSource ID，推荐使用。
- `slot_groups` — 按粗粒度装备类型匹配（weapon / armor / offhand / generic）。
- `lore_contains` — 按 lore 文本匹配。
- `stats_any` — 匹配已携带指定属性的装备。
### 广播与里程碑
- 里程碑标记记录每个星级首次达成的时间，确保同一件装备不会重复广播。
- 本地广播（可配置触发星级阈值与广播半径）和全服广播（可配置触发阈值）用于宣告高星成就。
- 广播消息支持 `%player%`、`%star%`、`%item%` 和 `%recipe%` 占位符。
### 经济系统
支持每条配方独立配置多种货币，每种货币可设置提供者（如 Vault）、基础费用和费用公式（示例配方使用 `base_cost * star`）。
### 预览、转移与运行时工具
- GUI 预览槽在玩家确认前实时显示成功率、费用和所需材料。
- 运行时转移服务可将装备的强化状态（星级 / 淬炼 / 分支 / 里程碑）迁移到另一件装备上。
- 修改配方后，使用测试道具执行热重载并验证结果。
### 与 Emaki 套件的分层显示
- 强化数据写入装备的强化层，叠加在锻造层之上而非覆盖。
- EmakiCoreLib 的组装系统从所有层重建最终的名称和 lore。
- 安装 EmakiAttribute 后，每个星级可贡献真实的 PDC 属性，参与实时战斗计算。
### JavaScript 扩展
- 强化脚本模块暴露概率规则钩子（`registerChanceRule`），可调整成功率、失败后星级、失败后淬炼层数及保护逻辑，支持优先级排序，结果钳制在 0–100 之间。
- 结果钩子（`onResult`）在强化结算后执行，可用于发放奖励或触发广播。
- 内置示例脚本演示了 VIP 玩家 +2.5% 成功率的规则实现。
### 公开 API
- 支持读取星级、检查强化资格、执行强化、重建显示，以及监听成功 / 失败 / 降星 / 受保护事件。
- `StrengthenResult` 返回替换原装备的新道具；强化逻辑在主线程上运行。
## 命令
主命令 /emakistrengthen，别名 /estrengthen。
| 命令 | 说明 |
|------|------|
| /estrengthen `help` | 显示帮助 |
| /estrengthen `open` | 打开强化 GUI |
| /estrengthen `reload` | 重载配方、GUI、语言文件及运行时资源 |
| /estrengthen `inspect [player]` | 查看手持装备的强化层数据与匹配配方 |
| /estrengthen `refresh [player]` | 刷新手持装备的显示 |
| /estrengthen `setstar <star> [recipe]` | 设置手持装备的星级 |
| /estrengthen `clearstate` | 清除手持装备的强化层数据 |
| /estrengthen `clearcrack` | 清除手持装备的淬炼层数 |
| /estrengthen `givecatalyst <material> [amount] [player]` | 发放强化材料 |
| /estrengthen `debug <status\|player\|module\|all>` | 查看运行时调试信息 |
## 权限
| 权限节点 | 说明 | 默认 |
|----------|------|------|
| `emakistrengthen.use` | 使用强化 GUI 及基础命令 | 所有玩家 |
| `emakistrengthen.reload` | 重载配置 | OP |
| `emakistrengthen.debug` | 调试命令 | OP |
| `emakistrengthen.admin` | 管理员命令 | OP |
## PlaceholderAPI
扩展标识符 `emakistrengthen`，读取主手物品数据：
| 占位符 | 说明 |
|--------|------|
| `%emakistrengthen_mainhand_star%` | 当前星级 |
| `%emakistrengthen_mainhand_temper%` | 当前淬炼层数 |
| `%emakistrengthen_mainhand_crack_level%` | 淬炼层数（旧字段名） |
| `%emakistrengthen_mainhand_max_star%` | 配方最高星级 |
| `%emakistrengthen_mainhand_recipe%` | 匹配的配方 ID |
| `%emakistrengthen_mainhand_eligible%` | 装备是否可强化 |
| `%emakistrengthen_mainhand_success_rate%` | 当前成功率 |
| `%emakistrengthen_mainhand_success_count%` | 成功次数 |
| `%emakistrengthen_mainhand_failure_count%` | 失败次数 |
## 兼容性与依赖
| 项目 | 要求 |
|------|------|
| Java | 25 |
| Bukkit API | 1.21 |
| 服务端 | Spigot / Paper 及下游分支 |
| Folia | 支持 |
| 必须依赖 | EmakiCoreLib |
| 可选依赖 | EmakiAttribute、PlaceholderAPI |
## 安装与快速开始
1. 先安装 EmakiCoreLib.jar（必须依赖）。
2. 将 EmakiStrengthen.jar 放入 `plugins/` 目录。
3. 启动服务端，自动生成默认配方、GUI、语言文件和主配置。
4. 通过 `match.source_ids` 将配方绑定到目标装备，按需调整星级、材料、概率和分支，然后执行重载。
5. 用真实装备测试完整流程：成功、失败、保护、淬炼、星级写入与属性写入。
## 相关链接
[Documentation](https://jiuwu02.github.io/Emaki_Series/) | [Discord](https://discord.gg/FV4GFQbvCM) | [QQ Group](https://qm.qq.com/q/GqGrzHp0wU)
[/MD]