### Dungeon Datapack Documentation

### Dungeon Configuration

**Path:** `datapacks/[namespace]/dungeons/[path]/dungeon.json`

```json
{
  "dungeon": {
    "id": "Unique system ID (namespace:path/name)",
    "displayName": "Translation key for the dungeon name",
    "description": "Translation key for the atmospheric location description",
    "meta": {
      "energyCost": "Amount of energy required for entry",
      "repeatable": "Boolean (true/false): whether the dungeon can be replayed",
      "raid": "Whether this dungeon is designed for a group of players"
    },
    "rooms": [
      { "id": "Reference to a specific Room ID from the available rooms pool" }
    ]
  }
}
```

### Room Configuration

**Path:** `datapacks/[namespace]/rooms/[path]/room.json`

```json
{
  "room": {
    "id": "Unique system ID (namespace:path/name)",
    "displayName": "Translation key for the UI display name",
    "description": "Translation key for the atmospheric flavor text shown upon entry",
    "hostiles": [
      "Array of Enemy IDs to spawn in this room (e.g., ['id1', 'id2'])"
    ],
    "gainXp": "Fixed amount of experience awarded for clearing the room",
    "credits": "Fixed amount of currency guaranteed to drop",
    "loot": [],
    "meta": {
      "isBossRoom": "Boolean: whether to trigger boss-fight logic"
    }
  }
}
```

### Hostile Configuration

Path: datapacks/[namespace]/enemies/hostiles/[path]/enemy.json

```json
{
  "hostile": {
    "id": "Unique system ID (namespace:path/name)",
    "displayName": "Translation key for the enemy's name",
    "stats": {
      "health": "Numerical HP value",
      "defense": "Numerical defense value",
      "damage": "Numerical base damage value",
      "critical.chance": "Critical hit chance",
      "attack.rate": "Attack speed (seconds)"
    },
    "loot": [],
    "meta": {}
  }
}
```

### Loot System Specification

This structure is used to define item drops within **Rooms** (on completion) or from **Hostiles** (on death).

```json
{
  "loot": [
    {
      "id": "Unique Item ID (namespace:items/item_name)",
      "chance": "Probability of dropping, from 0.0 (0%) to 1.0 (100%)",
      "count": {
        "min": "Minimum number of items to drop if the chance succeeds",
        "max": "Maximum number of items to drop if the chance succeeds"
      }
    },
    {
      "id": "Unique Item ID",
      "chance": "Probability of dropping",
      "count": "Fixed integer value if the item amount is always constant"
    }
  ]
}
```

### Project Examples Reference

- **Dungeon Example:** [crystal_mine](datapack-documentation/example/datapack/ex/data/dungeons/caverns/crystal_mine.json)
- **Room Examples:** \* [crystal_hallway](datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/crystal_hallway.json)
  - [core_vault](datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/core_vault.json)
- **Hostile Example:** [crystal_guardian](datapack-documentation/example/datapack/ex/data/enemies/hostiles/caverns/crystal_guardian.json)