Dungeons Reference

A dungeon is a structured series of rooms that a player enters and progresses through in order. Dungeons reference rooms by ID — they do not define enemies or loot directly.

Files live in: <your_pack_id>/data/dungeons/<group_folder>/<dungeon_name>.json

File Structure

{
  "dungeon": {
    "id": "...",
    "displayName": "...",
    "description": "...",
    "energyCost": 0,
    "repeatable": true,
    "rooms": [
      { "id": "..." },
      { "id": "..." }
    ]
  }
}

Field Reference

Field	Type	Required	Description
id	string	✅	Namespaced ID. Format: pack_id:group/dungeon_name
displayName	string	✅	Translation key for the dungeon display name
description	string	✅	Translation key for the dungeon description
energyCost	number	✅	Energy the player spends to enter. Use 0 for free entry.
repeatable	boolean	✅	true = farmable. false = one-time only (e.g. tutorial).
rooms	array	✅	Ordered list of room IDs. Each entry: { "id": "namespaced_room_id" }

Content Reference Chain

dungeon.json  →  lists room IDs
room.json     →  lists hostile IDs + rewards
hostile.json  →  defines enemy stats

Example — One-Time Tutorial Dungeon

{
  "dungeon": {
    "id": "stellar_forge:training/boot_camp",
    "displayName": "dungeons.stellar_forge.training.boot_camp",
    "description": "dungeons.stellar_forge.training.boot_camp.desc",
    "energyCost": 0,
    "repeatable": false,
    "rooms": [
      { "id": "stellar_forge:training/basic_combat_room" },
      { "id": "stellar_forge:training/loot_intro_room" },
      { "id": "stellar_forge:training/commander_fight" }
    ]
  }
}

Free to enter, plays through three rooms in order, cannot be repeated. Good for introductory content.

Example — Repeatable Farming Dungeon

{
  "dungeon": {
    "id": "stellar_forge:asteroids/mining_belt_raid",
    "displayName": "dungeons.stellar_forge.asteroids.mining_belt_raid",
    "description": "dungeons.stellar_forge.asteroids.mining_belt_raid.desc",
    "energyCost": 15,
    "repeatable": true,
    "rooms": [
      { "id": "stellar_forge:asteroids/patrol_drones_room" },
      { "id": "stellar_forge:asteroids/cargo_bay_room" },
      { "id": "stellar_forge:asteroids/ambush_room" },
      { "id": "stellar_forge:asteroids/excavator_boss_room" }
    ]
  }
}

Example — High-Cost Elite Dungeon (Repeated Room)

{
  "dungeon": {
    "id": "stellar_forge:void/collapsed_star",
    "displayName": "dungeons.stellar_forge.void.collapsed_star",
    "description": "dungeons.stellar_forge.void.collapsed_star.desc",
    "energyCost": 50,
    "repeatable": true,
    "rooms": [
      { "id": "stellar_forge:void/void_sentinels_room" },
      { "id": "stellar_forge:void/void_sentinels_room" },
      { "id": "stellar_forge:void/void_overlord_room" }
    ]
  }
}

The same room ID appears twice — this is valid. Players fight that room twice in sequence before the boss.

Language Keys

"dungeons.stellar_forge.asteroids.mining_belt_raid":      "Mining Belt Raid",
"dungeons.stellar_forge.asteroids.mining_belt_raid.desc": "Bandits have seized a civilian mining operation. Drive them out.",
"dungeons.stellar_forge.void.collapsed_star":      "The Collapsed Star",
"dungeons.stellar_forge.void.collapsed_star.desc": "At the edge of known space, something ancient stirs."