178 lines
7.0 KiB
Markdown
178 lines
7.0 KiB
Markdown
---
|
|
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
|