Full Example

A complete game world JSON demonstrating rooms, items, NPCs, creatures, exits, containers, dice rolls, and quest flags working together.

Game Overview

This example creates a small adventure where the player starts in a tavern, talks to a wizard to receive a quest, explores a forest, fights a spider, uses a lockpick to open a locked gate, and retrieves a crystal from a cave.

Complete JSON

{
  "meta": {
    "name": "The Crystal Quest",
    "description": "Retrieve the Crystal of Power from the forest cave and return it to the wizard.",
    "starting_room": "tavern",
    "version": "1.0"
  },

  "rooms": {
    "tavern": {
      "name": "The Rusty Flagon",
      "description": "A cozy tavern with a crackling fireplace. The bartender polishes glasses behind the bar. A wooden chest sits in the corner.",
      "items": ["rusty_sword", "tavern_chest", "old_map"],
      "npcs": ["wizard"],
      "creatures": [],
      "exits": {
        "north": "forest_edge"
      },
      "on_enter": {
        "type": "message",
        "text": "The warmth of the fire embraces you. A wizard in the corner catches your eye."
      }
    },
    "forest_edge": {
      "name": "Forest Edge",
      "description": "Tall trees loom before you. A narrow path winds into the dark woods. You can hear something skittering in the undergrowth.",
      "items": ["rusty_key"],
      "npcs": [],
      "creatures": [],
      "exits": {
        "south": "tavern",
        "north": "deep_forest"
      }
    },
    "deep_forest": {
      "name": "Deep Forest",
      "description": "The canopy blocks out most of the light. Thick webs hang between the trees. An iron gate blocks the path further north.",
      "items": [],
      "npcs": [],
      "creatures": ["giant_spider"],
      "exits": {
        "south": "forest_edge",
        "north": {
          "to": "crystal_cave",
          "keywords": ["gate", "iron gate"],
          "use_item": "rusty_key",
          "on_unlock": "The rusty key turns in the lock with a grinding screech. The gate swings open.",
          "permanently_unlock": true,
          "consume_item": true,
          "locked_msg": "An iron gate blocks the way. It's locked.",
          "sets_flag": "gate_opened"
        }
      }
    },
    "crystal_cave": {
      "name": "Crystal Cave",
      "description": "The cave glows with an ethereal blue light. In the center, a crystal floats above a stone pedestal.",
      "items": ["power_crystal"],
      "npcs": [],
      "creatures": [],
      "exits": {
        "south": "deep_forest"
      },
      "on_enter": {
        "type": "message",
        "text": "The air hums with magical energy. You feel the crystal calling to you."
      }
    }
  },

  "items": {
    "rusty_sword": {
      "name": "Rusty Sword",
      "description": "A dull but serviceable blade. Better than nothing.",
      "keywords": ["sword", "blade"],
      "weapon_damage": 5
    },
    "health_potion": {
      "name": "Health Potion",
      "description": "A small vial of glowing red liquid.",
      "keywords": ["potion", "vial"],
      "consumable": true,
      "combat_effect": {
        "type": "heal",
        "amount": 15
      }
    },
    "rusty_key": {
      "name": "Rusty Key",
      "description": "An old iron key covered in rust. It might fit the gate in the forest.",
      "keywords": ["key", "iron key"]
    },
    "power_crystal": {
      "name": "Crystal of Power",
      "description": "A brilliant blue crystal that pulses with magical energy.",
      "keywords": ["crystal", "blue crystal"]
    },
    "spider_silk": {
      "name": "Spider Silk",
      "description": "A bundle of incredibly strong silk from the giant spider.",
      "keywords": ["silk", "web"],
      "defense_bonus": 2
    },
    "spell_book": {
      "name": "Spell Book",
      "description": "A leather-bound tome filled with arcane knowledge.",
      "keywords": ["book", "tome"]
    },
    "tavern_chest": {
      "name": "Wooden Chest",
      "description": "A small wooden chest tucked in the corner.",
      "keywords": ["chest", "box"],
      "is_container": true,
      "takeable": false,
      "locked": false,
      "on_open_message": "The chest lid creaks open.",
      "contents": ["health_potion"]
    },
    "old_map": {
      "name": "Faded Map",
      "description": "A map showing the forest paths. There's an X marked at a cave.",
      "keywords": ["map"],
      "takeable": false,
      "on_examine": {
        "text": "Studying the map carefully, you notice a hidden trail marked with small runes."
      }
    }
  },

  "npcs": {
    "wizard": {
      "name": "Old Wizard",
      "description": "An elderly wizard in blue robes. His beard nearly touches the floor.",
      "keywords": ["wizard", "old man", "mage"],
      "dialogue": {
        "greeting": "Ah, a brave soul! I've been waiting for someone like you. Ask me about the quest.",
        "default": "Hmm, I know nothing of that.",
        "sets_flag": "met_wizard",
        "topics": {
          "quest": {
            "keywords": ["quest", "mission", "adventure"],
            "text": "Deep in the forest lies a Crystal of Power. Retrieve it and bring it to me. Take this key - you'll need it for the gate. And take the sword by the bar, you'll need it too.",
            "sets_flag": "quest_started",
            "leads_to": ["crystal", "danger"]
          },
          "crystal": {
            "keywords": ["crystal", "power"],
            "text": "The Crystal of Power is an ancient artifact. It must not fall into the wrong hands.",
            "locked_text": "Ask me about the quest first."
          },
          "danger": {
            "keywords": ["danger", "warning", "monster"],
            "text": "Beware the giant spider that guards the forest path. It won't let you pass easily.",
            "locked_text": "There's nothing to warn you about yet."
          }
        }
      },
      "accepts_item": "power_crystal",
      "gives_item": "spell_book",
      "accept_message": "The wizard's eyes widen. 'You found it! The Crystal of Power! As promised, take this spell book. You've earned it, adventurer.'",
      "sets_flag": "quest_complete"
    }
  },

  "creatures": {
    "giant_spider": {
      "name": "Giant Spider",
      "description": "A spider the size of a large dog. Its fangs drip with venom.",
      "keywords": ["spider"],
      "health": 20,
      "attack": 6,
      "defense": 1,
      "on_defeat_msg": "The spider collapses, its legs curling inward. A bundle of silk falls from its web.",
      "on_flee_msg": "You scramble away from the spider's reach!",
      "loot": ["spider_silk"],
      "sets_flag_on_defeat": "spider_defeated"
    }
  }
}

Where Things Start

Placement is part of each room definition above: the items, npcs, and creatures arrays say what is in the room when the game begins. In this world the sword, chest, and map start in the tavern with the wizard; the key lies at the forest edge; the spider waits in the deep forest; and the crystal sits in the cave. The health potion is never listed in a room because it starts inside the chest, and the spider silk and spell book only appear as loot and as the wizard's reward.

Sample Walkthrough

# Start in tavern
> look
> talk to wizard
> talk to wizard about quest      # Starts quest, unlocks topics
> talk to wizard about danger      # Learn about the spider
> take sword
> open chest                       # Find health potion
> take potion

# Head into the forest
> go north                         # Forest Edge
> take key
> go north                         # Deep Forest

# Fight the spider
> attack spider                    # Combat begins
> attack                           # Deal damage
> attack                           # Keep fighting
> use potion                       # Heal if needed
> attack                           # Defeat spider, get silk
> take silk

# Unlock the gate
> use key on gate                  # Unlock the iron gate
> go north                         # Crystal Cave

# Get the crystal
> take crystal

# Return to the wizard
> go south
> go south
> go south                         # Back to tavern
> give crystal to wizard           # Quest complete! Get spell book

Flags Used