ID List Expansion

ID List Expansion allows you to generate multiple entries from a single YAML entry by providing an array of integer IDs instead of a single value.

Basic Syntax

Instead of repeating entries with identical properties:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 3001
      $extends: commonLoot
    - huntingZoneId: 9001
      npcTemplateId: 3002
      $extends: commonLoot
    - huntingZoneId: 9001
      npcTemplateId: 3003
      $extends: commonLoot

Use an array for the ID field:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002, 3003]
      $extends: commonLoot

This expands into three separate entries, each with identical properties but different npcTemplateId values.

How It Works

Expansion happens after $extends resolution
Each entity section has a registered ID field (e.g., npcTemplateId for cCompensations, id for items). Only that field is eligible for expansion at the top level.
Each array element produces one complete entry
All other fields are copied to each expanded entry
Non-ID fields with integer arrays (e.g., linkPassivityId: [9000000, 9000001]) pass through as list values — they are never expanded into multiple entries

Supported Operations

ID List Expansion works with all CRUD operations:

cCompensations:
  create:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002]
      # ...creates 2 entries

  update:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002]
      changes:
        # ...updates 2 entries

  delete:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002]
      # ...deletes 2 entries

  upsert:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002]
      # ...upserts 2 entries

Combining with Definitions

ID List Expansion works seamlessly with $extends. Definitions are resolved first, then arrays are expanded:

definitions:
  infusionLoot:
    classBranches:
      - className: "warrior"
        itemBags:
          - probability: 0.1
            items:
              - templateId: 990000
                min: 1
                max: 1

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002, 3003, 3010, 3015]
      $extends: infusionLoot

Result: 5 CCompensation entries, each with the full infusionLoot definition merged in.

Detection Rules

Expansion behavior is context-aware based on nesting level:

Top-Level Entries

At the top level of operations (create/update/delete/upsert), only the section’s registered ID field with an integer array value triggers expansion. Other fields — even those containing integer arrays — are not expanded.

Value Type	Expands?	Reason
`npcTemplateId: 3001`	No	Scalar value
`npcTemplateId: [3001, 3002]`	Yes	Registered ID field with integer array
`linkPassivityId: [9000000, 9000001]`	No	Not the section’s ID field
`tags: ["elite", "boss"]`	No	String array, not ID field
`items: [{id: 1}, {id: 2}]`	No	Object array

Each section’s ID field is determined by the schema definition. The registered ID fields are:

Section	ID Field
`items`	`id`
`equipment`	`equipmentId`
`itemStrings`	`id`
`enchants`	`enchantId`
`enchantDatas`	`id`
`enchantPassivityCategories`	`enchantPassivityCategoryId`
`evolutions`	`targetTemplateId`
`materialEnchants`	`materialEnchantId`
`itemProduceRecipes`	`id`
`itemMixes`	`itemMixId`
`rawStoneItems`	`rawStoneItemId`
`exchanges`	`itemId`
`iCompensations`	`npcTemplateId`
`eCompensations`	`npcTemplateId`
`fCompensations`	`compensationId`
`cCompensations`	`npcTemplateId`
`passivities`	`id`
`passivityIconData`	`passivityId`
`passivityStrings`	`id`

Nested Sequences

Within nested sequences of mappings (e.g., classBranches, itemBags), any scalar array triggers expansion:

Value Type	Expands?
`className: "warrior"`	No (scalar)
`className: ["warrior", "lancer"]`	Yes (string array)
`priority: [1, 2, 3]`	Yes (integer array)

This context-aware approach maintains backward compatibility at the top level while enabling flexible expansion in nested structures.

Non-ID Integer Arrays

Integer arrays in non-ID fields are preserved as list values and never trigger expansion. This allows fields like linkPassivityId to accept inline list syntax transparently:

items:
  upsert:
    - id: 990000
      linkPassivityId: [9000000, 9000001]  # Preserved as a list, not expanded
      maxStack: 1

This produces a single item entry with linkPassivityId containing both values.

Empty Arrays

An empty array produces no entries:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: []  # Produces 0 entries

Nested Structure Expansion

Nested sequences containing mappings can use scalar arrays to generate multiple entries within the parent structure.

Class Branches Example

Instead of duplicating class branches with shared loot:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 3001
      classBranches:
        - className: "warrior"
          itemBags:
            - probability: 0.5
              items:
                - templateId: 50001
                  min: 1
                  max: 1
        - className: "lancer"
          itemBags:
            - probability: 0.5
              items:
                - templateId: 50001
                  min: 1
                  max: 1
        - className: "berserker"
          itemBags:
            - probability: 0.5
              items:
                - templateId: 50001
                  min: 1
                  max: 1

Use an array for className:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 3001
      classBranches:
        - className: ["warrior", "lancer", "berserker"]
          itemBags:
            - probability: 0.5
              items:
                - templateId: 50001
                  min: 1
                  max: 1

This expands into three classBranches entries, each with identical itemBags but different className values.

Combined with Top-Level Expansion

Top-level and nested expansion work together:

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002]  # Expands to 2 top-level entries
      classBranches:
        - className: ["warrior", "lancer"]  # Each entry gets 2 class branches
          $extends: sharedLoot

Result: 2 top-level entries × 2 class branches = 4 total class branch instances.

With Definitions

Nested expansion combines with $extends for maximum reuse:

definitions:
  sharedLoot:
    itemBags:
      - probability: 0.5
        items:
          - templateId: 50001
            min: 1
            max: 1

cCompensations:
  upsert:
    - huntingZoneId: 9001
      npcTemplateId: 3001
      classBranches:
        - className: ["warrior", "lancer"]
          $extends: sharedLoot

Use Cases

Bulk Loot Assignment

Apply the same loot table to multiple NPCs in a hunting zone:

definitions:
  zoneLoot:
    classBranches:
      - className: "warrior"
        itemBags:
          - probability: 0.05
            items:
              - templateId: 180001
                min: 1
                max: 1

cCompensations:
  upsert:
    # Regular mobs
    - huntingZoneId: 9001
      npcTemplateId: [3001, 3002, 3003, 3004, 3005, 3010, 3011, 3012]
      $extends: zoneLoot

    # BAMs with higher drop rate
    - huntingZoneId: 9001
      npcTemplateId: [3100, 3101, 3102]
      $extends: zoneLootBAM

Multi-Zone Configuration

iCompensations:
  upsert:
    - huntingZoneId: [9001, 9002, 9003]
      npcTemplateId: 1000
      itemBags:
        - # common loot for boss across zones

Limitations

Top-level expansion applies only to the section’s registered ID field — other integer arrays pass through as list values
Nested sequences: any scalar array (integer or string) triggers expansion
Expansion happens per-operation (create, update, delete, upsert)
Object arrays are never expanded (only scalar arrays)
Sections without a registered schema (e.g., manually authored entities) do not participate in ID list expansion