Quality / Tier and Display Layout

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

This chapter covers two interrelated things: how quality (Tier) is defined, and how the final item's Lore is laid out.

Part 1: Quality / Tier

Configuration file: plugins/QinhItems/item_tiers.yml.

1. What is a Tier

A Tier is an item's rarity level (Common / Rare / Epic / Legendary…), and it controls:

Display: shows a colored quality name at the top of the Lore.
Glow: an optional item glow hint.
Random generation parameters: the weight of being randomly selected (chance), and the capacity for how many affixes it can hold (capacity).

An item references a Tier via tier: EPIC (uppercase).

2. `item_tiers.yml` Structure

yaml

tiers:
  TRASH:
    name: '<gray>Trash</gray>'              # Display name (MiniMessage)
    generation:
      chance: 0.05                         # Weight of being selected during random generation

  COMMON:
    name: '<gray>Common</gray>'
    generation:
      chance: 0.30
      capacity:                            # Affix capacity parameters
        base: 2                            # Base slots
        scale: 0.25                        # Scale variable (× random[0,1))
        spread: 0.1                        # Extra variable
        max-spread: 0.25                   # High-end extra variable

  LEGENDARY:
    name: '<gold><bold>Legendary</bold></gold>'
    item-glow:                             # Glow hint
      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>Epic</bold></light_purple>'
    unidentification:                      # Unidentified display
      name: 'Epic'
      prefix: '<light_purple>'
    generation:
      chance: 0.06
      capacity:
        base: 12
        scale: 1.5
        spread: 0.15
        max-spread: 0.4

3. Tier Field Table

Key	Type	Meaning
`name`	String (required)	Colored display name (MiniMessage)
`unidentification.name`	String	Plain text name when unidentified (defaults to `name` with color stripped)
`unidentification.prefix`	String	Unidentified prefix
`item-glow.hint`	Boolean	Whether to show the glow hint
`item-glow.color`	String	Bukkit `DyeColor` name (e.g. `GOLD`)
`generation.chance`	Double	Weight of this Tier being randomly selected (0–1, but really a relative weight)
`generation.capacity.base`	Double	Affix capacity base value (guaranteed slots)
`generation.capacity.scale`	Double	Scale term (result += scale × random[0,1))
`generation.capacity.spread`	Double	Spread term (added the same way)
`generation.capacity.max-spread`	Double	High-end spread term (also written `max_spread`)

How is capacity computed into a slot count? See Random Generation → Capacity Calculation. Formula: base + scale×rand + spread×rand + maxSpread×rand, floored, and not less than 0.

4. Quality Resolution Order

When displaying an item, QI uses ItemTierRegistry.resolve() to decide which Tier to use, in this order:

definition.tier (the tier: written in YAML)
The variable values["tier"]
The variable values["quality"] (matched by plainName or id, case-insensitive)

Tier lookup itself is case-insensitive (converted to lowercase internally), but uppercase is recommended in YAML for consistency.

🖼️ [Image placeholder] Color comparison of item names across different qualities (Trash/Common/Rare/Epic/Legendary)　·　suggested assets/tier-colors.png

Part 2: Lore Display Layout

QI uses StructuredLoreBuilder to automatically assemble an item's Lore in a fixed order. Once you understand this order, you'll know where each section comes from and how to adjust it.

5. Lore Section Order (top to bottom)

#	Section	Source	Format example
1	Quality name	`ItemTierRegistry.resolve()`	`<gold><bold>Legendary</bold></gold>`
2	Item type	Type `display`	`Item Type: Weapon`
3	Attribute lines	`providers.ap` resolution	`Attack Damage: 22`, `Crit Rate: +12%`
4	Divider	Automatic	`────────────────` (inserted when there are attributes above and content below)
5	Section Lore	Section rendering	Lines produced by the affix pool
6	Gem state	`gem-state`	`▪ Embedded xxx`
7	Action Lore	Skill description	`▸ Thunder Strike`
8	Empty gem sockets	`gem-sockets`	`[ + ] Empty socket`
9	Set Lore	Set rendering	Set piece count / bonuses
10	Description / Flavor	`lore:` field	The description lines you write
11	Requirements	`options.restrictions`	`✔ Requirement: Level 20` / `✘ Requirement: …`
12	Soul Binding	Instance data	`xxx's item`, see Soul Binding
13	Durability	Depletable and not infinite durability	`Durability: 980 / 1000`

Note: what you write in the lore: field lands in section 10 (Description / Flavor); quality, attributes, sets, etc. are automatically generated and inserted before it — you don't write them by hand.

6. Attribute Display Labels

The labels for attribute lines come from ApDisplayLabels. Built-in labels:

Key	Label	Key	Label
`attack_damage`	Attack Damage	`armor`	Armor
`attack_speed`	Attack Speed	`armor_toughness`	Armor Toughness
`crit_rate`	Crit Rate	`movement_speed`	Movement Speed
`crit_damage`	Crit Damage	`knockback_resistance`	Knockback Resistance
`max_health`	Max Health	`lifesteal`	Lifesteal
`damage_reduction`	Damage Reduction	`skill_damage`	Skill Damage
`pvp_damage`	PVP Damage	`pve_damage`	PVE Damage

Keys not listed fall back to "underscores to spaces, first letter capitalized." If a value is a 0–1 ratio (such as crit_rate), it is displayed as a percentage +12%.

7. Name Prefixes/Suffixes and Star Levels

When the item name (display_name) is rendered:

Variable substitution is done first ({variable}).
Then the prefixes / suffixes produced by Sections / Affixes are applied.
If the type supports star levels and values["star"] > 0, [+N] is appended to the end of the name.

Types that support the star-level suffix: weapon / armor / projectile / shield / gem.

8. Text Format: MiniMessage

All names / Lore support MiniMessage (<gold>, <gradient:#A:#B>, <bold>, etc.). Legacy & / § color codes are also supported (converted by DisplayText.normalizeToMini).

yaml

display_name: "<gradient:#9141AC:#C41E3A>Blade of the Epic</gradient>"
lore:
  - "<gray>Plain gray text</gray>"
  - "&eLegacy yellow (also supported)"

Next Steps

Make quality participate in random drops → Random Generation
Add prefixes/suffixes to names with affix pools → Affixes / Sections
Configure attribute values → Attributes and Values

Quality / Tier and Display Layout ​

Part 1: Quality / Tier ​

1. What is a Tier ​

2. item_tiers.yml Structure ​

3. Tier Field Table ​

4. Quality Resolution Order ​

Part 2: Lore Display Layout ​

5. Lore Section Order (top to bottom) ​

6. Attribute Display Labels ​

7. Name Prefixes/Suffixes and Star Levels ​

8. Text Format: MiniMessage ​

Next Steps ​