Added Dungeon Datapack documentation

datapack-documentation/Dungeons.md

@@ -0,0 +1,99 @@
+### 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:** `datapack-documentation/example/datapack/ex/data/dungeons/caverns/crystal_mine.json`
+- **Room Examples:** \* `datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/crystal_hallway.json`
+  - `datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/core_vault.json`
+- **Hostile Example:** `datapack-documentation/example/datapack/ex/data/enemies/hostiles/caverns/crystal_guardian.json`

datapack-documentation/example/datapack/ex/data/dungeons/caverns/crystal_mine.json

@@ -0,0 +1,17 @@
+{
+  "dungeon": {
+    "id": "original:caverns/crystal_mine",
+    "displayName": "dungeons.original.caverns.crystal_mine.name",
+    "description": "dungeons.original.caverns.crystal_mine.desc",
+    "meta": {
+      "energyCost": 15,
+      "repeatable": true,
+      "raid": false
+    },
+    "rooms": [
+      { "id": "original:caverns/crystal_hallway" },
+      { "id": "original:caverns/crystal_hallway" },
+      { "id": "original:caverns/core_vault" }
+    ]
+  }
+}

datapack-documentation/example/datapack/ex/data/enemies/hostiles/caverns/crystal_guardian.json

@@ -0,0 +1,36 @@
+{
+  "hostile": {
+    "id": "original:caverns/crystal_guardian",
+    "displayName": "enemies.original.caverns.crystal_guardian.name",
+    "stats": {
+      "health": 120,
+      "defense": 0.25,
+      "damage": 18.0,
+      "critical,chance": 0.15,
+      "attack.rate": 2.5
+    },
+    "loot": [
+      {
+        "id": "original:ore_coal",
+        "chance": 0.8,
+        "count": { "min": 2, "max": 5 }
+      },
+      {
+        "id": "original:ore_copper",
+        "chance": 0.6,
+        "count": { "min": 1, "max": 3 }
+      },
+      {
+        "id": "original:crystal_flux_core",
+        "chance": 0.15,
+        "count": 1
+      },
+      {
+        "id": "original:crystal_dimentional",
+        "chance": 0.02,
+        "count": 1
+      }
+    ],
+    "meta": {}
+  }
+}

datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/core_vault.json

@@ -0,0 +1,28 @@
+{
+  "room": {
+    "id": "original:caverns/core_vault",
+    "displayName": "rooms.original.caverns.core_vault.name",
+    "description": "rooms.original.caverns.core_vault.desc",
+    "hostiles": [
+      "original:caverns/crystal_guardian",
+      "original:pirate/boarding_drone"
+    ],
+    "gainXp": 120,
+    "credits": 850,
+    "loot": [
+      {
+        "id": "original:crystal_flux_core",
+        "chance": 0.5,
+        "count": 1
+      },
+      {
+        "id": "original:ore_copper",
+        "chance": 1.0,
+        "count": { "min": 5, "max": 10 }
+      }
+    ],
+    "meta": {
+      "isBossRoom": true
+    }
+  }
+}

datapack-documentation/example/datapack/ex/data/enemies/rooms/caverns/crystal_hallway.json

@@ -0,0 +1,23 @@
+{
+  "room": {
+    "id": "original:caverns/crystal_hallway",
+    "displayName": "rooms.original.caverns.crystal_hallway.name",
+    "description": "rooms.original.caverns.crystal_hallway.desc",
+    "hostiles": [
+      "original:pirate/boarding_drone",
+      "original:pirate/boarding_drone"
+    ],
+    "gainXp": 45,
+    "credits": 250,
+    "loot": [
+      {
+        "id": "original:ore_coal",
+        "chance": 1.0,
+        "count": { "min": 3, "max": 6 }
+      }
+    ],
+    "meta": {
+      "isBossRoom": false
+    }
+  }
+}