progress

.opencode/skills/kq4-exit-checker/SKILL.md

@@ -0,0 +1,173 @@
+---
+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").
+
+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
+
+### 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