notid/ai-game-2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

progress

Browse Source
This commit is contained in:
Bryce
2026-02-21 12:18:48 -08:00
parent ff6d30259b
commit d6b36d1f13
97 changed files with 2329 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
.opencode/skills/kq4-exit-checker/SKILL.md Normal file
View File

@@ -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

77
.opencode/skills/kq4-room-creator/SKILL.md
View File

@@ -47,20 +47,30 @@ Reference the template import file, remember to use create_uid.py to create a ui
### Step 5: Update .tscn File - Transition Pieces
When adding a transition piece to the CURRENT room that leads to a DESTINATION room:
## CRITICAL: Transition Naming Convention
- **Node name**: The node name should match the destination room name (e.g., `kq4_016_graveyard`)
- **target**: The SCENE UID of the destination room (from the destination's .tscn file)
- **appear_at_node**: The NAME of the transition node in the DESTINATION room that leads BACK to the current room. This is almost always the name of the current room, as it it is saying which exit in the destination room to transition move the player to.
- **label**: Human-readable name for the destination (e.g., "Graveyard")
### Node Naming Rule
**ALWAYS name transition nodes after their DESTINATION room, NEVER use generic directional names.**
Example - Adding a south exit from room 010 to room 016:
| CORRECT | WRONG |
|---------|-------|
| `kq4_016_graveyard` | `north_exit` |
| `kq4_003_fountain_pool` | `south_exit` |
| `kq4_010_forest_path` | `east_exit` |
| `kq4_009_shady_wooded_area` | `west_exit` |
### appear_at_node Rule
The `appear_at_node` should be the name of the transition node in the DESTINATION room that leads back to the CURRENT room. Following the naming convention, this is always the current room's name.
### Example - Adding a south exit from room 010 to room 016:
In Room 010 (`kq4_010_forest_path.tscn`):
```gdscript
[node name="kq4_016_graveyard" parent="." instance=ExtResource("4_abc")]
position = Vector2(910, 542)
polygon = PackedVector2Array(-108, 454, -87, 649, 376, 658, 348, 381)
appear_at_node = "kq4_010_forest_path" # Name of transition in ROOM 016 that goes back to 010
target = "uid://621uqunr9pm" # Scene UID of room 016
appear_at_node = "kq4_010_forest_path" # This is the CURRENT room's name
target = "uid://27b2k6gky3afg" # Scene UID of destination room 016
label = "Graveyard"
[node name="entrance" parent="kq4_016_graveyard" index="0"]
@@ -68,40 +78,27 @@ position = Vector2(118, 514)
[node name="exit" parent="kq4_016_graveyard" index="1"]
position = Vector2(151, 615)
```
Then add the signal connection in the current room:
```gdscript
[connection signal="interacted" from="kq4_016_graveyard" to="." method="_on_graveyard_interacted"]
```
And add the handler in the current room's .gd file:
Then add the handler in Room 010's .gd file:
```gdscript
func _on_graveyard_interacted() -> void:
$kq4_016_graveyard.default_script(self)
$kq4_016_graveyard.default_script(self)
```
### Step 6: Update .gd File
Remove template functions and add only handlers for connected rooms:
```gdscript
extends Scene
### Step 6: Update the Destination Room (Bidirectional Transitions)
**Every transition MUST have a corresponding return transition in the destination room.**
func _on_forest_path_interacted() -> void:
$kq4_010_forest_path.default_script(self)
```
### Step 7: Update the Destination Room
For each exit you add, you need to add a corresponding transition in the DESTINATION room that leads back to the current room.
Example - In room 016 (Graveyard), add north exit back to room 010:
In Room 016 (`kq4_016_graveyard.tscn`), add the return transition:
```gdscript
[node name="kq4_010_forest_path" parent="." instance=ExtResource("4_abc")]
position = Vector2(910, -213)
polygon = PackedVector2Array(-108, 454, -87, 649, 376, 658, 348, 381)
appear_at_node = "kq4_010_forest_path" # Name of THIS transition (room 016's exit to 010)
target = "uid://bxsxv6esxljit" # Scene UID of room 010 (the room we're going TO)
appear_at_node = "kq4_016_graveyard" # This is the CURRENT room's name (016)
target = "uid://3ujj97iw54vo5" # Scene UID of destination room 010
label = "Forest Path"
[node name="entrance" parent="kq4_010_forest_path" index="0"]
@@ -113,19 +110,31 @@ position = Vector2(174, 519)
[connection signal="interacted" from="kq4_010_forest_path" to="." method="_on_forest_path_interacted"]
```
Then add the handler in room 016's .gd file:
Then add the handler in Room 016's .gd file:
```gdscript
func _on_forest_path_interacted() -> void:
$kq4_010_forest_path.default_script(self)
$kq4_010_forest_path.default_script(self)
```
### Summary: target vs appear_at_node
### Step 7: Run the Exit Checker Skill
Run the exit checker skill on the new room, as well as all rooms that you wired up to the new room.
| Field | Value | Meaning |
## Quick Reference: Transition Fields
| Field | Value | Example |
|-------|-------|---------|
| `target` | Scene UID of destination room | Which scene to load |
| `appear_at_node` | Node name of exit in destination room | Which transition in that scene should appear at
| Node name | Destination room name | `kq4_016_graveyard` |
| `target` | Scene UID of destination | `uid://27b2k6gky3afg` |
| `appear_at_node` | CURRENT room name | `kq4_010_forest_path` |
| `label` | Human-readable destination name | `Graveyard` |
## Common Mistakes to Avoid
1. **Generic node names**: Never use `north_exit`, `south_exit`, etc.
2. **Wrong appear_at_node**: Should be the CURRENT room name, not the destination
3. **Missing return transition**: Always add the bidirectional transition
4. **Duplicate nodes**: Never have two transitions with the same node name
5. **Wrong target UID**: Always verify the UID matches the destination scene
## Room Number Mapping
Reference the spec for cardinal direction matches