Affix

Belongs to: Server Owner Guide　·　Related: Section · Random Generation · Quality and Display

An affix is a reusable modifier package: it adds a prefix / suffix to an item's name and appends a line of Lore. Combined with the pool mechanism of Sections, it can implement random affixes.

---

1. What Is an Affix

An affix (QinhAffix) is essentially a named container carrying "prefix / suffix / Lore + arbitrary metadata". Items reference it through the affixes: list. Affixes are usually used together with Sections and Random Generation.

Data model:

data class QinhAffix(
    val id: String,
    val sourceFormat: String = "generic",   // Source classification
    val category: String = "generic",        // Group tag
    val weight: Int = 0,                      // Weight for weighted random (≥0)
    val modifiers: Map<String,String>,
    val metadata: Map<String,String>,         // prefix / suffix / lore etc. all live here
)

Common keys in metadata: prefix, suffix, lore, affix_id, source_id, source_format.

---

2. Declaring Affixes

Usually written in the affixes: section of some YAML file under sections/ (see sections/example_sections.yml for an example):

affixes:

  legendary_weapon_affix:
    prefix: "<gold>Legendary</gold> "
    lore: "<gold>◆ Infused with legendary power</gold>"

  epic_weapon_affix:
    prefix: "<gradient:#9141AC:#C41E3A>Epic</gradient> "
    lore: "<gradient:#9141AC:#C41E3A>◆ Epic power</gradient>"

  guardian_affix:
    suffix: " <gray>Guardian</gray>"
    lore: "<blue>◆ Power of the guardian</blue>"

Recognized Top-Level Keys

Key	Meaning
weight / priority	Weight (default 0)
category	Group (default generic)
source_format	Source format (default generic)
metadata	Metadata sub-section
values	Key-value sub-section merged into metadata
Any other key	Collected as a metadata key-value (e.g. prefix / suffix / lore)

---

3. Referencing It in an Item

my_sword:
  affixes:
    - legendary_weapon_affix
    - guardian_affix

During rendering (SectionLoreRenderer):

• The affix metadata's prefix / suffix is concatenated onto the item name (the first non-empty one is captured as the prefix / suffix).
• The lore is appended as a line of Lore (placed in the "Section Lore" section of the structured Lore).

---

4. Affix vs Section: How to Choose

	Affix	Section
Form	A single fixed modifier package	Can be static text, or a weighted random pool / quality pool
Randomness	No randomness of its own (a pool picks it)	Built-in weight_join / quality_pool randomness
Typical use	A single named affix	"Randomly draw N from a bunch of affixes"

In short: an affix is the "ingredient", a section is "how the ingredient is drawn". For random prefixes/suffixes, use a section's weight_join/quality_pool pool; to fixedly attach one affix, reference it directly with affixes:. See Section for details.

---

5. Registry Queries (Developer)

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

Management commands: /qi affixes, /qi affixes summary, /qi affixes categories, /qi affixes formats, see Commands.

---

Next Steps

• Section: weighted random pools, quality pools
• Random Generation: draw affixes from a pool by capacity