---
name: kq4-exit-checker
description: Validates that all transition pieces in a KQ4 room are correctly configured. Checks that target UIDs are valid and appear_at_node values exist in destination scenes.
---

# KQ4 Exit Checker

## Overview
This skill validates that all transition pieces in a room are correctly configured. A transition is valid if:
1. The `target` field contains the correct UID of the destination scene
2. The `appear_at_node` field matches a node name in the destination scene
3. Node names follow the naming convention (destination room name, not generic)
4. A return transition exists in the destination room (bidirectional)

## When to Use
Use this skill when you need to verify that room transitions are properly wired up. Most commonly used after creating new rooms or modifying existing ones.

## How to Use

### Step 1: Run the Skill
When you invoke this skill, specify the room number (e.g., "9", "009", or "kq4_009_shady_wooded_area").
Begin by running python ./scripts/check_transitions.py, which will show each room's transitions


The skill will:
1. Load the specified room's .tscn file
2. Parse all TransitionPiece nodes
3. For each transition, verify:
   - The `target` UID exists and points to the correct scene
   - The `appear_at_node` value matches a node in the target scene
   - The node name follows the naming convention
   - A return transition exists in the destination room
   - The room actually goes to the correct room specified in the room's spec (./kq4-sierra-decompile/rooms/)

### Step 2: Review Results

The skill outputs:
- **Valid transitions**: Confirmed working connections
- **Invalid transitions**: Issues found with target UIDs or appear_at_node names
- **Naming violations**: Generic names like `north_exit`, `south_exit`, etc.
- **Missing destinations**: Transitions pointing to non-existent rooms
- **Missing return transitions**: Destination room lacks transition back to source
- **Duplicate nodes**: Multiple transitions with the same name

## Validation Rules

### Node Naming Convention (CRITICAL)
Transition node names MUST follow this convention:
- **CORRECT**: Name the node after the destination room (e.g., `kq4_001_beach`, `kq4_025_beach_at_river_delta`)
- **WRONG**: Generic directional names (e.g., `north_exit`, `south_exit`, `east_exit`, `west_exit`, `exit_1`)

This makes the scene self-documenting and ensures consistent `appear_at_node` references.

### Target UID Check
- The `target` field must contain a valid UID that matches an existing scene's UID
- The UID is found in the scene's `.tscn` file header: `[gd_scene format=3 uid="uid://XXXXX"]`

### appear_at_node Check
- The `appear_at_node` field must match a node name in the destination scene
- Following the naming convention, this is typically the name of the CURRENT room
- Example: If Room 001 has `kq4_025_beach_at_river_delta` → Room 025, then `appear_at_node = "kq4_001_beach"` (because Room 025 should have a node named `kq4_001_beach` that leads back)

### Bidirectional Check (CRITICAL)
Every transition MUST have a corresponding return transition in the destination room.

**The Problem**: If Room A has a transition to Room B, but Room B doesn't have a transition back to Room A, the game will crash with:
```
Node not found: "kq4_A_name/exit" (relative to "background")
```

**How to Check**:
1. For each transition in the current room, note:
   - Source room name (e.g., `kq4_003_fountain_pool`)
   - Transition node name (e.g., `kq4_010_forest_path`)
   - Destination scene UID

2. Load the destination scene and search for a node with name = source room name:
   ```gdscript
   # In destination room, look for:
   [node name="kq4_003_fountain_pool" parent="." instance=ExtResource("...")]
   ```

3. If NOT FOUND, this is a CRITICAL ERROR - the transition will crash the game.

**Example Failure**:
```
Room 003 (Fountain Pool):
  Transition: kq4_010_forest_path
    appear_at_node = "kq4_003_fountain_pool"
    target = "uid://3ujj97iw54vo5" (room 010)

Checking Room 010 (Forest Path)...
  ERROR: Missing return transition!
  Room 010 does NOT have a node named "kq4_003_fountain_pool"
  This will cause: Node not found: "kq4_003_fountain_pool/exit"
```

**Required Fix**: Add the missing transition to Room 010:
```gdscript
[node name="kq4_003_fountain_pool" parent="." instance=ExtResource("4_abc")]
appear_at_node = "kq4_010_forest_path"
target = "uid://151dbn9bybiwx"
label = "Fountain Pool"
```

### Script Check
- Make sure that the signals are wired up to real functions for the transition pieces
- Make sure that the script references nodes that are actually in the scene tree

## Example Output

```
Checking exits for Room 3 (Fountain Pool)...

Transition: kq4_002_meadow
  target: uid://1489d4oh9twtu ✓
  appear_at_node: kq4_003_fountain_pool
  Checking destination scene (Room 2)...
    Node kq4_003_fountain_pool found ✓

Transition: kq4_010_forest_path
  target: uid://3ujj97iw54vo5 ✓
  appear_at_node: kq4_003_fountain_pool
  Checking destination scene (Room 10)...
    ERROR: Node "kq4_003_fountain_pool" NOT FOUND in destination!
    This will cause crash: Node not found: "kq4_003_fountain_pool/exit"
    FIX: Add transition node "kq4_003_fountain_pool" to Room 10

ERROR: Duplicate node "kq4_010_forest_path" found at lines 54 and 67!
ERROR: Generic node name "west_exit" should be renamed to destination room name!

Summary: 5 transitions checked, 3 errors found
```

## Technical Details

### Finding Scene UIDs
Scene UIDs are stored in `.uid` files or in the .tscn file header:
```bash
# Method 1: Read .uid file
cat scenes/kq4_009_shady_wooded_area/kq4_009_shady_wooded_area.tscn.uid

# Method 2: Parse .tscn header
head -1 scenes/kq4_009_shady_wooded_area/kq4_009_shady_wooded_area.tscn
# Output: [gd_scene format=3 uid="uid://1hkplw2a78b1y"]
```

### Finding Node Names in Scene
Node names are the `name=` attributes in the .tscn file:
```gdscript
[node name="kq4_003_fountain_pool" parent="." instance=ExtResource("4_abc")]
```

### Finding a Specific Node in a Scene
```bash
grep '\[node name="kq4_003_fountain_pool"' scenes/kq4_010_forest_path/kq4_010_forest_path.tscn
```

## Common Issues

1. **Missing return transition**: Destination room lacks a transition back to source room - CAUSES CRASH
2. **Generic node names**: Using `north_exit`, `south_exit`, etc. instead of destination room names
3. **appear_at_node mismatch**: The node name doesn't exist in the destination scene
4. **Missing target UID**: The target UID doesn't match any existing scene
5. **Duplicate node names**: Multiple transitions with the same name in one scene
6. **Bad scripts**: Transition script referencing non-existent nodes

## Checklist for Each Transition

For each transition in Room A going to Room B:
- [ ] Node name = `kq4_B_name` (destination room name)
- [ ] `target` = valid UID of Room B's scene
- [ ] `appear_at_node` = `kq4_A_name` (current room name)
- [ ] Room B has a node named `kq4_A_name`
- [ ] That node in Room B has `appear_at_node = "kq4_B_name"`
- [ ] Signal connection exists in .tscn
- [ ] Handler function exists in .gd file