1 files changed, 92 insertions, 0 deletions
diff --git a/building_guide/hidden_objects.md b/building_guide/hidden_objects.md
new file mode 100644
index 0000000..e79c026
--- /dev/null
+++ b/building_guide/hidden_objects.md
@@ -0,0 +1,92 @@
+## Hidden Objects
+
+Objects with `hidden: true` don't appear in the room's object listing. Players discover them by reading room descriptions or trying commands. The object is still fully interactable — `push gate`, `look gate`, etc.
+
+```yaml
+# data/objects/secret_lever.yaml
+id: secret_lever
+name: stone lever
+hidden: true
+description: "A cleverly concealed lever behind a loose stone."
+use_interactions:
+  - condition:
+      flag: secret_passage_open
+      value: true
+      not: true
+    message: "You pull the lever. A grinding sound echoes from the east."
+    action:
+      set_flags:
+        secret_passage_open: true
+```
+
+Room description hints at it:
+```yaml
+description: "A dusty corridor. One of the wall stones looks slightly out of place."
+```
+
+### Multiple names (`aliases`)
+
+By default an object matches its `name` (word-prefix matching) and the words in
+its `id`. Add `aliases` to accept extra names:
+
+```yaml
+id: 1002_shuttle
+name: landing craft        # matches "landing", "craft", "landing craft"
+aliases: [shuttle, ship]   # also matches "shuttle" and "ship"
+hidden: true
+```
+
+If a player's input matches more than one distinct object, `look` lists the
+candidates ("That's ambiguous, which one?") instead of guessing — so keep aliases
+specific enough to avoid overlap between objects in the same room.
+
+### Descriptions that react to flags
+
+An object can show different `look` text depending on the looking player's flags,
+using a `descriptions` list (first matching condition wins). This is the simplest
+way to fake per-player scenery — a crowd that becomes a queue, an NPC that
+"appears" partway through a scene — without spawning real objects or mobs.
+
+**If none of the variants match, the object is treated as absent for that
+player** — `look <it>` reports nothing is there. Combined with `hidden: true`, the
+same shared object can appear only while a player's flags warrant it (e.g. during
+an intro) and vanish on return visits.
+
+```yaml
+id: 1002_crowd
+name: crowd of people
+aliases: [people, crowd, passengers]
+hidden: true
+descriptions:
+  - condition:                       # after the pilot arrives
+      all_of:
+        - player_flag: boarded
+          not: true
+        - player_flag: lined_up
+    text: "The passengers have formed a single-file line."
+  - condition:                       # before the pilot arrives
+      all_of:
+        - player_flag: boarded
+          not: true
+        - player_flag: lined_up
+          not: true
+    text: "A couple dozen anxious passengers mill about the pad."
+  # once `boarded` is set, no variant matches -> the crowd is gone
+```
+
+A plain `description:` (with no `descriptions:` list) is always present, as before.
+
+### Safespot Objects
+
+Safespot objects should always be `hidden: true`. They only become visible in `look` when the player's effective safespot tier meets the object's `safespot.tier` requirement. This creates a natural discovery mechanic: completing quests and achievements reveals new coverage opportunities.
+
+Players can discover safespots by:
+- Reading room descriptions for hints
+- Trying `hide <object_name>` (name matching works even for hidden objects)
+- Using `look <object>` once they know the name
+- Gaining tier through progression, which reveals safespots in `look`
+
+See [Safespots](objects.md#safespots) for the full YAML format.
+
+---
+