品质 / Tier 与显示排版
本章讲两件互相关联的事：品质（Tier） 怎么定义，以及最终物品 Lore 怎么排版。
第一部分：品质 / Tier
配置文件：plugins/QinhItems/item_tiers.yml。
1. Tier 是什么
Tier 是物品的稀有度等级（普通 / 稀有 / 史诗 / 传说…），它控制：
- 显示：在 Lore 顶部显示带颜色的品质名。
- 光效：可选的物品发光提示。
- 随机生成参数：被随机抽中的权重（
chance）、能容纳多少词缀的容量（capacity）。
物品通过 tier: EPIC（大写）引用一个 Tier。
2. item_tiers.yml 结构
tiers:
TRASH:
name: '<gray>废品</gray>' # 显示名（MiniMessage）
generation:
chance: 0.05 # 随机生成时被抽中的权重
COMMON:
name: '<gray>普通</gray>'
generation:
chance: 0.30
capacity: # 词缀容量参数
base: 2 # 基础槽位
scale: 0.25 # 缩放变量（×随机[0,1)）
spread: 0.1 # 额外变量
max-spread: 0.25 # 高端额外变量
LEGENDARY:
name: '<gold><bold>传说</bold></gold>'
item-glow: # 发光提示
hint: false
color: GOLD # Bukkit DyeColor
generation:
chance: 0.08
capacity:
base: 10
scale: 1.2
spread: 0.12
max-spread: 0.35
EPIC:
name: '<light_purple><bold>史诗</bold></light_purple>'
unidentification: # 未鉴定显示
name: '史诗'
prefix: '<light_purple>'
generation:
chance: 0.06
capacity:
base: 12
scale: 1.5
spread: 0.15
max-spread: 0.43. Tier 字段表
| 键 | 类型 | 含义 |
|---|---|---|
name | String（必填） | 带颜色的显示名（MiniMessage） |
unidentification.name | String | 未鉴定时的纯文本名（默认从 name 去色得到） |
unidentification.prefix | String | 未鉴定前缀 |
item-glow.hint | Boolean | 是否显示发光提示 |
item-glow.color | String | Bukkit DyeColor 名（如 GOLD） |
generation.chance | Double | 该 Tier 被随机抽中的权重（0–1，但其实是相对权重） |
generation.capacity.base | Double | 词缀容量基础值（保底槽位） |
generation.capacity.scale | Double | 缩放项（结果 += scale × 随机[0,1)） |
generation.capacity.spread | Double | 散布项（同上叠加） |
generation.capacity.max-spread | Double | 高端散布项（也写 max_spread） |
容量怎么算成槽位数？ 见 随机生成 → 容量计算。公式：
base + scale×rand + spread×rand + maxSpread×rand，向下取整、不小于 0。
4. 品质解析顺序
物品显示时，QI 用 ItemTierRegistry.resolve() 决定用哪个 Tier，顺序：
definition.tier（YAML 里写的tier:）- 变量
values["tier"] - 变量
values["quality"]（按plainName或 id 匹配，大小写不敏感）
Tier 查找本身大小写不敏感（内部转小写），但 YAML 里建议大写以保持一致。
🖼️ [图片占位] 不同品质物品名的颜色对比图（废品/普通/稀有/史诗/传说） · 建议
assets/tier-colors.png
第二部分：Lore 显示排版
QI 用 StructuredLoreBuilder 把物品 Lore 按固定顺序自动拼装。理解这个顺序，你就知道每段内容从哪来、怎么调。
5. Lore 段顺序（从上到下）
| # | 段 | 来源 | 格式示例 |
|---|---|---|---|
| 1 | 品质名 | ItemTierRegistry.resolve() | <gold><bold>传说</bold></gold> |
| 2 | 物品类型 | 类型 display | 物品类型：武器 |
| 3 | 属性行 | providers.ap 解析 | 攻击伤害: 22、暴击几率: +12% |
| 4 | 分隔线 | 自动 | ────────────────（当上有属性、下有内容时插入） |
| 5 | 段 Lore | Section 渲染 | 词缀池产出的行 |
| 6 | 宝石状态 | gem-state | ▪ 已镶嵌 xxx |
| 7 | 动作 Lore | 技能描述 | ▸ 雷霆斩 |
| 8 | 宝石空孔 | gem-sockets | [ + ] 空孔 |
| 9 | 套装 Lore | Set 渲染 | 套装件数 / 加成 |
| 10 | 描述 / 风味 | lore: 字段 | 你写的描述行 |
| 11 | 需求 | options.restrictions | ✔ 需求: 等级 20 / ✘ 需求: … |
| 12 | 灵魂绑定 | 实例数据 | xxx 的物品，见 灵魂绑定 |
| 13 | 耐久 | 可损耗且非无限耐久 | 耐久度: 980 / 1000 |
注意：你在
lore:字段里写的内容落在第 10 段（描述 / 风味），品质、属性、套装等是自动生成插在它前面的，不用你手写。
6. 属性显示标签
属性行的标签来自 ApDisplayLabels。内置中文标签：
| 键 | 标签 | 键 | 标签 |
|---|---|---|---|
attack_damage | 攻击伤害 | armor | 护甲 |
attack_speed | 攻击速度 | armor_toughness | 护甲韧性 |
crit_rate | 暴击几率 | movement_speed | 移动速度 |
crit_damage | 暴伤增幅 | knockback_resistance | 击退抗性 |
max_health | 生命上限 | lifesteal | 生命偷取 |
damage_reduction | 伤害减免 | skill_damage | 技能伤害 |
pvp_damage | PVP 伤害 | pve_damage | PVE 伤害 |
未列入的键会回退成「下划线转空格、首字母大写」。数值若是 0–1 的比率（如 crit_rate）会显示成百分比 +12%。
7. 名称的前后缀与星级
物品名（display_name）在渲染时：
支持星级后缀的类型：weapon / armor / projectile / shield / gem。
8. 文本格式：MiniMessage
所有名称 / Lore 支持 MiniMessage（<gold>、<gradient:#A:#B>、<bold> 等）。也兼容传统 & / § 颜色码（会被 DisplayText.normalizeToMini 转换）。
display_name: "<gradient:#9141AC:#C41E3A>史诗之刃</gradient>"
lore:
- "<gray>普通灰色文字</gray>"
- "&e传统黄色（也支持）"