词缀（Affix）

所属：服主指南　·　相关：段 · 随机生成 · 品质与显示

词缀是可复用的修饰包：给物品名加前缀 / 后缀、追加一行 Lore。配合段（Section）的池机制，可实现随机词缀。

---

1. 词缀是什么

一个词缀（QinhAffix）本质是一个携带「前缀 / 后缀 / Lore + 任意元数据」的命名容器。物品通过 affixes: 列表引用它。词缀通常和段、随机生成一起用。

数据模型：

data class QinhAffix(
    val id: String,
    val sourceFormat: String = "generic",   // 来源分类
    val category: String = "generic",        // 分组标签
    val weight: Int = 0,                      // 加权随机的权重（≥0）
    val modifiers: Map<String,String>,
    val metadata: Map<String,String>,         // prefix / suffix / lore 等都在这
)

metadata 里常见键：prefix、suffix、lore、affix_id、source_id、source_format。

---

2. 声明词缀

通常写在 sections/ 下某个 YAML 的 affixes: 段（示例见 sections/example_sections.yml）：

affixes:

  legendary_weapon_affix:
    prefix: "<gold>传说</gold> "
    lore: "<gold>◆ 传说之力灌注</gold>"

  epic_weapon_affix:
    prefix: "<gradient:#9141AC:#C41E3A>史诗</gradient> "
    lore: "<gradient:#9141AC:#C41E3A>◆ 史诗力量</gradient>"

  guardian_affix:
    suffix: " <gray>守护</gray>"
    lore: "<blue>◆ 守护之力</blue>"

顶层可识别键

键	含义
weight / priority	权重（默认 0）
category	分组（默认 generic）
source_format	来源格式（默认 generic）
metadata	元数据子段
values	并入 metadata 的键值子段
其它任意键	当作 metadata 键值收集（如 prefix / suffix / lore）

---

3. 在物品里引用

my_sword:
  affixes:
    - legendary_weapon_affix
    - guardian_affix

渲染时（SectionLoreRenderer）：

• 取词缀 metadata 的 prefix / suffix 拼到物品名（第一个非空者捕获为前 / 后缀）。
• 取 lore 追加为一行 Lore（落在结构化 Lore 的「段 Lore」段）。

---

4. 词缀 vs 段：怎么选

	词缀 Affix	段 Section
形态	单个固定修饰包	可以是静态文本，也可以是加权随机池 / 品质池
随机性	自身无随机（靠池选中它）	内置 weight_join / quality_pool 随机
典型用途	一个具名词缀	「从一堆词缀里随机抽 N 个」

简单说：词缀是「料」，段是「怎么抽料」。要随机前后缀，用段的 weight_join/quality_pool 池；要固定挂一个词缀，直接 affixes: 引用。详见 段。

---

5. 注册表查询（开发者）

QinhAffixRegistry.get(id): QinhAffix?
QinhAffixRegistry.all(): List<QinhAffix>
QinhAffixRegistry.idsBySourceFormat(fmt): List<String>
QinhAffixRegistry.idsByCategory(cat): List<String>
QinhAffixRegistry.affixesByCategory(cat): List<QinhAffix>

管理命令：/qi affixes、/qi affixes summary、/qi affixes categories、/qi affixes formats，见 命令。

---

下一步

• 段：加权随机池、品质池
• 随机生成：按容量从池抽词缀