feat: unify on use, on look, and on kill. all support same conditions/actions now.

1 files changed, 65 insertions, 51 deletions

diff --git a/building_guide/objects.md b/building_guide/objects.md
index a8877a7..db72cf3 100644
--- a/building_guide/objects.md
+++ b/building_guide/objects.md
@@ -49,8 +49,8 @@ objects:
     description: |-
       Conditional or multi-line descriptions work exactly like file objects.
     on_look:
-      set_player_flags:
-        1001_look_sign: true
+      - set_player_flags:
+          1001_look_sign: true
 ```
 
 - **Identity comes from `name`.** Internally the object's id is the name, normalized
@@ -69,7 +69,7 @@ objects:
 - Local objects support only the **passive subset**: `name`, `aliases`, `color`, `hidden`,
   `inroom_description`, `description` (including conditional variants), and `on_look`.
 - Interactable / stateful behavior (`gather`, `talk`, `use`, `safespot`, `steal`, `guard_mob`,
-  `removal_item`, `use_interactions`, craft stations) **must** be a standalone object file;
+  `removal_item`, `on_use`, craft stations) **must** be a standalone object file;
   startup validation errors if those appear locally.
 - Local objects are re-read from the room file on every access, so edits take effect
   immediately (file objects are cached after first load).
@@ -137,14 +137,14 @@ Color accepts xterm-256 indices with optional modifiers (`bold`, `dim`, `underli
 and gradients (`g:C4,52`). In ANSI mode, extended colors downgrade to the nearest
 ANSI color.
 
-Object interaction (gate, lever — uses `use_interactions:` key):
+Object interaction (gate, lever — uses `on_use:` key):
 ```yaml
 name: iron gate
 hidden: true
 description: "A heavy iron gate set into the north wall."
-use_interactions:
+on_use:
   - condition:
-      flag: gate_open
+      global_flag: gate_open
       value: true
       not: true
     message: "You push the heavy iron gate open."
@@ -173,35 +173,40 @@ talk:
                 - text: "\"Goodbye.\""
 ```
 
-On-look action (runs when a player examines an object with `look <name>`):
+On-look interaction (runs when a player examines an object with `look <name>`):
 ```yaml
 name: sign
 aliases: [notice, board]
 description: "A wooden signpost with faded writing."
 on_look:
-    set_player_flags:
+    - set_player_flags:
         read_sign: true
 ```
-`on_look` fires the action AFTER showing the object's description. It uses the same
-`NodeAction` type as talk nodes — supports `set_player_flags`, `set_global_flags`,
-`give_item`, `take_item`, `teleport`, `heal`, `cost`, and everything else in the
-[node action reference](behaviors.md#node-action-reference).
+`on_look` is a list of interactions (same shape as `on_use`). The first entry
+whose `item_id` and `condition` pass wins, and fires AFTER the object's
+description is shown. An entry with an `item_id` only fires if the player
+currently carries that item in their inventory (empty `item_id` = always
+fires on look). It uses the same `interaction` shape as `on_use` — supports
+`condition`, `message`, and a full `action` (`set_global_flags`,
+`set_player_flags`, `give_item`, `take_item`, `teleport`, `heal`, `credits`,
+`aps_node`, `broadcast`, `broadcast_global`, `spawn_mob`, `despawn_mob`,
+`delay`), per the [interaction reference](behaviors.md#interaction-reference).
 
 See the [Talk section of behaviors](behaviors.md#talk-dialog-trees) for the full
 dialog tree format. See [Stealable Objects](#stealable-objects) for theft mechanics.
 
 ---
 
-## 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.
+## Interactions (On Use / On Look)
 
-Entries are checked top-to-bottom; the first match with a passing condition wins.
+Objects can define `on_use` and/or `on_look` to react to player actions. Both take a
+list of interactions (entries are checked top-to-bottom; the first whose
+`condition` passes wins — one fires per use/look).
 
 Simple message (no action):
 ```yaml
 name: anvil
-use_interactions:
+on_use:
   - item_id: silver_bar
     message: "You should use this with a mold at a furnace."
   - item_id: gold_bar
@@ -211,10 +216,10 @@ use_interactions:
 Puzzle interaction (take item, set flag):
 ```yaml
 name: crystal slot
-use_interactions:
+on_use:
   - item_id: crystal_key
     condition:
-      flag: crystal_inserted
+      global_flag: crystal_inserted
     message: "The crystal key is already in the slot."
   - item_id: crystal_key
     message: "You insert the crystal key into the slot. It clicks into place."
@@ -226,7 +231,7 @@ use_interactions:
 
 Quest item exchange:
 ```yaml
-use_interactions:
+on_use:
   - item_id: ancient_scroll
     condition:
       player_flag: quest_started
@@ -239,37 +244,46 @@ use_interactions:
         temple_door_open: true
 ```
 
-### UseInteraction Fields
-
-| Field       | Type       | Description                                      |
-| ----------- | ---------- | ------------------------------------------------ |
-| `item_id`   | string     | Item ID that triggers this interaction            |
-| `condition` | Condition  | Optional condition (same as exits/talk/use_interactions)    |
-| `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_global_flags`        | map[string]any | Set global 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                      |
-| ------------- | -------------------------------- |
-| `global_flag`        | Global 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      |
+### Interaction Fields
+
+| Field       | Type       | Description                                                     |
+| ----------- | ---------- | --------------------------------------------------------------- |
+| `item_id`   | string     | `on_use`: required item id (empty = bare `use <object>`). `on_look`: only fires if you carry this item. (Mobs' `on_kill`: only fires if you wield this weapon in main_hand or off_hand.) |
+| `condition` | Condition  | Optional condition (same as exits/talk/on_enter/triggers)       |
+| `message`   | string     | Message shown to the player when this entry fires               |
+| `action`    | StepAction | Optional actions (see [interaction reference](behaviors.md#interaction-reference)) |
+
+### Available Actions (same superset as on_enter steps/triggers/talk)
+
+| Field              | Type           | Description                                           |
+| ------------------ | -------------- | ----------------------------------------------------- |
+| `set_global_flags` | map[string]any | Set global flags (shared by all players)              |
+| `set_player_flags` | map[string]any | Set player flags (per-character, saved to YAML)      |
+| `give_item`        | string         | Give an item to inventory (1 unit)                    |
+| `take_item`        | string         | Remove an item from inventory (1 unit)                |
+| `teleport`         | int            | Move player to a room ID                              |
+| `heal`             | int            | Restore hitpoints (clamped to MaxHP)                  |
+| `credits`          | int            | Add (positive) or deduct (negative) credits           |
+| `aps_node`         | bool           | Mark current room as a discovered APS node            |
+| `broadcast`        | string         | Announce to all in the room (uses `%p`, `%v`)         |
+| `broadcast_global` | string         | Announce to all online (uses `%p`, `%v`)              |
+| `spawn_mob`        | string/map     | Spawn a transient mob (`id` or full [config](behaviors.md#spawn-mob-config))         |
+| `despawn_mob`      | string         | Despawn all transient mobs of this id                 |
+| `message`          | string         | Direct message to the player (also valid here)        |
+| `delay`            | int            | Ticks to wait before this step (only meaningful in on_enter/triggers) |
+
+### Available Conditions (same as exits/talk/on_enter/triggers)
+
+| Field         | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `global_flag` | Global flag check                                       |
+| `player_flag` | Per-character flag check                               |
+| `has_item`    | Inventory item check                                   |
+| `min_credits` | Minimum credits                                        |
+| `value`       | Expected value for flag checks                         |
+| `not`         | Invert the condition                                   |
+| `all_of`      | All sub-conditions must pass                           |
+| `any_of`      | Any sub-condition must pass                            |
 
 ---