Section and Lore Pools

Belongs to: Server Owner Guide　·　Related: Affixes · Random Generation

A Section is a reusable Lore block. It can be static text, a weighted random pool, or a quality branch pool. Config file: sections/example_sections.yml (and any sections/*.yml).

---

1. The Three Forms of a Section

type	Form	Purpose
single	Static section	Fixed prefix / suffix / Lore text
weight_join (= affix_pool)	Weighted random pool	Randomly draw amount entries from a set of weighted items
quality_pool	Quality branch pool	Pick different sub-sections based on item quality (tier)

---

2. Static Section

sharp_prefix:
  type: single
  prefix: "<gray>Sharp</gray>"
  lore: "<dark_gray>—— The blade is razor-sharp</dark_gray>"

Once referenced by an item, prefix is prepended to the name and lore appends a line.

---

3. Weighted Random Pool (weight_join)

weapon_affix_pool:
  type: weight_join
  amount: 1                       # how many to draw (without replacement)
  prefix: "<gray>Sharp</gray>"   # pool-level prefix (optional)
  suffix: "<gray>of Power</gray>"     # pool-level suffix (optional)
  values:
    - "4::<gray>Refined</gray>"     # format: weight::content
    - "3::<blue>Frost</blue>"
    - "2::<red>Flame</red>"
    - "1::<gold>Holy</gold>"

Entry Format

weight::content:

• 5::<gray>Sharp</gray> → weight 5, content <gray>Sharp</gray>.
• Omitting weight:: defaults the weight to 1.

Draw algorithm: random index by cumulative weight; after drawing one it is removed from the pool (without replacement), repeating for amount draws.

Inline Prefix / Suffix

Within the content you can write <prefix>...</prefix> and <suffix>...</suffix> tags. During rendering they are extracted as the prefix / suffix, and the remaining part becomes Lore:

values:
  - "<prefix>Flame</prefix> Searing Blade <suffix>of Wrath</suffix>"

---

4. Quality Branch Pool (quality_pool)

Pick different sub-sections based on the item tier:

quality_prefix_pool:
  type: quality_pool
  legendary: legendary_prefix    # tier=LEGENDARY → use the legendary_prefix section
  epic: epic_prefix
  rare: rare_prefix
  uncommon: uncommon_prefix

The key is the quality ID (lowercased when queried), and the value is the target section ID. When an item has tier: LEGENDARY, the renderer looks up legendary → finds the legendary_prefix section → takes its lore/prefix.

During random generation, quality_pool will further treat the matched sub-section as a weight_join pool and draw from it. See Random Generation for details.

---

5. Referencing in an Item

my_sword:
  tier: EPIC
  sections:
    - quality_prefix_pool       # pick prefix by quality
    - weapon_affix_pool         # randomly draw one affix

Render flow (SectionLoreRenderer.render(sectionIds, affixIds, tier)):

1. For each section: if a pool, draw; if static, take the text.
2. Capture the first prefix / suffix.
3. Accumulate all Lore lines.
4. Then process the affixes referenced by affixes:.

Returns RenderResult(prefix, suffix, loreLines, warnings), merged into the "Section Lore" segment of the structured Lore.

---

6. Section Field Table

Key	Meaning
type / source_key	Section type (single / weight_join / affix_pool / quality_pool)
target_key	Target mapping key (optional)
prefix / suffix	Prefix / suffix (static or pool-level)
lore / description	Lore text
amount	Pool draw count (default 1)
values	Pool entries (list) or key-value sub-sections
metadata	Metadata sub-sections (flattened to meta.<key>)

---

7. Registry and Commands (Developer / Admin)

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

Admin commands: /qi sections, /qi sections summary, /qi sections formats, /qi sections format. See Commands.

🖼️ [Image placeholder] A hover screenshot of an item with a random prefix + affix Lore, annotated with "prefix comes from quality_pool, Lore comes from weight_join"　·　suggested assets/section-affix-render.png

---

Next Steps

• Random Generation: hook section / affix pools into random drops
• Affixes: define named affixes