API/datapack-documentation/Dungeons.md

Dungeon Datapack Documentation

Dungeon Configuration

Path: datapacks/[namespace]/dungeons/[path]/dungeon.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

{
  "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

{
  "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).

{
  "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
• Room Examples: * crystal_hallway
• Hostile Example: crystal_guardian