ICompensationData

Version Support

Version	Status
v92	Full
v90	-
v86	-

ICompensation_{zone}.xml defines instance compensation data: NPC drop rewards including item bags with loot tables, drop probabilities, and enchantment bonuses for dungeon NPCs.

DSL Support

Entity: iCompensations Operations: create, update, delete, upsert File Organization: Zone-partitioned (one file per huntingZoneId)

Quick Recipes

Create

spec:
  version: "1.0"

iCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 1001
      npcName: "DungeonBoss"
      itemBags:
        - id: 1
          bagName: "CommonLoot"
          probability: 0.5
          items:
            - templateId: 50001
              name: "Gold Coin"
              min: 10
              max: 50
              probability: 1.0

Creates a new compensation entry for NPC 1001 in hunting zone 9001 with a single item bag containing gold coins.

Create with Enchantment Drops

spec:
  version: "1.0"

iCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 1002
      npcName: "EliteBoss"
      itemBags:
        - id: 1
          bagName: "RareLoot"
          probability: 0.25
          wValue: 100.5
          backLock: "lock_condition"
          t: "special_type"
          items:
            - templateId: 60001
              name: "Enchanted Sword"
              min: 1
              max: 1
              probability: 0.1
              enchantMin: 1
              enchantMax: 5
              enchantProbability: 0.3
              masterpieceProbability: 0.05

Creates compensation with enchantment bonuses on dropped items.

Create with Auto-Distribution

spec:
  version: "1.0"

iCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 1005
      npcName: "AutoDistBoss"
      itemBags:
        - id: 1
          bagName: "AutoLoot"
          probability: 0.5
          distribution: auto
          items:
            - templateId: 50001
              name: "Token A"
            - templateId: 50002
              name: "Token B"
            - templateId: 50003
              name: "Token C"

When distribution: auto is set, item probabilities are calculated automatically as 1/n. The first item receives any remainder to ensure the sum equals exactly 1.0. In this example: 0.34, 0.33, 0.33.

Min and max default to 1 when omitted, reducing boilerplate for single-quantity drops.

Update

spec:
  version: "1.0"

iCompensations:
  update:
    - huntingZoneId: 9001
      npcTemplateId: 1001
      changes:
        npcName: "UpdatedBossName"
        itemBags:
          - id: 1
            bagName: "ImprovedLoot"
            probability: 0.75

Updates an existing compensation entry’s name and item bag configuration.

Delete

spec:
  version: "1.0"

iCompensations:
  delete:
    - huntingZoneId: 9001
      npcTemplateId: 1001

Removes the compensation entry for the specified NPC in the given hunting zone.

Upsert

spec:
  version: "1.0"

iCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 1003
      npcName: "NewBoss"
      itemBags:
        - id: 1
          bagName: "DefaultLoot"
          probability: 0.5
          items:
            - templateId: 50001
              name: "Basic Drop"
              min: 1
              max: 5
              probability: 1.0

Creates the compensation if it doesn’t exist, or replaces it completely if it does.

Managing Bags and Items

The DSL uses replace-all semantics for nested structures. There are no granular operations to add or remove individual bags or items. Instead, use the update operation with a complete bag/item list.

Adding a new bag to an existing compensation:

spec:
  version: "1.0"

iCompensations:
  update:
    - huntingZoneId: 9001
      npcTemplateId: 1001
      changes:
        itemBags:
          # Include existing bag you want to keep
          - id: 1
            bagName: "OriginalLoot"
            probability: 0.5
            items:
              - templateId: 50001
                name: "Gold Coin"
                min: 10
                max: 50
                probability: 1.0
          # Add the new bag
          - id: 2
            bagName: "NewLoot"
            probability: 0.3
            items:
              - templateId: 50002
                name: "Silver Coin"
                min: 5
                max: 20
                probability: 1.0

Removing a bag: Simply omit it from the itemBags list in your update.

Adding an item to an existing bag: Include all existing items plus the new one in the bag’s items list.

Removing an item: Omit it from the bag’s items list.

Properties Reference

Compensation (Root Entry)

Property	Type	Since	Required	Description
`huntingZoneId`	`int`	v92	Yes	Hunting zone ID (file partition key)
`npcTemplateId`	`int`	v92	Yes	Unique NPC template ID (primary key)
`npcName`	`string`	v92	Yes	Internal NPC name (used as lookup key)
`itemBags`	`list`	v92	No	List of item bag configurations

ItemBag (Nested)

Property	Type	Since	Required	Description
`id`	`int`	v92	Yes	Unique item bag identifier within this compensation
`bagName`	`string`	v92	Yes	Display name for the item bag
`probability`	`decimal`	v92	Yes	Drop probability (0.0 to 1.0)
`wValue`	`decimal`	v92	No	Weight value for drop calculation
`backLock`	`string`	v92	No	Back lock condition string
`t`	`string`	v92	No	Type modifier string
`distribution`	`string`	v92	No	Distribution mode: `auto` (calculate probabilities) or `manual` (default, require explicit probabilities)
`items`	`list`	v92	No	List of items in this bag

Item (Nested)

Property	Type	Since	Required	Description
`templateId`	`int`	v92	Yes	Item template ID (references ItemTemplate)
`name`	`string`	v92	Yes	Display name for the item
`min`	`int`	v92	No	Minimum drop quantity. Defaults to `1`
`max`	`int`	v92	No	Maximum drop quantity. Defaults to `1`
`probability`	`decimal`	v92	No	Individual item drop probability. Required unless parent bag has `distribution: auto`
`enchantMin`	`int`	v92	No	Minimum enchantment level when dropped
`enchantMax`	`int`	v92	No	Maximum enchantment level when dropped
`enchantProbability`	`decimal`	v92	No	Probability of item being enchanted
`masterpieceProbability`	`decimal`	v92	No	Probability of masterpiece variant

XML Structure

ICompensationData uses 4-level nesting:

ICompensationData (huntingZoneId)
└── Compensation (npcName, npcTemplateId) [max 3]
    └── ItemBag (id, bagName, probability, wValue?, backLock?, t?)
        └── Item (templateId, name, min, max, probability, enchantMin?, enchantMax?, enchantProbability?, masterpieceProbability?)

Notation:

attr? = optional attribute
[max N] = maximum occurrence count

Common Pitfalls

Composite Key: ICompensation uses a composite key of huntingZoneId + npcTemplateId. Both must be specified for update/delete operations.
Zone-Partitioned Files: Files are organized by hunting zone. The huntingZoneId determines which file (ICompensation_{zone}.xml) the entry belongs to.
Probability Range: All probability values must be decimals between 0.0 and 1.0. Values like 50 (instead of 0.5) will be interpreted incorrectly.
NpcName as Lookup Key: During create operations, npcName is used as the initial lookup key before npcTemplateId is assigned. Ensure it’s unique within the compensation.
Item Bag ID Uniqueness: The id field within itemBags must be unique within each compensation entry.
Enchantment Dependencies: If specifying enchant properties, enchantMin should be less than or equal to enchantMax. The enchantProbability determines how often the enchant range applies.
Replace-All for Nested Structures: The DSL does not support granular add/remove for bags or items. When updating itemBags, the entire collection is replaced. Include all bags and items you want to preserve in your update operation.
Default Min/Max: When min or max is omitted from items, they default to 1. Only specify when different values are needed.
Auto-Distribution: Use distribution: auto on ItemBag to auto-calculate item probabilities. Items without explicit probability receive equal share (1/n). Items with explicit probability keep their value, remaining probability is distributed to others.