ECompensationData

Version Support

Version	Status
v92	Full
v90	-
v86	-

ECompensation_{zone}.xml defines elite compensation data: boss NPC drop rewards including item bags, gold bags, reward boxes, and jackpot reward boxes for elite monster encounters.

DSL Support

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

Quick Recipes

Create with ItemBag

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 2001
      npcName: "EliteBoss"
      itemBags:
        - id: 1
          bagName: "EliteLoot"
          probability: 0.5
          mustDrop: true
          rewardRank: 1
          items:
            - templateId: 50001
              name: "Elite Token"
              min: 1
              max: 3
              probability: 1.0
              isPublic: true

Creates an elite compensation entry with an item bag that always drops.

Create with Full Configuration

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 2002
      npcName: "WorldBoss"
      content: "world_boss_content"
      itemDropType: "elite"
      sender: "system"
      title: "World Boss Reward"
      itemBags:
        - id: 1
          bagName: "MainLoot"
          probability: 0.75
          wValue: "100"
          backLock: "lock_elite"
          bagLock: "bag_lock_condition"
          t: "elite_type"
          itemBagType: "elite"
          lockProbAndAmount: false
          mustDrop: false
          rewardRank: 2
          items:
            - templateId: 60001
              name: "Legendary Weapon"
              min: 1
              max: 1
              probability: 0.05
              enchantMin: 3
              enchantMax: 9
              enchantProbability: 0.5
              masterpieceProbability: 0.1
              isPublic: true

Creates a world boss compensation with all optional properties.

Create with Auto-Distribution

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 2005
      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"

eCompensations:
  update:
    - huntingZoneId: 9001
      npcTemplateId: 2001
      changes:
        title: "Updated Elite Reward"
        itemBags:
          - id: 1
            probability: 0.8

Updates an existing elite compensation entry.

Delete

spec:
  version: "1.0"

eCompensations:
  delete:
    - huntingZoneId: 9001
      npcTemplateId: 2001

Removes the elite compensation entry for the specified NPC.

Upsert

spec:
  version: "1.0"

eCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 2003
      npcName: "RaidBoss"
      itemBags:
        - id: 1
          bagName: "RaidLoot"
          probability: 1.0
          items:
            - templateId: 50001
              name: "Raid Token"
              min: 5
              max: 10
              probability: 1.0

Creates or replaces the elite compensation entry.

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"

eCompensations:
  update:
    - huntingZoneId: 9001
      npcTemplateId: 2001
      changes:
        itemBags:
          # Include existing bag you want to keep
          - id: 1
            bagName: "OriginalLoot"
            probability: 0.5
            items:
              - templateId: 50001
                name: "Elite Token"
                min: 1
                max: 3
                probability: 1.0
          # Add the new bag
          - id: 2
            bagName: "NewLoot"
            probability: 0.3
            items:
              - templateId: 50002
                name: "Bonus Token"
                min: 1
                max: 2
                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
`content`	`string`	v92	No	Content identifier string
`itemDropType`	`string`	v92	No	Type of item drop behavior
`sender`	`string`	v92	No	Reward sender identifier
`title`	`string`	v92	No	Reward title for display
`itemBags`	`list`	v92	No	List of item bag configurations

ItemBag (Nested)

Property	Type	Since	Required	Description
`id`	`int`	v92	Yes	Unique item bag identifier
`bagName`	`string`	v92	Yes	Display name for the item bag
`probability`	`decimal`	v92	Yes	Drop probability (0.0 to 1.0)
`wValue`	`string`	v92	No	Weight value for drop calculation
`backLock`	`string`	v92	No	Back lock condition string
`bagLock`	`string`	v92	No	Bag lock condition string
`t`	`string`	v92	No	Type modifier string
`itemBagType`	`string`	v92	No	Type classification for the bag
`lockProbAndAmount`	`boolean`	v92	No	Lock probability and amount values
`mustDrop`	`boolean`	v92	No	Force drop regardless of probability
`rewardRank`	`int`	v92	No	Reward rank for prioritization
`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 in ItemBag)

Property	Type	Since	Required	Description
`templateId`	`int`	v92	Yes	Item template ID
`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
`enchantMax`	`int`	v92	No	Maximum enchantment level
`enchantProbability`	`decimal`	v92	No	Probability of enchantment
`masterpieceProbability`	`decimal`	v92	No	Probability of masterpiece
`isPublic`	`boolean`	v92	No	Whether drop is announced publicly

GoldBag (Nested - XML Only)

Gold bag configuration for gold drops. Note: Currently only supported via direct XML editing.

Property	Type	Since	Required	Description
`id`	`int`	v92	No	Unique gold bag identifier
`bagName`	`string`	v92	Yes	Display name for the gold bag
`probability`	`decimal`	v92	Yes	Drop probability
`min`	`int`	v92	Yes	Minimum gold amount
`max`	`decimal`	v92	Yes	Maximum gold amount
`wValue`	`decimal`	v92	No	Weight value
`backLock`	`string`	v92	No	Back lock condition
`t`	`string`	v92	No	Type modifier
`lockProbAndAmount`	`boolean`	v92	No	Lock probability and amount
`rewardRank`	`int`	v92	No	Reward rank

RewardBox (Nested - XML Only)

Reward box configuration for grade-based rewards. Note: Currently only supported via direct XML editing.

Property	Type	Since	Required	Description
`id`	`int`	v92	Yes	Unique reward box identifier
`boxName`	`string`	v92	Yes	Display name for the box
`grade`	`int`	v92	Yes	Reward grade level
`dropItemToPC`	`boolean`	v92	Yes	Drop directly to player inventory
`partyDamageMin`	`decimal`	v92	Yes	Minimum party damage requirement
`partyDamageMax`	`decimal`	v92	Yes	Maximum party damage threshold

JackpotRewardBox (Nested - XML Only)

Jackpot reward box for rare drops. Note: Currently only supported via direct XML editing.

Property	Type	Since	Required	Description
`id`	`int`	v92	Yes	Unique jackpot box identifier
`boxName`	`string`	v92	Yes	Display name for the box
`gradeMin`	`int`	v92	Yes	Minimum grade level
`gradeMax`	`int`	v92	Yes	Maximum grade level
`dropItemToPC`	`boolean`	v92	Yes	Drop directly to player inventory

XML Structure

ECompensationData uses 4-level nesting with multiple bag types:

ECompensationData (huntingZoneId)
└── Compensation (npcName, npcTemplateId, content?, itemDropType?, sender?, title?)
    ├── GoldBag (id?, bagName, probability, min, max, wValue?, backLock?, t?, lockProbAndAmount?, rewardRank?)
    ├── ItemBag (id, bagName, probability, wValue?, backLock?, bagLock?, t?, itemBagType?, lockProbAndAmount?, mustDrop?, rewardRank?)
    │   └── Item (templateId, name, min, max, probability, enchantMin?, enchantMax?, enchantProbability?, masterpieceProbability?, isPublic?)
    ├── RewardBox (id, boxName, grade, dropItemToPC, partyDamageMin, partyDamageMax) [max 3]
    │   └── Item (templateId, name, min, max, probability)
    └── JackpotRewardBox (id, boxName, gradeMin, gradeMax, dropItemToPC)
        └── Item (templateId, name, min, max, probability)

Notation:

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

Common Pitfalls

Composite Key: ECompensation uses huntingZoneId + npcTemplateId as composite key. Both required for update/delete.
Zone-Partitioned Files: Files organized by hunting zone (ECompensation_{zone}.xml).
Multiple Bag Types: ECompensation supports four distinct bag types (GoldBag, ItemBag, RewardBox, JackpotRewardBox). Currently only ItemBag is fully supported via YAML.
WValue Type Difference: In ECompensation, wValue on ItemBag is a string type, not decimal like in ICompensation.
MustDrop Flag: When mustDrop: true, the bag drops regardless of the probability value.
RewardBox Party Damage: The partyDamageMin and partyDamageMax define the contribution range for party members to receive rewards.
IsPublic Announcement: Setting isPublic: true on items causes server-wide announcements when dropped.
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.