# xml-data

> Parses and manages game data XML files for items, skills, NPCs, and custom features.
Use when: adding new items/skills/NPCs, modifying existing game data, creating custom features, debugging XML parsing errors

- Author: valeriybaranyshyn-pixel
- Repository: valeriybaranyshyn-pixel/Tales-of-Aden
- Version: 20260202145225
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/valeriybaranyshyn-pixel/Tales-of-Aden
- Web: https://mule.run/skillshub/@@valeriybaranyshyn-pixel/Tales-of-Aden~xml-data:20260202145225

---

---
name: xml-data
description: |
  Parses and manages game data XML files for items, skills, NPCs, and custom features.
  Use when: adding new items/skills/NPCs, modifying existing game data, creating custom features, debugging XML parsing errors
allowed-tools: Read, Edit, Write, Glob, Grep, Bash
---

# XML Data Skill

Handles all game data XML files in Tales of Aden. The L2J server uses two parallel XML parsing systems: `XMLDocument` (abstract class pattern) for items/skills and `IXmlReader` (interface with defaults) for custom features. Items, skills, and NPCs load at server startup via singleton datatables.

## Quick Start

### Adding a New Item

```xml
<!-- Files/game/data/xml/items/XXXX-XXXX.xml -->
<item id="90001" type="EtcItem" name="Custom Token">
    <set name="material" val="PAPER" />
    <set name="weight" val="0" />
    <set name="price" val="0" />
    <set name="is_stackable" val="true" />
    <set name="is_tradable" val="false" />
</item>
```

### Adding a New NPC

```xml
<!-- Files/game/data/xml/npcs/Custom/YourNpc.xml -->
<npc id="90001" name="Custom NPC" title="Event Manager">
    <set name="level" val="70"/>
    <set name="type" val="L2Npc"/>
    <set name="hp" val="2444"/>
    <set name="mp" val="1345"/>
    <ai type="DEFAULT" ssCount="0" ssRate="0" spsCount="0" 
        spsRate="0" aggro="0" canMove="true" seedable="false"/>
</npc>
```

## Key Concepts

| Concept | Class | Location |
|---------|-------|----------|
| Item parsing | `DocumentItem` | `gameserver/skills/DocumentItem.java` |
| Skill parsing | `DocumentSkill` | `gameserver/skills/DocumentSkill.java` |
| NPC loading | `NpcTable` | `gameserver/datatables/NpcTable.java` |
| Base parser | `XMLDocument` | `gameserver/xmlfactory/XMLDocument.java` |
| Modern parser | `IXmlReader` | `commons/data/xml/IXmlReader.java` |

## Common Patterns

### Using Level Tables

**When:** Skill/item values vary by level

```xml
<skill id="1" levels="37" name="Triple Slash">
    <table name="#power"> 431 458 486 516 547 579 612 ... </table>
    <set name="power" val="#power"/>
</skill>
```

### Drop Categories

```xml
<drops>
    <category id="0">  <!-- Adena always drops separately -->
        <drop itemid="57" min="30" max="42" chance="700000"/>
    </category>
    <category id="1">  <!-- Equipment group (one item chosen) -->
        <drop itemid="112" min="1" max="1" chance="79637"/>
    </category>
    <category id="-1"> <!-- Spoil drops -->
        <drop itemid="1786" min="1" max="1" chance="45293"/>
    </category>
</drops>
```

## File Organization

| Path | Content |
|------|---------|
| `data/xml/items/` | Items by ID range (0000-0099.xml) |
| `data/xml/skills/` | Skills by ID range |
| `data/xml/npcs/` | NPCs by ID range + subfolders |
| `data/xml/custom/` | Custom features (DailyRewards, Dolls, etc.) |

## See Also

- [patterns](references/patterns.md)
- [workflows](references/workflows.md)

## Related Skills

- See the **java** skill for datatable implementation patterns
- See the **skill-system** skill for skill mechanics
- See the **item-handlers** skill for item behavior
- See the **npc-scripting** skill for NPC AI integration
- See the **ai-system** skill for NPC behavior configuration