World Structure

The world data is a single JSON object with five top-level keys. This is the root document that defines your entire game.

Schema

{
  "meta": {
    "name": "My Adventure",        // Required - human-readable game name
    "description": "A short quest...", // Required - game description
    "starting_room": "room_id",   // Required - where the player begins
    "version": "1.0"              // Optional - version identifier
  },
  "rooms": {
    "room_id": { /* room definition */ }
  },
  "items": {
    "item_id": { /* item definition */ }
  },
  "npcs": {
    "npc_id": { /* NPC definition */ }
  },
  "creatures": {
    "creature_id": { /* creature definition */ }
  }
}

meta

Controls game-wide configuration.

Field	Type	Required	Description
name	string	required	Human-readable name for the game, displayed to players.
description	string	required	A short description of the game or its premise.
starting_room	string	required	The room ID where the player begins. Must match a key in rooms.
version	string	optional	Version identifier for your game world.
author	string	optional	Who wrote the world. Informational only.

rooms

An object where each key is a unique room ID and each value is a Room definition. Room IDs are used throughout the world data to reference locations.

"rooms": {
  "tavern": { /* ... */ },
  "cellar": { /* ... */ },
  "forest_clearing": { /* ... */ }
}

items

An object where each key is a unique item ID and each value is an Item definition. Items are placed by listing their IDs in a room's items array. See Placing Entities in Rooms.

"items": {
  "rusty_sword": { /* ... */ },
  "health_potion": { /* ... */ },
  "wooden_chest": { /* ... */ }
}

npcs

An object where each key is a unique NPC ID and each value is an NPC definition. NPCs are placed by listing their IDs in a room's npcs array. See Placing Entities in Rooms.

"npcs": {
  "bartender": { /* ... */ },
  "mysterious_wizard": { /* ... */ }
}

creatures

An object where each key is a unique creature ID and each value is a Creature definition. Creatures are placed by listing their IDs in a room's creatures array (see Placing Entities in Rooms) and can be attacked to initiate combat.

"creatures": {
  "goblin": { /* ... */ },
  "dragon": { /* ... */ }
}

About IDs

All IDs (room, item, NPC, creature) are strings you define. They are used internally to reference entities across the world data. Recommendations:

• Use lowercase with underscores: old_sword, dark_forest
• Keep them descriptive but concise
• IDs must be unique within their category (rooms, items, npcs, creatures)
• IDs are never shown to the player - they only see name fields

Placing Entities in Rooms

Items, NPCs, and creatures are placed by listing their IDs on the room itself. Every room definition accepts three optional arrays:

"tavern": {
  "name": "The Tavern",
  "description": "A dimly lit tavern with a roaring fireplace...",
  "exits": { "north": "town_square" },
  "items": ["rusty_sword", "health_potion"],
  "npcs": ["bartender"],
  "creatures": ["goblin"]
}

When a game starts, the engine copies these arrays into each room's room state, which then changes as players take items and defeat creatures. Your world definition is never modified. Items that only ever come out of a container, a creature's loot, or an NPC's gives_item do not need to be listed in any room.