Rooms Reference

A room is a single encounter within a dungeon. Rooms can contain combat encounters, loot drops, or both. Dungeons string rooms together in sequence — players move through them one at a time.

Files live in: <your_pack_id>/data/enemies/rooms/<group_folder>/<room_name>.json

File Structure

{
  "rooms": {
    "id": "...",
    "hostiles": [ "...", "..." ],
    "gainXp": 0,
    "credits": 0,
    "description": "...",
    "loot": [
      { "id": "...", "count": 1 }
    ]
  }
}

Field Reference

Field	Type	Required	Description
id	string	✅	Namespaced ID for this room. Referenced by dungeon files.
hostiles	array	✅	List of hostile IDs in this room. Use [] for a loot-only room. Repeat the same ID to spawn multiple copies.
gainXp	number	❌	XP awarded to the player on completion. Omit or set 0 for none.
credits	number	❌	Credits awarded on completion.
description	string	❌	Flavor text shown when entering the room. Can be a translation key or raw string.
loot	array	❌	Items given to the player on entering the room (before/without combat).

loot array entry fields

Field	Type	Required	Description
id	string	✅	Namespaced item ID. Must match an item defined in a materials or equipment JSON file.
count	number	✅	How many of this item the player receives.

How Rooms Connect

dungeon.json  →  rooms[].id  →  room.json
room.json     →  hostiles[]  →  hostile.json
              →  loot[].id   →  item .json

Example — Combat Room

{
  "rooms": {
    "id": "stellar_forge:asteroids/patrol_drones_room",
    "hostiles": [
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:guards/mining_enforcer"
    ],
    "gainXp": 15,
    "credits": 250
  }
}

Two Nano Swarm drones and one Mining Enforcer. On completion: 15 XP and 250 credits.

Example — Loot Room (No Combat)

{
  "rooms": {
    "id": "stellar_forge:asteroids/cargo_bay_room",
    "hostiles": [],
    "gainXp": 5,
    "credits": 500,
    "description": "You discover an abandoned cargo bay full of salvageable materials.",
    "loot": [
      { "id": "stellar_forge:ore_uranium", "count": 3 },
      { "id": "stellar_forge:ore_xenite",  "count": 1 }
    ]
  }
}

Example — Boss Room

{
  "rooms": {
    "id": "stellar_forge:asteroids/excavator_boss_room",
    "hostiles": [ "stellar_forge:bosses/excavator_prime" ],
    "gainXp": 150,
    "credits": 5000
  }
}

Example — Ambush Room

{
  "rooms": {
    "id": "stellar_forge:asteroids/ambush_room",
    "hostiles": [
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:drones/nano_swarm",
      "stellar_forge:guards/mining_enforcer"
    ],
    "gainXp": 30,
    "credits": 400,
    "description": "Warning: Proximity sensors triggered. Multiple contacts incoming."
  }
}

Design Tips

• Start dungeons easy, end hard. First rooms should be lighter than the last.
• Use loot rooms as breathing room. A loot room mid-dungeon gives players a break before the final boss.
• Scale rewards to difficulty. Boss rooms should pay out significantly more than patrol rooms.
• Repeating the same room ID is valid. A dungeon can reference the same room ID multiple times.