品质系统

品质系统决定锻造结果的品质等级，影响材料效果的数值倍率和物品展示。

全局品质配置

品质在 config.yml 的 quality 节点中全局配置：

yaml

quality:
  tiers:
    - name: "平庸"
      weight: 60
      multiplier: 1.0
    - name: "精良"
      weight: 30
      multiplier: 1.05
    - name: "完美"
      weight: 1
      multiplier: 1.2
  default_tier: "平庸"
  guarantee:
    enabled: true
    threshold: 60
    minimum: "无暇"
  item_meta:
    enabled: true
    tiers:
      完美:
        name_actions:
          - action: "prepend_prefix"
            value: "<color:#FFD700>[完美] </color>"
        lore_actions: []
        action:
          - 'broadcastmessage text="<color:#FFD700>%player_name%锻造出了一个完美品质的<show_item></color>"'

tiers 格式

推荐写法是每项一个记录：

字段	类型	说明
`name`	string	品质的唯一标识和显示名。为空时该项被忽略。
`weight`	integer	抽取权重，越大越常见。必须大于 0，否则该项被忽略。
`multiplier`	number	材料效果数值的乘数（`配置值 × 材料数量 × 品质倍率`）。默认 `1.0`。

也兼容 "品质名-权重-倍率" 的字符串写法（按 - 分成三段），但当前配置线推荐使用上面的记录写法。

tiers 全部解析失败时会回退到内置默认品质池（单一品质 普通，权重 100，倍率 1.0），且保底与 item_meta 均关闭。

保底机制

下表「键缺失时的回退值」是配置里没写该键时代码采用的值，与随包 config.yml 的发布值不同。随包发布值为 enabled: true、threshold: 60、minimum: "无暇"，即默认配置本身是开启保底的。

字段	类型	键缺失时的回退值	随包发布值	说明
`guarantee.enabled`	boolean	`false`	`true`	是否启用全局保底。
`guarantee.threshold`	integer	`10`	`60`	连续未达到最低品质的次数阈值。达到后保底触发。
`guarantee.minimum`	string	`普通`	`无暇`	保底触发时的最低品质等级。

保底判定规则：

每次锻造后比较本次抽中的品质在品质池中的位次与保底最低品质的位次。
位次更低时保底计数 +1；否则保底计数重置为 0。
计数达到 threshold - 1 后，下一次锻造直接给出保底品质并重置计数。

保底计数器按玩家 + 配方维度记录，保存在 data/<玩家UUID>.yml。quality_modify 的 force 模式会跳过全部保底逻辑，既不触发保底也不更新计数。

item_meta 品质写入

当 item_meta.enabled: true 时，锻造成功后会根据品质等级对结果物品执行额外操作：

字段	说明
`name_actions`	按品质等级对物品名称执行操作。
`lore_actions`	按品质等级对物品 Lore 执行操作。
`action`	按品质等级执行动作列表（如全服广播）。

确定性算法

品质计算使用确定性算法：品质由玩家、配方和材料构成的指纹加上预览种子计算得出，而不是每次现掷随机数。内部对该 roll key 取 SHA-256，用哈希前 12 位十六进制字符换算成 0~1 的比例，再在品质池上做加权选择。

准备好的锻造结果缓存 TTL 为 30 秒，因此：

玩家在 GUI 中看到的品质结果与实际锻造结果一致。
30 秒内重复提交相同输入不会改变结果。
更换材料或等待缓存过期后结果会变化。

配方级别品质覆盖

每个配方可以在 quality 节点中覆盖全局配置。注意配方级字段名与全局配置不同：

yaml

quality:
  enabled: true
  custom_pool:
    - "普通-50-1.0"
    - "精良-35-1.08"
    - "史诗-15-1.25"
  guarantee:
    enabled: true
    attempts: 5
    minimum: "精良"

字段	类型	默认值	说明
`enabled`	boolean	`false`	是否启用配方级品质配置。
`custom_pool`	list<string>	空	配方专用品质池，使用 `"品质名-权重-倍率"` 字符串写法。为空时使用全局 `quality.tiers`。
`guarantee.enabled`	boolean	`false`	是否启用配方级保底。
`guarantee.attempts`	integer	`10`	配方级保底阈值。对应全局配置的 `threshold`。
`guarantee.minimum`	string	`普通`	配方级保底最低品质。

配方级保底未启用而全局保底已启用时，回退到全局的 threshold 与 minimum。

与材料效果的交互

variables 效果值 = 配置值 × 材料数量 × 品质倍率
ea_attribute 效果值 = 配置值 × 材料数量 × 品质倍率
quality_modify 的 force 模式会跳过保底判定与计数更新
quality_modify 的 minimum 模式只在抽中品质低于指定品质时把结果提升到该品质

材料效果的详细写法见材料系统。

品质系统 ​

全局品质配置 ​

tiers 格式 ​

保底机制 ​

item_meta 品质写入 ​

确定性算法 ​

配方级别品质覆盖 ​

与材料效果的交互 ​