Environment Compensation

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) File Creation: upsert and create automatically scaffold ECompensation_{zone}.xml for zones without an existing file

---

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
          equalProbability: true
          items:
            - templateId: 50001
              name: "Token A"
            - templateId: 50002
              name: "Token B"
            - templateId: 50003
              name: "Token C"

When equalProbability: true 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.

Upsert into a New Zone

spec:
  version: "1.0"

eCompensations:
  upsert:
    - huntingZoneId: 83
      npcTemplateId: 4001
      npcName: "BleakrockGuardian"
      itemBags:
        - id: 1
          bagName: "GuardianLoot"
          probability: 0.6
          items:
            - templateId: 70001
              name: "Guardian Token"
              min: 1
              max: 5
              probability: 1.0

When the zone file ECompensation_83.xml does not exist, the DSL automatically creates it with the correct root element structure. No manual file creation required.

Updating a Nameless Vanilla GoldBag

Some vanilla XML files contain <GoldBag> elements without a bagName attribute. Use bagName: "" (empty string) to target these entries:

spec:
  version: "1.0"

eCompensations:
  upsert:
    - huntingZoneId: 10
      npcTemplateId: 1001
      goldBags:
        - bagName: ""
          probability: 0.8
          min: 5000
          max: 55000

The empty string matches any GoldBag element that lacks a bagName attribute in the vanilla XML. To replace a nameless GoldBag with a named one, use update with a complete goldBags list (replace-all semantics):

spec:
  version: "1.0"

eCompensations:
  update:
    - huntingZoneId: 10
      npcTemplateId: 1001
      changes:
        goldBags:
          - bagName: "Gold"
            probability: 0.8
            min: 5000
            max: 55000

This replaces all existing GoldBags (including nameless ones) with the specified list.

Create with GoldBag

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: 2006
      npcName: "GoldBoss"
      goldBags:
        - bagName: "Gold"
          probability: 0.7
          min: 100
          max: 500

Creates a compensation entry with a gold drop bag. GoldBag uses bagName as its key for upsert operations.

Create with RewardBox

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 487
      npcTemplateId: 100
      npcName: "FieldBoss"
      rewardBoxes:
        - id: 1
          boxName: "grade1 reward"
          grade: 1
          dropItemToPC: true
          partyDamageMin: 0
          partyDamageMax: 0.003
          items:
            - templateId: 209089
              name: "Grade 1 Box"
              min: 1
              max: 1
              probability: 1
        - id: 2
          boxName: "grade2 reward"
          grade: 2
          dropItemToPC: true
          partyDamageMin: 0.003
          partyDamageMax: 0.05
          items:
            - templateId: 209090
              name: "Grade 2 Box"
              min: 1
              max: 1
              probability: 1

RewardBox uses grade-tiered tiers with partyDamageMin/partyDamageMax ranges. Items use integer probabilities.

Create with JackpotRewardBox

spec:
  version: "1.0"

eCompensations:
  create:
    - huntingZoneId: 487
      npcTemplateId: 100
      npcName: "FieldBoss"
      jackpotRewardBoxes:
        - id: 1
          boxName: "Jackpot Drop"
          gradeMin: 2
          gradeMax: 3
          dropItemToPC: true
          items:
            - templateId: 209087
              name: "Treasure Box"
              min: 1
              max: 1
              probability: 1

JackpotRewardBox awards rare loot to players within the gradeMin–gradeMax damage contribution range.

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.

Replace-All Semantics

When you specify any bag list (itemBags, goldBags, rewardBoxes, jackpotRewardBoxes) in an update, the entire collection for that bag type is replaced. Any entries not included will be removed. Always include all entries you want to preserve.

---

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
goldBags	list	v92	No	List of gold bag configurations
rewardBoxes	list	v92	No	List of reward box configurations
jackpotRewardBoxes	list	v92	No	List of jackpot reward box 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
equalProbability	bool	v92	No	When true, auto-distributes probability equally among items without explicit probability. Truncated to 2 decimal places.
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 equalProbability: true
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)

Gold bag configuration for gold currency drops.

Property	Type	Since	Required	Description
id	int	v92	No	Unique gold bag identifier
bagName	string	v92	Yes	Display name for the gold bag (used as key). Use "" to target nameless vanilla entries
probability	decimal	v92	Yes	Drop probability (0.0 to 1.0)
min	int	v92	Yes	Minimum gold amount
max	decimal	v92	Yes	Maximum gold amount
wValue	decimal	v92	No	Weight value for drop calculation
backLock	string	v92	No	Back lock condition
t	string	v92	No	Type modifier string
lockProbAndAmount	boolean	v92	No	Lock probability and amount values
rewardRank	int	v92	No	Reward rank for prioritization

RewardBox (Nested)

Reward box configuration for grade-based party rewards with damage gating.

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 contribution threshold
partyDamageMax	decimal	v92	Yes	Maximum party damage contribution threshold
items	list	v92	No	List of reward items in this box

RewardBox Item (Nested in RewardBox)

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	int	v92	Yes	Drop probability (integer)

JackpotRewardBox (Nested)

Jackpot reward box for rare drops with grade range filtering.

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
items	list	v92	No	List of jackpot items in this box

JackpotRewardBox Item (Nested in JackpotRewardBox)

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	int	v92	Yes	Drop probability (integer)

---

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). Upsert automatically creates the zone file if it doesn’t exist — no need to pre-create ECompensation_{zone}.xml for new zones.

• Multiple Bag Types: ECompensation supports four distinct bag types (ItemBag, GoldBag, RewardBox, JackpotRewardBox), all fully supported via YAML. Each bag type uses a different key: ItemBag by id, GoldBag by bagName, RewardBox by id, JackpotRewardBox by id.

• 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, goldBags, rewardBoxes, or jackpotRewardBoxes, the entire collection for that bag type is replaced. Include all entries 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.

• Probability Types: ItemBag items use decimal probability (0.0–1.0). RewardBox and JackpotRewardBox items use int probability. Do not mix the two formats.

• GoldBag Key: GoldBag uses bagName as its upsert key, not id. Two gold bags with the same bagName are treated as the same entry.

• Nameless Vanilla GoldBags: Some vanilla XML files contain <GoldBag> elements without a bagName attribute. Use bagName: "" (empty string) to target these entries. See the “Updating a Nameless Vanilla GoldBag” recipe above for examples.

• Auto-Distribution: Use equalProbability: true 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. Auto-distribution is not available for RewardBox or JackpotRewardBox items.