段（Section）与 Lore 池

所属：服主指南　·　相关：词缀 · 随机生成

段（Section）是可复用的 Lore 块，可以是静态文本，也可以是加权随机池或品质分支池。配置文件：sections/example_sections.yml（及任意 sections/*.yml）。

---

1. 段的三种形态

type	形态	用途
single	静态段	固定前缀 / 后缀 / Lore 文本
weight_join（= affix_pool）	加权随机池	从一组带权条目里随机抽 amount 个
quality_pool	品质分支池	按物品品质（tier）选不同子段

---

2. 静态段

sharp_prefix:
  type: single
  prefix: "<gray>锋利的</gray>"
  lore: "<dark_gray>—— 剑刃锋利无比</dark_gray>"

物品引用后，prefix 拼到名前，lore 追加一行。

---

3. 加权随机池（weight_join）

weapon_affix_pool:
  type: weight_join
  amount: 1                       # 抽几个（不放回）
  prefix: "<gray>锋利的</gray>"   # 池级前缀（可选）
  suffix: "<gray>之力</gray>"     # 池级后缀（可选）
  values:
    - "4::<gray>精致的</gray>"     # 格式：权重::内容
    - "3::<blue>冰霜的</blue>"
    - "2::<red>烈焰的</red>"
    - "1::<gold>神圣的</gold>"

条目格式

权重::内容：

• 5::<gray>锋利</gray> → 权重 5，内容 <gray>锋利</gray>。
• 省略 权重:: 则权重默认 1。

抽取算法：累计权重随机索引，抽完一个从池里移除（不放回），抽 amount 个。

内联前后缀

内容里可写 <prefix>...</prefix> 和 <suffix>...</suffix> 标签，渲染时会被抽出来当前 / 后缀，剩余部分作 Lore：

values:
  - "<prefix>烈焰的</prefix> 灼烧之刃 <suffix>之怒</suffix>"

---

4. 品质分支池（quality_pool）

根据物品 tier 选用不同子段：

quality_prefix_pool:
  type: quality_pool
  legendary: legendary_prefix    # tier=LEGENDARY → 用 legendary_prefix 段
  epic: epic_prefix
  rare: rare_prefix
  uncommon: uncommon_prefix

键是品质 ID（查询时小写），值是目标段 ID。物品 tier: LEGENDARY 时，渲染器查 legendary → 找到 legendary_prefix 段 → 取其 lore/prefix。

随机生成时，quality_pool 会进一步把命中的子段当 weight_join 池抽取，详见 随机生成。

---

5. 在物品里引用

my_sword:
  tier: EPIC
  sections:
    - quality_prefix_pool       # 按品质选前缀
    - weapon_affix_pool         # 随机抽一个词缀

渲染流程（SectionLoreRenderer.render(sectionIds, affixIds, tier)）：

1. 逐个段：池则抽取，静态则取文本。
2. 捕获第一个前缀 / 后缀。
3. 累积所有 Lore 行。
4. 再处理 affixes: 引用的词缀。

返回 RenderResult(prefix, suffix, loreLines, warnings)，并入结构化 Lore 的「段 Lore」段。

---

6. 段字段表

键	含义
type / source_key	段类型（single / weight_join / affix_pool / quality_pool）
target_key	目标映射键（可选）
prefix / suffix	前 / 后缀（静态或池级）
lore / description	Lore 文本
amount	池抽取数量（默认 1）
values	池条目（列表）或键值子段
metadata	元数据子段（扁平化为 meta.<key>）

---

7. 注册表与命令（开发者 / 管理）

QinhSectionRegistry.get(id): QinhSection?
QinhSectionRegistry.all(): List<QinhSection>
QinhSectionRegistry.idsBySourceFormat(fmt): List<String>

管理命令：/qi sections、/qi sections summary、/qi sections formats、/qi sections format，见 命令。

🖼️ [图片占位] 一件带随机前缀 + 词缀 Lore 的物品 hover 截图，标注「前缀来自 quality_pool、Lore 来自 weight_join」　·　建议 assets/section-affix-render.png

---

下一步

• 随机生成：把段 / 词缀池接进随机掉落
• 词缀：定义具名词缀