ItemMixData

Overview

ItemMixData.xml defines item mixing recipes: success rates, progress timers, material requirements, and output items for the item combination system.

Version Support

Version	Status
v92	Full
v90	-
v86	-

This entity supports an inline workflow:

1. Inline item — define mix result items within an itemMixes.create operation using the item: block

---

DSL Support

Entity: itemMixes Operations: create, update, delete, upsert Inline blocks:

• item: — creates/updates ItemTemplate.xml with mix-specific defaults

---

Quick Recipes

Create with Inline Item Block (Recommended)

spec:
  version: "1.0"

itemMixes:
  create:
    - itemMixId: 1001
      # Inline item block - automatically creates ItemTemplate entry
      item:
        # Tier 3: Required user input (10 fields)
        name: "ultimate_potion"
        icon: "Icon_Items.potion_ultimate_Tex"
        level: 60
        rareGrade: 2  # 0=Common, 1=Uncommon, 2=Rare, 3=Superior
        category: "consumable"
        combatItemSubType: "potion"
        buyPrice: 500000
        sellPrice: 50000
        maxStack: 99
        maxDropUnit: 10

        # Tier 2: Optional overrides (defaults applied if omitted)
        combatItemType: "MIX_DISPOSAL"  # Default: "MIX_DISPOSAL"
        tradable: true  # Default: false
        warehouseStorable: true  # Default: true

      # Mix recipe properties
      successRate: 0.85
      progressTime: 5000
      progressSocial: 100
      materials:
        - itemId: 50001
          count: 3
        - itemId: 50002
          count: 1
      result:
        successItemId: 1001  # References the inline item created above
        successCount: 1

Creates mix recipe 1001 with an automatically generated ItemTemplate entry (ID 1001). The system applies 14 hard defaults (Tier 1) including essential item flags, plus 6 soft defaults (Tier 2) for common mix item attributes.

Create (Traditional Approach)

spec:
  version: "1.0"

itemMixes:
  create:
    - itemMixId: 1001
      successRate: 0.85
      progressTime: 5000
      progressSocial: 100
      materials:
        - itemId: 50001
          count: 3
        - itemId: 50002
          count: 1
      result:
        successItemId: 60001
        successCount: 1

Creates a new item mix recipe with 85% success rate that requires 3 units of item 50001 and 1 unit of item 50002 to produce 1 unit of item 60001.

Create with Failed Result

spec:
  version: "1.0"

itemMixes:
  create:
    - itemMixId: 1002
      successRate: 0.50
      progressTime: 10000
      progressSocial: 200
      questProgressCondition: "quest_complete_100"
      materials:
        - itemId: 50003
          count: 5
      result:
        successItemId: 60002
        successCount: 1
        failedItemId: 60003
        failedCount: 1

Creates a mix recipe with 50% success rate. On success, produces item 60002. On failure, produces item 60003 instead.

Update

spec:
  version: "1.0"

itemMixes:
  update:
    - itemMixId: 1001
      changes:
        successRate: 0.95
        progressTime: 3000

Updates the success rate and progress time for an existing mix recipe.

Update Materials

spec:
  version: "1.0"

itemMixes:
  update:
    - itemMixId: 1001
      changes:
        materials:
          - itemId: 50001
            count: 2
          - itemId: 50004
            count: 1

Replaces the entire materials list for the mix recipe.

Delete

spec:
  version: "1.0"

itemMixes:
  delete:
    - 1001
    - 1002

Removes item mix recipes with the specified IDs.

Upsert

spec:
  version: "1.0"

itemMixes:
  upsert:
    - itemMixId: 1003
      successRate: 0.75
      progressTime: 8000
      materials:
        - itemId: 50005
          count: 2
      result:
        successItemId: 60004
        successCount: 2

Creates the mix recipe if it doesn’t exist, or updates it completely if it does.

Upsert with Inline Item (Create or Update)

spec:
  version: "1.0"

itemMixes:
  upsert:
    - itemMixId: 1004
      item:
        name: "legendary_elixir"
        icon: "Icon_Items.elixir_legendary_Tex"
        level: 75
        rareGrade: 3
        category: "consumable"
        combatItemSubType: "elixir"
        buyPrice: 1000000
        sellPrice: 100000
        maxStack: 50
        maxDropUnit: 5
      successRate: 0.60
      progressTime: 12000
      materials:
        - itemId: 50006
          count: 5
        - itemId: 50007
          count: 3
      result:
        successItemId: 1004
        successCount: 1
        failedItemId: 50008
        failedCount: 1

Creates a new mix recipe and its ItemTemplate entry if ID 1004 doesn’t exist, or replaces both completely if they do exist.

---

Properties Reference

ItemMix (Root Entry)

Property	Type	Since	Required	Description
itemMixId	int	v92	Yes	Unique identifier for this mix recipe. Defaults as itemId if inline item: block is used without explicit itemId.
item	object	v92	No	Inline item block for creating mix result items automatically. See Item (Inline Block) below. Mutually exclusive with external item creation.
successRate	decimal	v92	Yes	Probability of successful mixing (0.0 to 1.0)
progressTime	int	v92	No	Time in milliseconds for the mixing animation
progressSocial	int	v92	No	Social point cost or requirement
questProgressCondition	string	v92	No	Quest condition string that must be satisfied

Materials (Nested List)

Defines the input materials required for the mix recipe.

Property	Type	Since	Required	Description
itemId	int	v92	Yes	Item template ID of the required material
count	int	v92	Yes	Quantity of this material required

Result (Nested)

Defines the output items produced by the mix recipe.

Property	Type	Since	Required	Description
successItemId	int	v92	Yes	Item template ID produced on successful mixing
successCount	int	v92	Yes	Quantity produced on successful mixing
failedItemId	int	v92	No	Item template ID produced on failed mixing
failedCount	int	v92	No	Quantity produced on failed mixing

Common (Global Settings)

Global settings that apply to all item mix operations. This element appears once in the XML file.

Property	Type	Since	Required	Description
progressTime	int	v92	Yes	Default progress time for mix operations
progressSocial	int	v92	Yes	Default social points for mix operations
successSocial	int	v92	Yes	Social points awarded on successful mixing
failedSocial	int	v92	Yes	Social points awarded on failed mixing

Item (Inline Block)

Defines a mix result item inline during create/upsert operations. When specified, automatically creates/updates the corresponding ItemTemplate entry with mix-specific defaults.

Three-Tier Default System:

• Tier 1 (Hard Defaults): 14 attributes with 100% constant values (auto-applied, non-overridable). Includes critical flags like boundType: None, artisanable: false, conversion: false, dismantlable: false.
• Tier 2 (Soft Defaults): 6 attributes with high-frequency defaults (auto-applied, user-overridable). See properties marked with “(Tier 2 default)” below.
• Tier 3 (Required Input): 10 attributes users must provide.

Tier 3 - Required User Input:

Property	Type	Since	Required	Description
name	string	v92	✅	Display name of the mix result item
icon	string	v92	✅	Icon asset path for the item
level	int	v92	✅	Required level to use this item
rareGrade	int	v92	✅	Rarity grade: 0=Common, 1=Uncommon, 2=Rare, 3=Superior
category	string	v92	✅	Item category (e.g., “consumable”, “material”)
combatItemSubType	string	v92	✅	Combat item subtype (e.g., “potion”, “elixir”)
buyPrice	int	v92	✅	Purchase price at NPC vendors
sellPrice	int	v92	✅	Sell price at NPC vendors
maxStack	int	v92	✅	Maximum stack size for this item
maxDropUnit	int	v92	✅	Maximum units dropped at once

Tier 2 - Optional Overrides (Defaults Applied if Omitted):

Property	Type	Since	Default	Description
itemId	int	v92	<itemMixId>	Item template ID (defaults to mixId if not specified)
combatItemType	string	v92	"MIX_DISPOSAL"	Combat item type. Default is appropriate for mix result items.
tradable	boolean	v92	false	Whether the mix result item can be traded. Override to true for tradable items.
warehouseStorable	boolean	v92	true	Whether storable in personal warehouse
guildWarehouseStorable	boolean	v92	false	Whether storable in guild warehouse
storeSellable	boolean	v92	true	Whether sellable in player stores
destroyable	boolean	v92	true	Whether the item can be destroyed by players

Tier 1 - Auto-Applied Hard Defaults (Non-Overridable):

14 attributes including boundType: None, artisanable: false, conversion: false, dismantlable: false, enchantEnable: false, itemUseCount: 1, itemDropEffect: "Default", skillCondition: "None", and other technical flags. These are applied automatically and cannot be overridden.

---

XML Structure

ItemMixData uses 3-level nesting:

ItemMixData
├── Common (progressTime, progressSocial, successSocial, failedSocial)
└── ItemMix (itemMixId, successRate, progressTime?, progressSocial?, questProgressCondition?)
    ├── Materials
    │   └── Material (itemId, count) [max unbounded]
    └── Result (successItemId, successCount, failedItemId?, failedCount?)

Notation:

• attr? = optional attribute
• [max unbounded] = unlimited occurrences

---

Common Pitfalls

• Inline Item Block Conflict (Error E410): You cannot specify both an item: block and expect the system to reference an external ItemTemplate with the same ID. When using the item: block, the system automatically creates/updates the ItemTemplate entry at the specified itemId (or itemMixId if itemId is omitted). Choose one approach:

  • Use item: block when creating a new mix with a new result item (recommended, reduces authoring effort)
  • Use external ItemTemplate when referencing an existing item that should not be modified
  • Error message: E410: Cannot specify both external item and 'item' block at itemMixes.create[0]

• Inline Item Required Fields: When using the item: block, all 10 Tier 3 fields are required: name, icon, level, rareGrade, category, combatItemSubType, buyPrice, sellPrice, maxStack, maxDropUnit. Omitting any will cause a YamlParseException.MissingField error.

• RareGrade Range: The rareGrade field in inline item blocks must be 0-3 (0=Common, 1=Uncommon, 2=Rare, 3=Superior). Other values will cause an InvalidEnum error.

• Three-Tier Default System: When using inline item blocks:

  • Tier 1 (14 fields): Automatically applied, non-overridable (e.g., boundType: None, artisanable: false)
  • Tier 2 (6 fields): Automatically applied with defaults, but user-overridable (e.g., combatItemType: "MIX_DISPOSAL", tradable: false)
  • Tier 3 (10 fields): User must provide all required values

  Total: 30 item attributes set with only 10 required user inputs (67% reduction in authoring effort).

• ItemId Defaults to ItemMixId: When using the item: block, if you don’t specify itemId, it automatically defaults to itemMixId. This is the recommended approach for most mix recipes. Only specify itemId explicitly if the item ID must differ from the mix ID.

• Success Rate Range: The successRate must be a decimal between 0.0 and 1.0 inclusive. Values like 85 (instead of 0.85) will be interpreted incorrectly.

• Material vs Result IDs: Don’t confuse material item IDs (inputs) with result item IDs (outputs). Materials are consumed; results are produced.

• Failed Result Requires Both Fields: If specifying a failed result, you should provide both failedItemId and failedCount. Specifying only one may cause unexpected behavior.

• Materials Replacement: When updating materials via the changes: block, the entire materials list is replaced. To add a single material, include all existing materials plus the new one.

• Common Element: The Common element in the XML defines global defaults but is not directly manipulated through YAML operations. These values are typically set once and rarely changed.

• Quest Progress Condition: The questProgressCondition string must match exactly with quest system identifiers. Typos or invalid quest IDs will cause the mix to always be unavailable.