ai-game-2/.opencode/skills/kq4-exit-checker/SKILL.md

name, description

name	description
kq4-exit-checker	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:

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

[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:

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

[node name="kq4_003_fountain_pool" parent="." instance=ExtResource("4_abc")]

Finding a Specific Node in a Scene

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