---
name: kq4-room-creator
description: Create new King's Quest IV room scenes from the decompiled room specs. Handles template copying, visual image setup, transition wiring, and connecting to existing rooms.
---

# KQ4 Room Creator

## Overview
This skill automates the creation of new King's Quest IV rooms from the decompiled room specs.

## When to Use
Use this skill when you need to create a new game room scene. The skill will:
1. Copy the placeholder template
2. Set up cardinal exits based on room spec
3. Wire up connections to existing rooms
4. Copy the visual image from decompile
5. Run the exit checker skill

## How to Use

### Step 1: Get Room Spec
First, read the room specification from:
```
kq4-sierra-decompile/rooms/kq4-XXX-room-name/kq4-XXX-room-name.md
```

Look for the "Exits" section to determine which directions connect to which room numbers.

Example from room 010:
```
- **Exits**: North→4, South→16, East→11, West→9
```

### Step 2: Copy Template
```bash
cp -r scenes/kq4_placeholder_template scenes/kq4_XXX_room_name
mv scenes/kq4_XXX_room_name/kq4_placeholder_template.gd scenes/kq4_XXX_room_name/kq4_XXX_room_name.gd
mv scenes/kq4_XXX_room_name/kq4_placeholder_template.tscn scenes/kq4_XXX_room_name/kq4_XXX_room_name.tscn
```

### Step 3: Copy Visual Image
```bash
cp kq4-sierra-decompile/rooms/kq4-XXX-room-name/pic_XXX_visual.png scenes/kq4_XXX_room_name/
```

### Step 4: Create Import File
Reference the template import file, remember to use create_uid.py to create a uid

### Step 5: Update .tscn File - Transition Pieces

## CRITICAL: Transition Naming Convention

### Node Naming Rule
**ALWAYS name transition nodes after their DESTINATION room, NEVER use generic directional names.**

| 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"  # 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"]
position = Vector2(118, 514)

[node name="exit" parent="kq4_016_graveyard" index="1"]
position = Vector2(151, 615)

[connection signal="interacted" from="kq4_016_graveyard" to="." method="_on_graveyard_interacted"]
```

Then add the handler in Room 010's .gd file:
```gdscript
func _on_graveyard_interacted() -> void:
    $kq4_016_graveyard.default_script(self)
```

### Step 6: Update the Destination Room (Bidirectional Transitions)

**Every transition MUST have a corresponding return transition in the destination room.**

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_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"]
position = Vector2(133, 643)

[node name="exit" parent="kq4_010_forest_path" index="1"]
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:
```gdscript
func _on_forest_path_interacted() -> void:
    $kq4_010_forest_path.default_script(self)
```

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

## Quick Reference: Transition Fields

| Field | Value | Example |
|-------|-------|---------|
| Node name | Destination room name | `kq4_016_graveyard` |
| `target` | Scene UID of destination | `uid://27b2k6gky3afg` |
| `appear_at_node` | CURRENT room name, i.e., the player appears at the exit node | `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
6. **Connecting to open ocean**: The open ocean room is special and doesn't follow the typical rules. Ignore it

## Room Number Mapping
Reference the spec for cardinal direction matches

## Key Files
- Template: `scenes/kq4_placeholder_template/`
- Room specs: `kq4-sierra-decompile/rooms/kq4-XXX-room-name/`
- TransitionPiece: `TransitionPiece.tscn`
- Base Scene class: `Scene.gd`
