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