---
name: setpiece-creator
description: Create interactive SetPiece nodes for King's Quest IV rooms. This skill automates mask extraction, polygon generation, and scene wiring. Use when adding interactive objects (doors, items, characters, etc.) to room scenes. Takes an entity name and room, optionally a look description.
---

# SetPiece Creator

## Overview

Automate the creation of interactive SetPiece nodes for KQ4 room scenes. This skill handles mask extraction via ComfyUI, polygon resource generation, and scene file wiring.

## When to Use

Use this skill when:
- Adding interactive objects to a room (doors, windows, items, characters)
- Creating clickable areas with cursor-based interactions
- User requests like "Add a door to room 4" or "Create a setpiece for the fountain"

## Workflow

### 1. Identify Background Image

Find the room's `.tscn` file and locate the `bg` Sprite2D node:

```
[node name="bg" type="Sprite2D" parent="."]
scale = Vector2(0.783, 0.78)
texture = ExtResource("2_u8g8b")
```

The texture path references an ext_resource pointing to the background image. **Use this path for mask extraction, NOT pic_XXX_visual.png.** The .tscn references the AI-generated caption image which is what should be used.

### 2. Verify Entity Visibility

Use the `image-inspector` skill to confirm the entity is visible in the background image:

```bash
# Resize image to 1MP max
mkdir -p ./.tmp
magick "scenes/kq4_XXX_room/background.png" -resize '1000000@>' ./.tmp/resized.png
```

Then ask @image-expert: "Is a [entity] visible in this image?"

If **No**, report to user and stop.

### 3. Extract Mask

Use `tools/extract_mask.py` to generate the mask:

```bash
python tools/extract_mask.py "the [entity]" \
  scenes/kq4_XXX_room/caption_XXX_generated.png \
  /tmp/[entity]_mask.png
```

**Subject phrasing:** Use descriptive phrasing like "the door of the ogre's cottage" for better results.

**CRITICAL:** Always use the background image path from the .tscn file (e.g., `caption_3_840023845_generated.png`), NOT `pic_XXX_visual.png`. The .tscn shows which image is actually used in-game.

### 4. Generate Polygon Resource

Use `tools/mask_to_polygon.py` to create the .tres file:

```bash
python tools/mask_to_polygon.py /tmp/[entity]_mask.png \
  --output scenes/kq4_XXX_room/[entity]_polygon.tres \
  --target-points 8 \
  --preview /tmp/[entity]_preview.png
```

The script outputs the new UID. Note it for the next step.

### 5. Update Room .tscn

Add ext_resource entries for the polygon and SetPiece script:

```
[ext_resource type="Resource" uid="uid://NEWUID" path="res://scenes/kq4_XXX_room/[entity]_polygon.tres" id="N_entity"]
[ext_resource type="Script" uid="uid://bounwnqg34t5k" path="res://SetPiece_.gd" id="N_setpiece"]
```

Add the SetPiece node (match bg scale):

```
[node name="[entity]" type="Polygon2D" parent="." groups=["set-piece"]]
scale = Vector2(0.783, 0.78)
color = Color(0.5, 0.5, 0.5, 0.25)
polygon = PackedVector2Array(...)
script = ExtResource("N_setpiece")
label = "[Entity]"
points_resource = ExtResource("N_entity")
```

Add signal connection:

```
[connection signal="looked" from="[entity]" to="." method="_on_[entity]_looked"]
```

### 6. Update Room .gd Script

Add the signal handler:

```gdscript
func _on_[entity]_looked() -> void:
	start_main_script(ScriptBuilder.init(
		ScriptBuilder.say(ego, "[Look description]")
	).build(self, "_on_script_complete"))
```

## Key Details

### Scale Matching

The SetPiece `scale` must match the bg node's scale for the polygon to align correctly.

### Polygon Points

Copy the `points` from the generated .tres into the `polygon` field of the .tscn node. This provides a preview in the editor.

### Signal Precedence

- `interacted` signal takes precedence over cursor-specific signals
- If `interacted` is wired, it overrides `walked`/`looked`/`touched`/`talked`
- Default is to wire `looked` for examination

### Label Formatting

Use title case for the label: "Door", "Pool", "Forest Path"

## Common Patterns

### Door/Walkable Object

```
[connection signal="interacted" from="door" to="." method="_on_door_interacted"]
```

### Examinable Object (Default)

```
[connection signal="looked" from="[entity]" to="." method="_on_[entity]_looked"]
```

### Multi-Signal Object

```
[connection signal="looked" from="[entity]" to="." method="_on_[entity]_looked"]
[connection signal="touched" from="[entity]" to="." method="_on_[entity]_touched"]
```

## Example Usage

**User:** "Create a door for the ogre's cottage in room 4"

**Process:**
1. Find `scenes/kq4_004_ogres_cottage/kq4_004_ogres_cottage.tscn`
2. Identify bg texture: `caption_1_454377357_generated.png`
3. Verify door is visible via image-inspector
4. Extract mask: `python tools/extract_mask.py "the door of the ogre's cottage" ...`
5. Generate polygon: `python tools/mask_to_polygon.py ...`
6. Add SetPiece node with scale `Vector2(0.783, 0.78)`
7. Wire `looked` signal
8. Add look handler with description