DungeonData

Version support

Version	Status
v92	Full
v90	-
v86	-

DungeonData files define dungeon instance configurations: entry conditions, event scripting, clear objectives, and recommendation data. Each continent has its own file using the naming convention DungeonData_{continentId}.xml. The continentId identifies both the file partition and the dungeon entity.

---

DSL support

Entity: dungeonDatas Operations: create, update, delete, upsert Key attribute: continentId File organization: AttributePartitioned by continentId

---

Quick recipes

Create (minimal)

spec:
  version: "1.0"
  schema: v92

dungeonDatas:
  create:
    - continentId: 9001
      name: "@dungeon:9001"
      exitContinentId: 7031
      enterLimitCount: 5
      coolTime: 3600

Create (with conditions and events)

spec:
  version: "1.0"
  schema: v92

dungeonDatas:
  create:
    - continentId: 9001
      name: "@dungeon:9001"
      exitContinentId: 7031
      startPos: [12345.5, 4336.25, 15047.75]
      exitPos: [63475.03, 38629.24, -8876.56]
      enterLimitCount: 5
      coolTimeApplyType: "party"
      coolTime: 3600
      conditions:
        - type: levelOver
          value: 65
        - type: minItemLevel
          value: 439
      clearConditions:
        - huntingZoneId: 990
          templateId: 3000
          killCount: 1
      eventGroups:
        - type: enterTerritory
          territoryId: "99001"
          tasks:
            - type: spawn
              next: "none"
              huntingZoneId: 990
              templateId: 100

Update

spec:
  version: "1.0"
  schema: v92

dungeonDatas:
  update:
    - continentId: 9001
      changes:
        enterLimitCount: 10
        coolTime: 7200

Delete

spec:
  version: "1.0"
  schema: v92

dungeonDatas:
  delete:
    - 9001

Upsert

spec:
  version: "1.0"
  schema: v92

dungeonDatas:
  upsert:
    - continentId: 9001
      name: "@dungeon:9001"
      exitContinentId: 7031
      enterLimitCount: 5
      coolTime: 3600

---

Properties reference

Root attributes

Attribute	Type	Since	Description
continentId	int	v92	Continent ID (partition key and entity identifier)
name	string	v92	Internal dungeon name or string reference
startPos	decimal[]	v92	Player spawn coordinates [x, y, z]
exitContinentId	int	v92	Continent ID for the dungeon exit
exitPos	decimal[]	v92	Exit teleport coordinates [x, y, z]
destroyWaitMin	int	v92	Minutes to wait before destroying instance
startDir	int	v92	Player facing direction on spawn (degrees)
exitDir	int	v92	Player facing direction on exit (degrees)
enterLimitCount	int	v92	Maximum entry count per cooldown period
coolTimeApplyType	string	v92	Cooldown scope: party or individual
newbieBonusOff	bool	v92	Disable newbie bonus for this dungeon
coolTime	int	v92	Re-entry cooldown in seconds
coolTimeForPartyMatching	int	v92	Cooldown override for party matching entries
needBattlePoint	int	v92	Required battle points to enter
matchingRoleId	int	v92	Party matching role requirement ID
startRandomPos	decimal[]	v92	Random spawn area coordinates [x, y, z]
allAoiWideBroadCaster	bool	v92	Enable wide-area broadcast for all entities
overlapConsoleEvent	bool	v92	Allow overlapping console events
summonPc	bool	v92	Allow player summoning inside dungeon
relatedDailyQuest	int	v92	Associated daily quest ID
coolTimeWithContinentId	string	v92	Shared cooldown continent ID group
scenarioUIOn	bool	v92	Enable scenario UI overlay
scenarioQuestId	int	v92	Associated scenario quest ID
eventDungeon	bool	v92	Mark as event (seasonal) dungeon
isPremiumDungeon	bool	v92	Mark as premium dungeon
addClusterMargin	int	v92	Additional cluster margin for instancing
ownershipGuaranteeSec	int	v92	Ownership guarantee period in seconds
lazyBroadcastPartyMemberInfo	bool	v92	Defer party member info broadcasting

Nested elements

Element	Type	Description	Reference
conditions	list	Entry requirement conditions	Conditions
clearConditions	list	Dungeon clear objectives	Conditions
restoreTargetQuests	list	Quests restored on entry	Conditions
retry	nested	Retry mechanism	Below
supportMatchingEffects	list	Support matching effects	Below
dpsDisplay	nested	DPS meter configuration	Below
visibleBGGroup	nested	Background visibility settings	Below
abnormalityWhenResurrection	nested	Resurrection abnormality	Below
randomStarts	list	Random spawn points	Below
recommend	nested	Recommendation UI data	Recommend
restrictPassivityType	nested	Passivity restrictions	Below
eventGroups	list	Event scripting groups	Event Groups

---

Inline block types

Retry

Property	Type	Since	Description
retryId	string	v92	Retry mechanism identifier

---

SupportMatchingEffect

Property	Type	Since	Description
type	SupportMatchingEffectType	v92	Effect type
value	string	v92	Effect value parameter
string	string	v92	String parameter

SupportMatchingEffectType

Value	Since
changeLevel	v92
abnormality	v92

---

DPSDisplay

Property	Type	Since	Description
updateFrequency	decimal	v92	Update interval in seconds
cutDigits	int	v92	Decimal places to truncate
digitStringId	int	v92	Digit format string ID

---

VisibleBGGroup

Property	Type	Since	Description
defaultGroupId	int	v92	Default background group ID
visibleBGs	list	v92	Background entries

VisibleBG

Property	Type	Since	Description
groupId	int	v92	Background group ID
name	string	v92	Background name reference

---

AbnormalityWhenResurrection

Property	Type	Since	Description
id	int	v92	Abnormality ID applied on resurrection
method	string	v92	Application method

---

RandomStart

Property	Type	Since	Description
pos	decimal[]	v92	Spawn coordinates [x, y, z]

---

RestrictPassivityType

Property	Type	Since	Description
typeIdList	int	v92	Restricted passivity type ID

---

XML structure

DungeonData_{continentId}.xml
└── Dungeon (root element = entity)
    ├── Scalar attributes (name, startPos, exitPos, coolTime, ...)
    ├── Condition [multiple]
    ├── ClearCondition [multiple]
    ├── RestoreTargetQuest [multiple]
    ├── Retry
    ├── SupportMatchingEffect [multiple]
    ├── DPSDisplay
    ├── VisibleBGGroup
    │   └── VisibleBG [multiple]
    ├── AbnormalityWhenResurrection
    ├── RandomStart [multiple]
    ├── Recommend
    │   ├── Category
    │   └── DropItem
    │       └── Class [multiple]
    ├── RestrictPassivityType
    └── EventGroup [multiple]
        └── Event [multiple]
            └── EventTaskGroup [multiple]
                └── EventTask [multiple]

---

Special types

Coordinate arrays

Position attributes (startPos, exitPos, startRandomPos) use decimal[] arrays in YAML that serialize to comma-separated strings in XML:

startPos: [12345.5, 4336.25, 15047.75]

Produces: startPos="12345.5,4336.25,15047.75"

NPC references

Several event task properties use composite NPC references. In YAML, use the NpcRef block:

targetNpcId:
  huntingZone: 990
  templateId: 1000

Produces: targetNpcId="990,1000"

---

Common pitfalls

• Root-as-entity: The <Dungeon> root element IS the entity. There is no collection wrapper. Each file contains exactly one dungeon.

• File partitioning: Files are partitioned by continentId. Creating a dungeon with continentId: 9001 targets DungeonData_9001.xml.

• Flat vs nested events: 94% of dungeons use the flat tasks shorthand. The mapper automatically wraps flat tasks into the Event > EventTaskGroup > EventTask hierarchy. See Event Groups for details.

• Element replacement: On upsert, nested collections (conditions, eventGroups, etc.) are fully replaced. You cannot patch individual entries.

• vlaue typo: The attribute vlaue (not value) is preserved verbatim from the source data. This is intentional.

• YAML reserved words: Some enum values (none, on, off, y) are YAML 1.1 reserved keywords. Quote them in YAML: next: "none", turn: "on".