changes for stuff

.opencode/skills/kq4-room-navigator/SKILL.md

@@ -0,0 +1,170 @@
+---
+
+## name: kq4-room-navigator description: Navigate between KQ4 rooms using the Godot MCP server. BFS pathfinds through room transition graph, then executes step-by-step clicks via McpInteractionServer (port 9090). Use when planning navigation between any two rooms or simulating player movement through the game world at runtime. Trigger phrases: "navigate from", "go to room", "path from X to Y", "walk to", "how do I get to room", "room navigation".
+
+# KQ4 Room Navigator
+
+## Overview
+
+This skill finds shortest paths between rooms and can execute them through the running game using Godot's MCP server. It combines offline `.tscn` file parsing for graph construction with runtime interaction via McpInteractionServer (TCP port 9090).
+
+The room transition system uses TransitionPiece nodes: each has an `exit_node_name` (destination), a clickable polygon, and connects rooms bidirectionally. Clicking a TransitionPiece triggers a 3-step animation (walk → fade/swap scenes → walk to entrance in new room).
+
+## When to Use
+
+- Planning multi-room navigation paths
+- Verifying room connectivity
+- Debugging why a path can't be traversed
+- Automating room transitions during testing
+- Generating step-by-step click instructions for agents
+
+## How It Works
+
+```
+.scenes/*.tscn files → adjacency graph (96 rooms, 233 exits) → BFS pathfinding  → use MCP for execution
+```
+
+Room identification at runtime:
+
+- Game node tree: `/root/Node2D/SceneViewport/background` (always named "background")
+- Room identity comes from `background.get_script().resource_path` (e.g., `res://scenes/kq4_010_forest_path/kq4_010_forest_path.gd`)
+- TransitionPiece children have `.target` UIDs and `.label` strings for cross-referencing
+
+## Quick Start
+
+### Step 1 Make a plan:
+
+```bash
+python tools/kq4_room_navigator.py --from kq4_003_fountain_pool --to kq4_011_enchanted_grove
+```
+
+Output:
+
+```
+Path: kq4_003_fountain_pool → kq4_011_enchanted_grove (3 steps)
+  1. Click 'kq4_004_ogres_cottage' in kq4_003_fountain_pool → kq4_004_ogres_cottage [Ogre's Cottage] (click at: 1874, 714)
+  2. Click 'kq4_010_forest_path' in kq4_004_ogres_cottage → kq4_010_forest_path [Forest Path] (click at: 1042, 1078)
+  3. Click 'kq4_011_enchanted_grove' in kq4_010_forest_path → kq4_011_enchanted_grove [Enchanted Grove] (click at: 1898, 610)
+```
+
+This will tell you which set pieces to click on to get there. Specifically, this is suggesting that you use the walk interaction with kq4_004_ogres_cottage. This can be done using the mcp server for godot, and using the eval tool.
+
+Here's how to proceed.
+
+1. start the game (godot --path . &)
+
+   ```bash
+   # Wait for "McpInteractionServer: Listening on 127.0.0.1:9090" in console
+   ```
+
+2. Verify current room matches the starting point
+
+3. For each step, find TransitionPiece coordinates at runtime via GDScript eval
+
+4. Use the `func mock_interact(action = 0) -> void` on setpiece using the gdscript eval
+
+5. Poll until room changes to expected destination
+
+6. Verify final arrival
+
+## More detailed
+
+When implementing navigation step by step through MCP commands:
+
+### Starting the game:
+
+```bash
+godot --path . &
+# Wait for "McpInteractionServer: Listening on 127.0.0.1:9090" in console
+```
+
+### Then verify the connection:
+
+Send `{"command": "get_scene_tree"}` via TCP to verify MCP responds. The response will show the full node hierarchy including `Node2D/SceneViewport/background`.
+
+### Discover current room's exits
+
+```json
+{"command": "find_nodes_by_class", "params": {"class_name": "TransitionPiece"}}
+```
+
+Returns all TransitionPieces in the active scene with `.name`, `.label`, `.target` properties.
+
+For rooms without scripts, identify via transition piece labels or target UIDs cross-referenced with `scripts/build_room_graph.py --room <name>` output.
+
+### Simulate interactions
+
+Use eval to find the centroid of a TransitionPiece's polygon in viewport space:
+
+```json
+{
+  "command": "eval",
+  "params": {
+    "code": " get_tree().root.get_node_or_null('Node2D/SceneViewport/background/kq4_010_forest_path').mock_interaction(0)"
+  }
+}
+```
+
+Interactions match ActionState.Action (LOOK/WALK/ITEM/TALK)
+
+### Waiting after interaction
+
+```json
+{"command": "wait", "params": {"frames": 60}}
+```
+
+Transition animation takes \~1-2 seconds (fade-out + scene swap + fade-in). Wait 30+ frames before checking room change.
+
+## Room Graph Structure
+
+The graph currently has:
+
+- **96 rooms** across 23 connected components
+- Largest component: 36 rooms (starting from room 3 Fountain Pool)
+- Second largest: 17 rooms (room 1 Beach area)
+- Some rooms are fully disconnected (not all transitions wired bidirectionally yet)
+
+Use `python scripts/build_room_graph.py --room <name>` to check a room's available exits.
+
+## Common Issues
+
+| Problem | Diagnosis | Fix |
+| --- | --- | --- |
+| "No path" between expected connected rooms | Room has no matching .uid file or transition pieces not wired bidirectionally | Check `build_room_graph.py` output for which component each room belongs to; verify the target room's `.tscn` has correct UID and exit nodes |
+| MCP "Server busy" error during navigation | Previous command hasn't completed (30s timeout on server) | Tool handles automatic retry with exponential backoff. If persistent, restart game. |
+| Click lands outside polygon → transition doesn't trigger | Scale transform not applied to coordinates | Use runtime eval (not offline centroid). The `--navigate` flag uses MCP eval which reads actual node transforms. |
+| "Room not found in graph" | Room name mismatch — must use exact `.tscn` filename stem | Run `python scripts/build_room_graph.py` to see available room names |
+| "Expected X but game reports Y" during --navigate | Game is on different room than specified | Restart at correct room, or adjust --from flag. Check current room name via MCP eval. |
+
+## API Reference
+
+### build_room_graph.py
+
+```python
+from build_room_graph import build_graph, find_path, NavigationStep
+
+graph = build_graph(scenes_dir)            # RoomInfo dict keyed by room name
+steps = find_path(graph, "kq4_003_fountain_pool", "kq4_011_enchanted_grove")  # List[NavigationStep] or None
+step.from_room       # Navigation source room name
+step.exit_node_name  # TransitionPiece node to click
+step.to_room         # Destination room name
+step.label           # Human-readable label
+step.viewport_centroid()  # (x, y) tuple — polygon center in viewport coords
+```
+
+### kq4_room_navigator.py CLI
+
+```bash
+python tools/kq4_room_navigator.py [--from ROOM] [--to ROOM]  [summary]
+```
+
+## Key Files
+
+| File | Purpose |
+| --- | --- |
+| `tools/kq4_room_navigator.py` | CLI combining graph + BFS + MCP navigation |
+| `scripts/build_room_graph.py` | Room adjacency graph builder + BFS pathfinding |
+| `scripts/check_transitions.py` | Existing transition validation (related) |
+| `TransitionPiece.gd` | TransitionPiece node class (class_name TransitionPiece) |
+| `SetPiece_.gd` | Base interactive polygon class (class_name SetPiece) |
+|  |  |