From 2725e2927a1595c7b100d942d1f14146252adeb7 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Thu, 25 Jun 2026 04:46:40 -0400
Subject: feat: who, global chat, removed redundant YAML IDs

---
 building_guide/objects.md | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

(limited to 'building_guide/objects.md')

diff --git a/building_guide/objects.md b/building_guide/objects.md
index 427968a..110eb56 100644
--- a/building_guide/objects.md
+++ b/building_guide/objects.md
@@ -4,9 +4,28 @@ Objects interact with the world through **inline behavior configs** under
 `gather:`, `talk:`, or `use:` keys. There is no separate behavior
 directory — everything goes directly in the object's YAML.
 
+### Naming & file organization
+
+**The filename is the ID.** An object is looked up by its filename stem
+(`copper_rock.yaml` → `copper_rock`), and the loader derives `ObjectDef.ID` from that
+filename. Rooms reference the object by this bare ID regardless of which folder the file
+lives in. **Do not put an `id:` field in the file** — it is ignored. (A nested `- id:` under
+a room's `objects:` list is a different thing: a *reference* to an object by its filename,
+and is still required there.)
+
+- **Generic, shared objects** (rocks, trees, altars, stations) use a semantic name and live
+  flat in `data/objects/` — e.g. `data/objects/copper_rock.yaml`.
+- **Room-specific one-offs** (signs, set-dressing, scenery for a single room) are prefixed
+  with the room number and placed in `data/objects/unique/` — e.g.
+  `data/objects/unique/1001_sign.yaml` (ID `1001_sign`, referenced from room `1001`).
+
+Loading walks `data/objects/` recursively, so subdirectories are purely organizational and
+need no changes to room references when a file is moved. They do **not** namespace IDs: every
+filename stem must be globally unique across all of `data/objects/`. Use `hidden: true` for
+signage/scenery so it doesn't appear in room listings.
+
 Gathering object (mining):
 ```yaml
-id: copper_rock
 name: copper rock
 color: "178"                   # xterm-256 color index (0-255)
 gather:
@@ -37,7 +56,6 @@ gather:
 
 Tree object (woodcutting with shared depletion):
 ```yaml
-id: oak_tree
 name: oak tree
 color: "113"
 gather:
@@ -70,7 +88,6 @@ ANSI color.
 
 Object interaction (gate, lever — uses `use_interactions:` key):
 ```yaml
-id: iron_gate
 name: iron gate
 hidden: true
 description: "A heavy iron gate set into the north wall."
@@ -87,14 +104,12 @@ use_interactions:
 
 Decorative object (no behavior keys — just a name/description):
 ```yaml
-id: lumby_fountain
 name: town fountain
 description: "Clear water sparkles in the sunlight."
 ```
 
 Talk object (NPC conversations — uses `talk:` key):
 ```yaml
-id: tool_shed
 name: Tool Shed
 description: "A small shed with an open window."
 talk:
@@ -121,7 +136,6 @@ Entries are checked top-to-bottom; the first match with a passing condition wins
 
 Simple message (no action):
 ```yaml
-id: anvil
 name: anvil
 use_interactions:
   - item_id: silver_bar
@@ -132,7 +146,6 @@ use_interactions:
 
 Puzzle interaction (take item, set flag):
 ```yaml
-id: crystal_slot
 name: crystal slot
 use_interactions:
   - item_id: crystal_key
@@ -201,7 +214,6 @@ use_interactions:
 Objects can be stealable via the `steal` command. These use the same drop table system as mobs and searches.
 
 ```yaml
-id: market_stall
 name: Market Stall
 description: "A wooden stall piled with food and sundries."
 steal_table: market_stall_steal
@@ -234,7 +246,6 @@ crouch behind them and attack with ranged or science weapons. Melee attacks forc
 out of cover.
 
 ```yaml
-id: rock_outcrop
 name: rock outcrop
 color: "248"
 hidden: true
-- 
cgit v1.2.3