Exits

Exits connect rooms together. They range from simple one-way pointers to complex locked passages with keywords, flags, and reveal mechanics.

Simple Exits

The simplest exit is just a direction mapped to a destination room ID:

"exits": {
  "north": "town_square",
  "east": "forest",
  "up": "tower_top"
}

Players can use go north, n, or walk north to move.

Available Directions

Direction	Shortcuts
north	n
south	s
east	e
west	w
northeast	ne
northwest	nw
southeast	se
southwest	sw
up	u
down	d
in	—
out	—

Complex Exits

For exits with conditions, locks, or special behavior, use an object instead of a plain string:

"north": {
  "to": "throne_room",
  "keywords": ["door", "iron door", "heavy door"],
  "requires": "throne_key",
  "locked_msg": "The iron door is locked. You need a key.",
  "unlocked_msg": "The iron door stands open."
}

Complex Exit Fields

Field	Type	Required	Description
`to`	string	required	Destination room ID.
`keywords`	array	optional	Natural language names for the exit. Lets players say `use key on door` instead of `use key on north`.
`requires`	string	optional	Item ID that must be in the player's inventory to pass.
`requires_flag`	string	optional	A global flag that must be `true` for the exit to be usable.
`locked_msg`	string	optional	Message shown when the player tries to use a locked exit.
`unlocked_msg`	string	optional	Message shown when the exit is available/unlocked.

Interactive Unlocking

Exits can be unlocked by using a specific item on them. This gives you more control than the passive requires check.

"east": {
  "to": "secret_chamber",
  "keywords": ["gate", "iron gate"],
  "use_item": "skeleton_key",
  "on_unlock": "The skeleton key turns with a satisfying click.",
  "permanently_unlock": true,
  "consume_item": true,
  "sets_flag": "secret_chamber_unlocked",
  "locked_msg": "An iron gate blocks the passage."
}

Field	Type	Default	Description
`use_item`	string	—	Item ID that can unlock this exit when used on it.
`on_unlock`	string	—	Message displayed when the exit is unlocked with the item.
`permanently_unlock`	boolean	`false`	If `true`, the exit stays unlocked permanently after first use.
`consume_item`	boolean	`false`	If `true`, the item is removed from inventory when used.
`sets_flag`	string	—	Global flag set to `true` when the exit is unlocked or used.

Players unlock interactive exits with: use skeleton_key on gate or use skeleton_key on east

Hidden Exits

Hidden exits don't appear in the room's exit list until they are revealed. They can be revealed by examining items, using items, or setting flags.

"west": {
  "to": "hidden_passage",
  "hidden": true,
  "reveal_msg": "A hidden passage is revealed behind the bookcase!"
}

Field	Type	Description
`hidden`	boolean	If `true`, this exit is not shown in exit listings until revealed.
`reveal_msg`	string	Message shown when the exit is revealed.

Ways to Reveal Hidden Exits

1. Via item examination

Set on_examine.reveals_exit on an item in the room:

"old_painting": {
  "name": "old painting",
  "description": "A landscape painting. Something seems off...",
  "on_examine": {
    "reveals_exit": "west",
    "text": "Behind the painting, you discover a hidden lever!"
  }
}

2. Via item use

Set reveals_exit on an item:

"magic_lens": {
  "name": "magic lens",
  "reveals_exit": {
    "direction": "west",
    "message": "Through the lens, a hidden door shimmers into view!"
  }
}

3. Via flag

Use requires_flag — when the flag is set, the exit auto-reveals.

Exit Keywords

Keywords let players reference exits by name instead of direction. This makes interactions feel more natural:

"north": {
  "to": "castle_interior",
  "keywords": ["drawbridge", "castle gate", "gate"],
  "use_item": "castle_key",
  "locked_msg": "The castle gate is sealed shut."
}

Now players can type:

use castle_key on gate (instead of use castle_key on north)
go drawbridge (instead of go north)

Keywords are case-insensitive and support multi-word phrases.

Full Example

"exits": {
  // Simple exit
  "north": "town_square",

  // Locked exit requiring inventory item
  "east": {
    "to": "treasury",
    "requires": "gold_key",
    "locked_msg": "The door is locked."
  },

  // Interactive unlock with keywords
  "south": {
    "to": "dungeon",
    "keywords": ["trapdoor", "hatch"],
    "use_item": "crowbar",
    "on_unlock": "You pry open the trapdoor with a groan of metal.",
    "permanently_unlock": true,
    "consume_item": false,
    "locked_msg": "A heavy trapdoor. It won't budge by hand."
  },

  // Hidden exit
  "west": {
    "to": "secret_room",
    "hidden": true,
    "reveal_msg": "A section of wall slides away!"
  }
}