progress

AGENTS.md

@@ -200,6 +200,79 @@ Each room has:
 - `GameScript` (GameScript.gd) - Script builder for cutscenes
 - `Ego` (Ego.gd) - Player character
 
+## Interaction System (Global)
+
+The game uses a **cursor-based action system** with 4 modes that cycle via right-click:
+
+| Cursor | Action | Icon | Purpose |
+|--------|--------|------|---------|
+| 0 | Walk | boot_icon.png | Move player to location |
+| 1 | Look | eye_icon.png | Examine objects/room |
+| 2 | Touch | hand_icon.png | Interact with objects |
+| 3 | Talk | speech_icon.png | Talk to characters |
+
+### Key Components
+
+#### ActionState (Autoload)
+Global singleton (`ActionState.gd`) that tracks the current cursor action:
+```gdscript
+ActionState.current_action  # 0-3 (WALK, LOOK, TOUCH, TALK)
+ActionState.Action.WALK     # Enum values
+```
+
+#### SetPiece Nodes
+Interactive areas in rooms use `SetPiece_.gd` (extends Polygon2D):
+
+**Signals emitted:**
+- `interacted` - Generic interaction (takes precedence over cursor actions)
+- `walked` - When walk cursor clicks the piece
+- `looked` - When look cursor clicks the piece  
+- `touched` - When touch cursor clicks the piece
+- `talked` - When talk cursor clicks the piece
+
+**Priority Rule:** If `interacted` signal has connections, it overrides cursor-specific actions.
+
+### Room Setup for Interactions
+
+1. **Add SetPiece nodes** to room scene for interactive objects:
+```gdscript
+[node name="pool" type="Polygon2D" parent="."]
+polygon = PackedVector2Array(...)
+script = ExtResource("SetPiece_.gd")
+label = "Pool"
+```
+
+2. **Connect signals** in .tscn:
+```gdscript
+[connection signal="looked" from="pool" to="." method="_on_pool_looked"]
+```
+
+3. **Implement handlers** in room script:
+```gdscript
+func _on_pool_looked() -> void:
+    start_main_script(ScriptBuilder.init(
+        ScriptBuilder.say(ego, "The water looks inviting.")
+    ).build(self, "_on_script_complete"))
+```
+
+### Room-Wide Look
+
+Clicking empty space with look cursor triggers `_on_room_looked()`:
+```gdscript
+func _on_room_looked() -> void:
+    # Override in room script for room description
+    start_main_script(ScriptBuilder.init(
+        ScriptBuilder.say(ego, "Room description here...")
+    ).build(self, "_on_script_complete"))
+```
+
+### Behavior Rules
+
+1. **Precedence**: `interacted` signal always wins if connected
+2. **Fallback**: If no handler for cursor action, do nothing (silent)
+3. **SetPiece detection**: Mouse must be inside polygon
+4. **Unhandled clicks**: Scene._unhandled_input handles empty space
+
 ### Common Patterns
 
 #### Navigation