MaterialEnchantData

Overview

MaterialEnchantData.xml defines material enchantment entries: upgrade costs, success rates, failure penalties, and material requirements for enchanting equipment through multiple enhancement steps.

Version Support

Version	Status
v92	Full
v90	-
v86	-

DSL Support

Entity: materialEnchants Operations: create, update, delete, upsert

materialEnchants:
  create:
    - materialEnchantId: 1
      maxEnchantCount: 9
      materialItems:
        - enchantStep: 0
          enchantProb: 1.0
          requiredMoney: 0
          materials:
            - id: 94101
              type: Item
              amount: 4

  update:
    - materialEnchantId: 1
      changes:
        maxEnchantCount: 12

  delete:
    - 1

  upsert:
    - materialEnchantId: 2
      maxEnchantCount: 6

Quick Recipes

Create a Basic Material Enchant

materialEnchants:
  create:
    - materialEnchantId: 1
      maxEnchantCount: 9

Creates a material enchant entry with ID 1 and maximum enchantment count of 9.

Create with Enchantment Steps

materialEnchants:
  create:
    - materialEnchantId: 1
      maxEnchantCount: 9
      materialItems:
        - enchantStep: 0
          enchantProb: 1.0
          requiredMoney: 0
        - enchantStep: 1
          enchantProb: 0.85
          requiredMoney: 1000
          hideProb: false
        - enchantStep: 2
          enchantProb: 0.70
          requiredMoney: 2500
          failRevisionProb: 0.1

Creates an enchant with three progressive steps, each with different success rates and costs. Step 0 has guaranteed success (1.0), while higher steps have reduced success probability.

Create with Material Requirements

materialEnchants:
  create:
    - materialEnchantId: 1
      maxEnchantCount: 9
      materialItems:
        - enchantStep: 0
          enchantProb: 1.0
          requiredMoney: 0
          materials:
            - id: 94101
              type: Item
              amount: 4
            - id: 94102
              type: Item
              amount: 2
        - enchantStep: 1
          enchantProb: 0.85
          requiredMoney: 1000
          materials:
            - id: 94103
              type: Item
              amount: 6

Creates an enchant where each step requires specific material items. Step 0 requires 4 units of item 94101 and 2 units of item 94102.

Create with Failure Penalties

materialEnchants:
  create:
    - materialEnchantId: 1
      maxEnchantCount: 9
      materialItems:
        - enchantStep: 3
          enchantProb: 0.60
          requiredMoney: 5000
          downStep: 1
          downProb: 0.3
          damageProb: 0.1

Creates an enchant step with failure consequences: 30% chance to downgrade by 1 step, 10% chance to damage the item.

Update Maximum Enchant Count

materialEnchants:
  update:
    - materialEnchantId: 1
      changes:
        maxEnchantCount: 12

Increases the maximum enchantment count for material enchant 1 from 9 to 12.

Update Enchantment Steps

materialEnchants:
  update:
    - materialEnchantId: 1
      changes:
        materialItems:
          - enchantStep: 0
            enchantProb: 1.0
            requiredMoney: 500
          - enchantStep: 1
            enchantProb: 0.90
            requiredMoney: 1500

Updates existing enchantment steps with new probabilities and costs. Targets steps by enchantStep identifier.

Delete a Material Enchant

materialEnchants:
  delete:
    - 1
    - 2
    - 3

Removes material enchant entries with IDs 1, 2, and 3 from the datasheet.

Upsert (Create or Update)

materialEnchants:
  upsert:
    - materialEnchantId: 1
      maxEnchantCount: 9
      materialItems:
        - enchantStep: 0
          enchantProb: 1.0
          requiredMoney: 0

Creates a new material enchant if ID 1 doesn’t exist, or replaces the existing entry completely if it does.

Properties Reference

ItemEnchant (Root)

Property	Type	Since	Required	Default	Description
materialEnchantId	int	v92	✅	—	Unique identifier for this material enchant entry
maxEnchantCount	int	v92	✅	—	Maximum number of enchantment steps allowed for this entry
materialItems	list	v92	❌	—	List of enchantment step configurations (up to maxEnchantCount entries)

MaterialItem (Nested)

Represents a single enchantment step configuration. Identified by enchantStep within its parent ItemEnchant.

Property	Type	Since	Required	Default	Description
enchantStep	int	v92	✅	—	Step number (0-based index, must be < maxEnchantCount)
enchantProb	decimal	v92	✅	—	Success probability for this step (0.0 to 1.0)
requiredMoney	int	v92	✅	—	Gold cost required to attempt this enchantment step
failRevisionProb	decimal	v92	❌	—	Probability of a “fail revision” outcome on failure (0.0 to 1.0)
hideProb	bool	v92	❌	—	Whether to hide the success probability from the player UI
downStep	int	v92	❌	—	Number of steps to downgrade on failure (must be ≤ enchantStep)
downProb	decimal	v92	❌	—	Probability of downgrading on failure (0.0 to 1.0)
damageProb	decimal	v92	❌	—	Probability of item damage/destruction on failure (0.0 to 1.0)
materials	list	v92	❌	—	Material items required for this enchantment step (max 6 entries)

Material (Deeply Nested)

Represents a material requirement for an enchantment step. Identified by id within its parent MaterialItem.

Property	Type	Since	Required	Default	Description
id	int	v92	✅	—	Item ID of the required material
type	MaterialType	v92	✅	Item	Type of material (currently only Item supported)
amount	int	v92	✅	—	Quantity of this material required

XML Structure

MaterialEnchantData uses 3-level nesting with composite keys for nested entities:

<MaterialEnchantData>
  <ItemEnchant materialEnchantId="1" maxEnchantCount="9">
    <MaterialItem enchantStep="0" enchantProb="1.0" requiredMoney="0">
      <Material id="94101" type="Item" amount="4" />
      <Material id="94102" type="Item" amount="2" />
    </MaterialItem>
    <MaterialItem enchantStep="1" enchantProb="0.85" requiredMoney="1000" downStep="1" downProb="0.2">
      <Material id="94103" type="Item" amount="6" />
    </MaterialItem>
  </ItemEnchant>
  <ItemEnchant materialEnchantId="2" maxEnchantCount="6">
    <MaterialItem enchantStep="0" enchantProb="1.0" requiredMoney="0" />
  </ItemEnchant>
</MaterialEnchantData>

Composite Key Structure:

• ItemEnchant: Identified by materialEnchantId
• MaterialItem: Identified by (materialEnchantId, enchantStep)
• Material: Identified by (materialEnchantId, enchantStep, id)

Enum Reference

MaterialType

Defines the type of material required for enchantment.

Value	Description
Item	Standard item material (currently the only supported type)

Common Pitfalls

• Composite Key Targeting: When updating or upserting MaterialItem entries, you must specify enchantStep to target the correct nested element. Similarly, Material entries are identified by their id within a specific MaterialItem.

• Maximum Material Limit: Each MaterialItem can contain at most 6 Material entries. Exceeding this limit will cause validation errors against the XSD schema.

• Enchant Step Bounds: The enchantStep value must be less than maxEnchantCount. For example, if maxEnchantCount="9", valid enchantStep values are 0-8.

• Probability Ranges: All probability fields (enchantProb, failRevisionProb, downProb, damageProb) must be decimal values between 0.0 and 1.0 inclusive.

• Downgrade Validation: If specified, downStep must be less than or equal to the current enchantStep. You cannot downgrade more steps than the current enchantment level.

• Required Fields in Nested Structures: When creating MaterialItem entries, enchantStep, enchantProb, and requiredMoney are all required. When creating Material entries, id, type, and amount are all required.

• Upsert Replaces Entirely: The upsert operation replaces the entire ItemEnchant entry, including all nested MaterialItem and Material data. To preserve existing nested data while updating, use the update operation instead.