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.

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 in rooms via room state.

"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 in rooms via room state.

"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 in rooms via room state 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

Initial Room State

Items, NPCs, and creatures are placed into rooms via the initial room state, which is set up when the game starts. Each room gets a state object tracking what's currently in it:

// This is set up automatically by the engine from your world data.
// You define which entities go in which rooms here:
{
  "items": ["rusty_sword", "health_potion"],
  "npcs": ["bartender"],
  "creatures": ["goblin"]
}

See Flags & State for full details on how game state works.