EmakiStrengthen

EmakiStrengthen (强化模块) 的总览: 它能做哪些玩法, 你会动到哪些配置文件, 每个功能页面各讲什么

EmakiStrengthen 是装备强化模块, 提供星级强化, 锻印 (temper), 保护材料, 里程碑, 属性写入, 强化层重建和公开 API. 你用它做"装备从 +0 逐步升到 +N"这类玩法

NOTE

部分命令仍使用 crack 等历史命名 (如 clearcrack), 在玩法描述中统一称为"锻印"或"强化痕迹"

基本信息

项目	值
模块版本	`4.8.9`
主命令	`/emakistrengthen`
别名	`/estrengthen`
硬依赖	EmakiCoreLib
软依赖	EmakiItem, EmakiAttribute, PlaceholderAPI
主要权限	`emakistrengthen.use`, `emakistrengthen.reload`, `emakistrengthen.debug`, `emakistrengthen.admin`

功能页面

页面	内容
命令与权限	怎么打开强化 GUI, 怎么检查主手装备, 刷新展示, 以及怎么设置星级和发放材料
强化配方	`recipes/*.yml` 里怎么配成功率, 材料消耗, 失败惩罚, 效果和动作
流程说明	一次强化从匹配配方, 到写入 PDC, 再到刷新展示的完整流程
分支树系统	按星级段划分的强化路线, 以及不同路线各自给出哪些属性, 技能和展示
广播系统	首次达到指定星级时, 怎么向周围或全服发通知
占位符	PlaceholderAPI 占位符的输出
CoreLib 动作	用来重建或修改主手强化层的动作段
API 接入	通过 `EmakiStrengthenApi` 读取状态, 预览和执行强化
事件 API	强化流程里的 Bukkit 事件和拦截点

核心概念

概念	说明
强化星级	装备当前强化等级, 例如 +1, +2, +10
强化配方	定义哪些装备能强化, 需要哪些材料, 成功率和结果
材料计划	判断并消耗强化材料, 保护材料和锻印材料
锻印 (temper)	失败时累积的等级, 按 `temper_chance_bonus_per_level` 提升后续成功率
失败降星	目标星级 ≥ 6 且未使用保护材料时, 失败会降 1 星
保护材料	`protection: true` 的材料, 失败时阻止降星
分支树	在指定星级后分叉为不同强化路线
强化层	写入装备的 strengthen namespace layer, 由 CoreLib 重建展示

默认配置目录

text

plugins/EmakiStrengthen/
├── config.yml
├── recipes/
│   ├── example_recipe.yml
│   └── example_branch_recipe.yml
├── enhancement_recipes/
│   ├── example_enhancement_recipe.yml
│   ├── example_affix_recipe.yml
│   └── example_gem.yml
├── gui/
│   ├── strengthen_gui.yml
│   └── affix_strengthen_gui.yml
└── lang/
    ├── zh_CN.yml
    └── en_US.yml

你要配星级强化, 改 recipes/*.yml; 通用强化框架 (装备 / 词条 / 宝石) 的配方放在 enhancement_recipes/*.yml. 界面布局则看两份文件: gui/strengthen_gui.yml 管星级强化, gui/affix_strengthen_gui.yml 管词条强化

`config.yml` 主配置

想配 success_rates, 看流程说明; 想配 local_broadcast_radius 与 broadcast.*, 看广播系统. 其余字段如下:

字段	类型	必填	默认值	取值范围	说明
`version`	string	否	`4.8.9`	—	配置结构的版本标记; 默认资源版本由资源同步流程维护. 源码内部还有两个用途不同的常量: 这个键为空时回退到 `4.5.9`, 完全没有配置文件时 `AppConfig.defaults()` 用 `4.2.9`. 这两个值都不是发布版本号
`language`	string	否	`zh_CN`	—	使用 `lang/<language>.yml` 语言文件
`release_default_data`	boolean	否	`true`	`true` / `false`	当配方, GUI 与语言资源缺失时, 是否释放内置的默认版本
`affix.max_level`	integer	否	`10`	≥ 0 (负值按 `0` 处理)	单条词条的强化等级上限; `0` 表示不设上限
`affix.capacity_max`	integer	否	`100`	≥ 0 (负值按 `0` 处理)	单件装备可以分配给词条的总容量
`affix.capacity_cost_per_level`	integer	否	`10`	≥ 0 (负值按 `0` 处理)	每提升一级词条要消耗的容量; 容量不够时本次强化不执行
`affix.bonus_per_level`	double	否	`1.0`	有限数 (非有限值按 `0` 处理)	每提升一级词条增加的属性值
`enhancement.reject_container_target`	boolean	否	`false`	`true` / `false`	启用后, 放在外部容器 (比如箱子) 里的目标物品会被拒绝, 免得在预览和确认之间被其他玩家取走
`enhancement.reject_container_material`	boolean	否	`false`	`true` / `false`	启用后, 放在外部容器 (比如箱子) 里的材料会被拒绝, 免得确认时按旧数量扣了费却拿不到材料
`enhancement.min_success_rate`	double	否	`0.0`	`0.0`~`1.0` (比例; `≤0` 或非有限按 `0`, `>1` 按 `1`)	成功率的最低下限; 只有当递减把成功率压得太低时才会抬升, 不会压低本来就更高的成功率, 保底 (连续失败到一定次数后必定成功) 的强制成功也不受影响. `0.0` 表示不设下限
`enhancement.diminishing_returns.per_level`	double	否	`0.0`	`0.0`~`1.0`	每超出 `start_level` 一级, 就按这个比例削减基础成功率. `0.0` 关闭
`enhancement.diminishing_returns.start_level`	integer	否	`1`	≥ 1	从这一级起开始递减; 低于这一级的强化不受影响
`enhancement.cost_growth.per_level`	double	否	`0.0`	≥ 0	每升一级追加的费用比例 (倍率). `0.0` 关闭
`enhancement.cost_growth.max_multiplier`	double	否	`0.0`	≥ 0 (`0` 表示不设上限)	费用倍率上限
`enhancement.failure_demotion.levels`	integer	否	`0`	≥ 0 (`0` 表示不降级)	单次失败回退的等级数
`enhancement.failure_demotion.floor_level`	integer	否	`0`	≥ 0	回退不会低于这一级
`enhancement.pity_retry.interval_ticks`	integer	否	`0`	≥ 0 (`0` 不启动重试任务)	保底计数写到文件失败后的重试间隔, 单位是 tick (一个游戏刻, 也就是 1/20 秒)
`enhancement.pity_retry.max_attempts`	integer	否	`0`	≥ 0 (`0` 不启动重试任务)	连续失败达到这个次数后停止重试并告警
`enhancement.mastery.exp_per_attempt`	double	否	`0.0`	≥ 0	每次强化 (不论成功还是失败) 获得的熟练度经验; 只在费用, 材料与目标都提交成功后才记账
`enhancement.mastery.exp_per_success`	double	否	`0.0`	≥ 0	强化成功时额外获得的熟练度经验
`enhancement.mastery.soft_cap`	integer	否	`0`	≥ 0 (`0` 表示不限)	熟练度等级的软上限; 每累计 100 点经验算一级. 两项经验都填 `0` 时, 完全不写熟练度数据

下面是自带的默认值 (只列节选, success_rates, local_broadcast_radius, broadcast.* 见对应页面):

yaml

version: "4.8.9"
language: "zh_CN"
release_default_data: true
affix:
  max_level: 10
  capacity_max: 100
  capacity_cost_per_level: 10
  bonus_per_level: 1.0
enhancement:
  reject_container_target: false
  reject_container_material: false
  min_success_rate: 0.0
  diminishing_returns:
    per_level: 0.0
    start_level: 1
  cost_growth:
    per_level: 0.0
    max_multiplier: 0.0
  failure_demotion:
    levels: 0
    floor_level: 0
  pity_retry:
    interval_ticks: 0
    max_attempts: 0
  mastery:
    exp_per_attempt: 0.0
    exp_per_success: 0.0
    soft_cap: 0

使用示例: 从 +6 起每级削减 8% 基础成功率, 并给成功率设 5% 下限:

yaml

enhancement:
  min_success_rate: 0.05
  diminishing_returns:
    per_level: 0.08
    start_level: 6

典型强化流程

你用 /estrengthen open 打开强化 GUI
放入目标装备, 强化材料和可选的保护材料
模块按配方顶层的 matcher 与 slot_groups 等字段匹配可用的强化配方
检查条件, 材料, 经济费用和当前星级上限
算成功率: 目标星级基础成功率加锻印加成, 再钳到不超过 success_chance_cap
触发 StrengthenPreAttemptEvent, 允许外部改写成功率或取消
执行随机判定, 并扣除材料与费用
成功时星级 +1, 写入强化层, 执行该星级的 actions.success
失败时按规则累积锻印并可能降星, 执行 actions.failure
CoreLib 重建装备展示; 首次达到广播星级时, 发送本地或全服广播

与 Attribute 的关系

Strengthen 也可以只当展示和成长系统来用. 你装上 EmakiAttribute 并配置 ea_attribute 效果后, 每个星级就能提供真实属性加成: 属性通过 EmakiAttribute 的权威 API 写进结构化的 PDC layer, 参与真实战斗计算

没装 EmakiAttribute 时走空操作路径, 强化照常完成, 但不写入属性

与 Item 的关系

装了 EmakiItem, Strengthen 会在按条件加载的 integration 包里通过 EmakiItemApi 注册物品层预览提供者, 让 EmakiItem 那边能预览强化层的内容. EmakiItem 没装或被禁用时, 注册会自动跳过或释放, 不影响强化功能

EmakiStrengthen ​

基本信息 ​

功能页面 ​

核心概念 ​

默认配置目录 ​

config.yml 主配置 ​

典型强化流程 ​

与 Attribute 的关系 ​

与 Item 的关系 ​