Dungeon JSON Schema

Dungeon JSON Schema

Dungeon rooms are described in source/core/assets/configs/rooms.json. This page explains the fields that are important when adding or changing a room. For how the game turns this file into playable rooms, see Dungeon Generation.

All x and y values are tile positions.

World

{
  "startRoomId": "selection",
  "startEntryPointId": "start",
  "rooms": []
}

• startRoomId is the first room loaded.
• startEntryPointId says where the player starts in that room.
• rooms contains the selection room and every dungeon room.

The exits between these rooms form the dungeon graph.

Room

{
  "id": "dungeonOneEntrance",
  "dungeonId": "dungeonOne",
  "title": "Dungeon One: Entrance",
  "mapWidth": 50,
  "mapHeight": 50,
  "entryPoints": [],
  "enemySpawns": [],
  "obstacles": [],
  "exits": []
}

• id is the room's unique name. Other rooms use it as a destination.
• dungeonId groups rooms into one dungeon. It is null for the selection room.
• title is shown on screen.
• mapWidth and mapHeight set the room size in tiles.
• entryPoints are named player spawn positions.
• enemySpawns, obstacles and exits describe what appears in the room.

Room contents

Entry point

{ "id": "fromSelection", "x": 10, "y": 10 }

An entry point is a named position. It is used when the game starts or when the player arrives through a bookshelf.

Enemy

{ "type": "CHASE", "x": 30, "y": 28 }

type can be BOMB, CHASE or FLOATING_DEMON.

Obstacle

{ "type": "BARREL", "x": 17, "y": 14 }

type can be ROCK or BARREL.

Exits

An exit has an id, a kind, a position and the room it leads to. Set requiresClear to prevent the player leaving while enemies are alive.

Bookshelf

Bookshelves connect the selection room and a dungeon. They place the player at a named entry point in the destination room.

{
  "id": "dungeonOneShelf",
  "kind": "BOOKSHELF",
  "x": 20,
  "y": 21,
  "destinationRoomId": "dungeonOneEntrance",
  "destinationEntryPointId": "fromSelection"
}

A shelf can be shown but disabled:

{
  "id": "dungeonTwoShelf",
  "kind": "BOOKSHELF",
  "x": 20,
  "y": 16,
  "available": false,
  "message": "This dungeon is not available yet."
}

Set completesDungeon to true on the final bookshelf. Using it records the dungeon as completed before returning to the selection room.

Paired doors

Doors connect two dungeon rooms. Each door points to the matching door in the other room:

{
  "id": "sideDoor",
  "kind": "DOOR",
  "x": 48,
  "y": 14,
  "side": "RIGHT",
  "destinationRoomId": "dungeonOneSide",
  "destinationExitId": "returnDoor",
  "requiresClear": true
}

The matching door points back to sideDoor. Its side must face the opposite direction. Valid sides are LEFT, RIGHT, TOP and BOTTOM. This pairing lets the game place the player just inside the door they entered.

Adding a dungeon

1. Add its rooms to the rooms list and give them the same dungeonId.
2. Give each room its entry points, enemies, obstacles and exits.
3. Connect dungeon rooms with paired doors.
4. Add a bookshelf in the selection room that leads to the dungeon entrance.
5. Mark the dungeon's final bookshelf with completesDungeon: true.

Room IDs and referenced entry or exit IDs must match exactly. The configuration is checked when the game starts, so broken room links are reported immediately.

AI declaration

LLM aid (GPT 5.6 Sol) was used in writing this page.