Advanced Recipes (Variables / Sections / Set Combinations)

Belongs to: Server Owner Guide　·　Related: Variables · Sections · Sets

Complex practical recipes that combine variables, sections, affixes, sets, and actions. See the respective chapters for the basic concepts.

---

Recipe 1: Randomized-Value Weapon (Multi-Variable Linkage)

Each weapon rolls a random damage range and shows it in the lore:

random_blade:
  type: weapon
  material: iron_sword
  display_name: "<gold>Blade of {quality_word}</gold>"
  lore:
    - ""
    - "<gray>Damage: <red>{min_dmg} - {max_dmg}</red></gray>"
    - "<gray>Crit: <yellow>{crit}%</yellow></gray>"
  variables:
    min_dmg: "12 - 18"          # randomized per item
    max_dmg: "24 - 32"
    crit: "5 - 15"
    quality_word: "Trial"
  providers:
    ap:
      value: '{"attack_damage":18}'

Variables only affect the display; the actual attribute values live in providers.ap. To keep the display consistent with the attributes, you must coordinate the two yourself, or use the capacity / affix mechanisms of Random Generation. See Variables for the variable mechanism.

---

Recipe 2: Quality Prefix + Random Affix + Suffix (Three-Layer Stacking)

epic_blade:
  type: weapon
  material: netherite_sword
  tier: EPIC
  display_name: "<white>Judgment</white>"
  sections:
    - quality_prefix_pool       # add a quality prefix based on tier (Epic)
    - weapon_affix_pool         # randomly draw one weapon affix (with prefix/suffix)
  affixes:
    - guardian_affix            # always append the "Guardian" suffix
  lore:
    - ""
    - "<gray>Empowered by three affixes</gray>"
  providers:
    ap:
      value: '{"attack_damage":30,"crit_rate":0.15}'
  options:
    unbreakable: true
    glow: true

Render order: quality prefix + affix prefix → item name → affix suffix + guardian suffix; the lore accumulates the description lines of each section / affix. See Sections for the section mechanism, Affixes for affixes, and Quality and Display for display order.

---

Recipe 3: Nested Quality Pools (Different Quality → Different Affix Pool)

Configure two-level pools in sections/:

# quality pool: routes to a sub-pool by tier
quality_damage_pool:
  type: quality_pool
  legendary: dmg_pool_legendary
  epic: dmg_pool_epic
  rare: dmg_pool_rare

# per-quality sub-pools (weight_join)
dmg_pool_rare:
  type: weight_join
  amount: 1
  values:
    - "3::<gray>+8 Damage</gray>"
    - "2::<gray>+10 Damage</gray>"

dmg_pool_legendary:
  type: weight_join
  amount: 1
  values:
    - "3::<gold>+25 Damage</gold>"
    - "1::<gold>+35 Damage</gold>"

The item references quality_damage_pool; during random generation it picks the matching sub-pool by the item's tier and draws from it. See Random Generation for random generation.

---

Recipe 4: Set + Event Skill Chain

Once the set is complete, automatically counterattack when hit and heal when killing:

# sets/guardian.yml
guardian_set:
  display_name: "<aqua>Guardian</aqua>"
  icon: SHIELD
  belonging_pieces:
    - "guardian"                # all guardian_xxx count
  lore:
    - "<gray>The legacy of the Guardian</gray>"
  bonuses:
    - pieces: 2
      name: "Bulwark"
      attributes:
        防御: 20
    - pieces: 4
      name: "<aqua>Guardian Bastion</aqua>"
      lore:
        - "<aqua>Cumulative +50 Defense</aqua>"
        - "<gray>Counterattack on hit / heal on kill</gray>"
      attributes:
        防御: 30                # cumulative +50 across 4 pieces
      effects:
        DAMAGE_RESISTANCE: 0
      abilities:
        - trigger: on_hit       # auto-triggers when hit
          cooldown: 4s
          actions:
            - {handler: "qinhskills:cast", payload: "守护反击"}
        - trigger: on_kill      # auto-triggers on kill
          cooldown: 2s
          actions:
            - {handler: "qinhskills:cast", payload: "战意回血"}

Event-type abilities auto-trigger once enough pieces are worn (independent of which item is held). See Sets for the set mechanism; skills are handled by QinhSkills.

---

Recipe 5: Star Enhancement Display

Use the star variable to drive a [+N] suffix on the name (types that support stars: weapon/armor/projectile/shield/gem):

upgradable_sword:
  type: weapon
  material: diamond_sword
  display_name: "<gold>Refined Blade</gold>"
  variables:
    star: "3"                   # name suffix shows [+3]
  providers:
    ap:
      value: '{"attack_damage":20}'

An enhancement system can change star at runtime via the Layer API / Variable API.

---

Recipe 6: Restriction + Binding + Trigger Combination (High-End Gear)

boss_drop_blade:
  type: weapon
  material: netherite_sword
  tier: LEGENDARY
  display_name: "<gradient:#FFD700:#FF4500>Worldender</gradient>"
  providers:
    ap:
      value: '{"attack_damage":40,"crit_rate":0.25}'
  options:
    unbreakable: true
    glow: true
    bind_on_acquire: true       # bound on pickup, prevents trading
    restrictions:
      - "level:40"              # usable only at level 40
      - "permission:rank.vip"   # VIP exclusive
  actions:
    triggers:
      shift_left_click:
        trigger: { atom: shift_left_click }
        cooldown: 8s
        consume:
          - "level:3"
        refs:
          - handler: qi:title
            payload: "<dark_red>World-Ending Strike</dark_red>||||5||30||10"
          - handler: qinhskills:cast
            payload: '{"skill":"apocalypse","level":3}'

See Soul Binding for binding, Item Definition for restrictions, and Action System for actions.

---

Next Steps

• Variables / Sections / Sets: underlying mechanisms
• Random Generation: affix pools + capacity
• Item Example Library: built-in examples