1 files changed, 85 insertions, 5 deletions
diff --git a/worldbuilding_guide/objects.md b/worldbuilding_guide/objects.md
index 6929606..3644a18 100644
--- a/worldbuilding_guide/objects.md
+++ b/worldbuilding_guide/objects.md
@@ -24,18 +24,98 @@ id: iron_gate
 name: iron gate
 behavior: iron_gate_toggle
 hidden: true
-props:
-  description: "A heavy iron gate set into the north wall."
+description: "A heavy iron gate set into the north wall."
 ```
 
 Decorative object (no behavior):
 ```yaml
 id: lumby_fountain
 name: town fountain
-behavior: ""
-props:
-  description: "Clear water sparkles in the sunlight."
+description: "Clear water sparkles in the sunlight."
 ```
 
 ---
 
+## Use Interactions
+
+Objects can define `use_interactions` to handle when a player uses a specific item on the object. Each interaction can check conditions, show a message, and execute actions — using the same condition and action primitives as the talk system.
+
+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: silver_bar
+    message: "You should use this with a mold at a furnace."
+  - item: gold_bar
+    message: "You should use this with a mold at a furnace."
+```
+
+Puzzle interaction (take item, set flag):
+```yaml
+id: crystal_slot
+name: crystal slot
+use_interactions:
+  - item: crystal_key
+    condition:
+      flag: crystal_inserted
+    message: "The crystal key is already in the slot."
+  - item: crystal_key
+    message: "You insert the crystal key into the slot. It clicks into place."
+    action:
+      take_item: crystal_key
+      set_flags:
+        crystal_inserted: true
+```
+
+Quest item exchange:
+```yaml
+use_interactions:
+  - item: ancient_scroll
+    condition:
+      player_flag: quest_started
+    message: "You place the scroll on the pedestal. The door rumbles open!"
+    action:
+      take_item: ancient_scroll
+      set_player_flags:
+        quest_complete: true
+      set_flags:
+        temple_door_open: true
+```
+
+### UseInteraction Fields
+
+| Field       | Type       | Description                                      |
+| ----------- | ---------- | ------------------------------------------------ |
+| `item`      | string     | Item ID that triggers this interaction            |
+| `condition` | Condition  | Optional condition (same as exits/talk/toggle)    |
+| `message`   | string     | Message shown to the player                       |
+| `action`    | NodeAction | Optional actions (same as talk node actions)      |
+
+### Available Actions (same as talk)
+
+| Field              | Type           | Description                        |
+| ------------------ | -------------- | ---------------------------------- |
+| `set_flags`        | map[string]any | Set world flags (shared)           |
+| `set_player_flags` | map[string]any | Set player flags (per-character)   |
+| `give_item`        | string         | Give an item to inventory          |
+| `take_item`        | string         | Remove an item from inventory      |
+| `teleport`         | int            | Move player to a room ID           |
+| `heal`             | int            | Restore hitpoints                  |
+
+### Available Conditions (same as exits/talk)
+
+| Field         | Description                      |
+| ------------- | -------------------------------- |
+| `flag`        | World flag check                 |
+| `player_flag` | Per-character flag check         |
+| `has_item`    | Inventory item check             |
+| `value`       | Expected value for flag checks   |
+| `not`         | Invert the condition             |
+| `all_of`      | All sub-conditions must pass     |
+| `any_of`      | Any sub-condition must pass      |
+
+---
+