Presets

Presets define reusable attribute patterns that reduce repetition and enforce consistency across patch specs.

They’re especially useful when you have many similar entries (weapon families, armor sets, tier progressions, shared tooltips, etc.).

If you’re looking for the overall “what’s supported”, see Capabilities.
If you want the YAML shapes for create/update/delete, see Syntax.

---

Two kinds of presets

1) Entity presets

Entity presets apply to top-level entities like:

• items
• equipment
• itemStrings

They are defined under presets.<entity> and referenced with preset: in create/update operations.

2) Block presets

Block presets apply to nested blocks inside an entity, like:

• items.create[].equipment.compute
• items.create[].equipment.override
• other nested structures where you want deep merge behavior

They are defined under presets.blocks.<namespace> and referenced with preset: inside the nested block (example below).

---

Defining entity presets

Entity presets live under the presets section, grouped by entity type:

presets:
  items:
    weapon_base:
      combatItemType: "EQUIP_WEAPON"
      category: "weapon"
      maxStack: 1
      tradable: "True"
      destroyable: "True"

    armor_base:
      combatItemType: "EQUIP_ARMOR"
      category: "armor"
      maxStack: 1
      tradable: "True"

  equipment:
    standard_stats:
      atkRate: 1.0
      defRate: 1.0
      balanceRate: 1.0

---

Using entity presets

Reference a preset by name inside a create or update operation:

items:
  create:
    - id: 99001
      preset: weapon_base
      name: "Iron Sword"
      level: 10
      combatItemSubType: "TWOHAND"

For updates, presets are applied before changes:

items:
  update:
    - id: 99001
      preset: weapon_base
      changes:
        level: 20
        buyPrice: 250

---

Inheritance (extends)

Presets support single inheritance using extends:

presets:
  items:
    weapon_base:
      combatItemType: "EQUIP_WEAPON"
      category: "weapon"
      maxStack: 1

    rare_weapon:
      extends: weapon_base
      rareGrade: "Rare"
      tradable: "True"

    epic_sword:
      extends: rare_weapon
      combatItemSubType: "TWOHAND"
      rareGrade: "Unique"  # overrides inherited value

Inheritance rules (important)

1. Single inheritance only — each preset can extend one parent
2. Max depth: 10 — prevents unreadable inheritance chains
3. No circular references — cycles are rejected
4. Child wins — child values override parent values

How values resolve

Preset inheritance uses null-coalescing:

resolved_value = child_value ?? parent_value

So if the child defines a value, it wins; otherwise the parent’s value is used.

---

Apply order (preset vs operation)

After a preset is resolved (including inheritance), it is applied to the operation:

Final Value = operation_value ?? preset_value

Example:

presets:
  items:
    base:
      level: 10
      rareGrade: "Common"

items:
  create:
    - id: 99001
      preset: base
      level: 20       # overrides preset
      name: "My Item" # new property

Result:

• level = 20 (operation wins)
• rareGrade = "Common" (from preset)

---

List properties

Lists are replaced entirely, not merged:

presets:
  items:
    base:
      requiredClass:
        - WARRIOR
        - LANCER

items:
  create:
    - id: 99001
      preset: base
      requiredClass:
        - ARCHER
        - SORCERER

Result: requiredClass becomes [ARCHER, SORCERER].

---

Equipment presets (common pattern)

Equipment presets behave the same as item presets:

presets:
  equipment:
    weapon_stats:
      atkRate: 1.0
      defRate: 1.0
      countOfSlot: 2

    elite_weapon:
      extends: weapon_stats
      atkRate: 1.2
      countOfSlot: 4

They can be used inside inline equipment blocks on items:

items:
  create:
    - id: 99001
      name: "Elite Sword"
      combatItemType: "EQUIP_WEAPON"

      equipment:
        preset: elite_weapon
        computed: true

If you’re using computed equipment, see Equipment computation.

---

ItemStrings presets (name/toolTip)

ItemStrings presets work the same way:

presets:
  itemStrings:
    common_tooltip:
      toolTip: "Right-click to use."

    quest_item:
      extends: common_tooltip
      toolTip: "Quest item. Cannot be sold or traded."

Used in inline strings: blocks:

items:
  create:
    - id: 99001
      name: "QuestItem"

      strings:
        preset: quest_item
        name: "Ancient Artifact"  # required for create

Important: name is always required when creating a string entry and cannot be inherited from presets. Presets can reliably carry shared toolTip text.

---

Merge order with computation (equipment)

When inline equipment uses computation, the full precedence is:

Final Value = override_value ?? computed_value ?? preset_value

1. Preset values — baseline from equipment preset
2. Computed values — auto-calculated stats (when computed: true)
3. Override values — explicit overrides always win

See Equipment computation for details.

---

Block presets (nested configurations)

Block presets enable reusable configuration for nested blocks within entities.

When to use block presets

Use block presets when many entities share the same nested configuration, e.g.:

• many weapons with identical computation settings
• an armor set sharing slot configuration
• multiple tiers with consistent scaling inputs

Defining block presets

Block presets live under presets.blocks.<namespace>:

presets:
  blocks:
    inlineEquipment:
      standard_weapon:
        compute:
          formula: "standard"
          powerTier: 5
        override:
          countOfSlot: 2
          balance: 50

Using a block preset

Reference it inside the nested block using preset::

items:
  create:
    - id: 99100
      name: "Iron Greatsword"
      preset: weapon_base

      equipment:
        preset: standard_weapon  # block preset (namespace: inlineEquipment)
        override:
          minAtk: 500            # override just one value

Block preset inheritance

Block presets can also extends another block preset (same rules as entity presets):

presets:
  blocks:
    inlineEquipment:
      weapon_base:
        compute:
          formula: "standard"
          powerTier: 5
        override:
          countOfSlot: 2

      elite_weapon:
        extends: weapon_base
        compute:
          powerTier: 7
        override:
          countOfSlot: 4
          atkRate: 1.2

Deep-merge behavior (why block presets exist)

Block presets use deep merge for nested objects:

• merge recursively at each level
• child overrides parent at the same path
• unspecified properties are inherited

This differs from entity presets where nested objects are typically replaced as a whole.

Block preset precedence

When combining a block preset with inline values:

Final Value = inline_value ?? block_preset_value

Inline values always win.

Entity presets can carry block preset references

You can include a nested block preset reference inside an entity preset so that it’s inherited:

presets:
  items:
    iron_weapon:
      equipment:
        preset: standard_weapon

  blocks:
    inlineEquipment:
      standard_weapon:
        compute:
          formula: "standard"

items:
  create:
    - id: 99100
      preset: iron_weapon
      name: "Iron Sword"

---

Limitations and best practices

Limitations

• No multiple inheritance (one extends)
• Inheritance depth limited (max 10)
• Lists replace, they don’t merge
• Presets are intended to stay readable; if you need heavy logic, use computation/features designed for it

Best practices

• Keep base presets small and stable
• Prefer composition (preset + a few inline overrides) over deep inheritance chains
• Use block presets when nested configs repeat frequently
• Name presets like you’d name code: weapon_base, rare_weapon, tier_3_weapon, quest_tooltip

---

Validation errors (common)

Error	Cause	Fix
E301	Unknown preset reference	Check preset name spelling
E302	Circular inheritance	Remove circular extends
E303	Inheritance depth > 10	Flatten the chain
E304	Unknown block preset reference	Check block preset name and namespace

If you hit these, also check Error codes.