---

## 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) |
|  |  |