From 9292634f2f8d71a53879ff07e1330c671b207d51 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Mon, 6 Jul 2026 23:05:04 -0400
Subject: feat: split the concept of hidden and impassable exits. add
 player_flag for discovered hidden exits.

---
 building_guide/rooms.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

(limited to 'building_guide/rooms.md')

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index d3412de..111404a 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -90,6 +90,40 @@ exits:
       boarded_shuttle: true        # marks "left this area" on the way out
 ```
 
+### Hidden exits
+
+Hidden exits are invisible in `look` and `verbs` output until the player
+discovers them by traversing them once. Even hidden, the exit is still
+traversable — just not listed. Once a player moves through a hidden exit, it
+becomes "discovered" for that character and appears in listing with a
+`(HIDDEN)` tag. On the map, hidden exits (and rooms only reachable via them)
+do not appear until the character discovers them. Gods in `god` mode see all
+hidden exits regardless of discovery.
+
+```yaml
+exits:
+  down:
+    room: 1002
+    hidden: true
+```
+
+### Always-blocked exits
+
+Always-blocked exits are impassable to players but always visible. They
+appear in `look`/`verbs` and render on the map as blocked `X` connectors.
+Gods in `god` mode can traverse them. Primarily used for agility course
+room-to-room links so the map can lay the course out visually.
+
+```yaml
+exits:
+  north:
+    room: 99999221
+    always_blocked: true
+```
+
+Hidden and always_blocked can be combined: the exit is invisible until
+discovered (or seen by a god), and then shows as impassable.
+
 ### Map grid & one-way exits
 
 All exits (north/south/east/west/ne/nw/se/sw) must form a consistent 3D grid: from
-- 
cgit v1.2.3