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/courses.md |  2 +-
 building_guide/rooms.md   | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

(limited to 'building_guide')

diff --git a/building_guide/courses.md b/building_guide/courses.md
index e5deb32..5e92318 100644
--- a/building_guide/courses.md
+++ b/building_guide/courses.md
@@ -6,7 +6,7 @@ Agility courses are defined in `data/courses/<id>.yaml`. Each course defines a s
 
 > Editing courses is done from the **Map screen** in the admin web GUI: select an obstacle room and use its **Course** side-panel tab to create a course, add the room as a step, edit all of its parameters, or remove it. The legacy standalone "Courses" editor tab has been removed.
 >
-> When a room is added as a course step, the admin GUI auto-creates **hidden one-way exits** between consecutive obstacle rooms so the in-game map can lay them out correctly. The direction of these hidden exits is chosen by the builder. Hidden exits are invisible in `look` output and cannot be traversed — they exist solely for map rendering. On the map, course links appear as blue dashed one-way arrows (colored via the `map_course` theme token).
+> When a room is added as a course step, the admin GUI auto-creates **always-blocked one-way exits** between consecutive obstacle rooms so the in-game map can lay them out correctly. The direction of these exits is chosen by the builder. Always-blocked exits are impassable to players but visible on the map — they exist solely for map rendering. On the map, course links appear as blue dashed one-way arrows (colored via the `map_course` theme token).
 
 ### Course YAML
 
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