ai-game-2/.opencode/skills/setpiece-creator/SKILL.md

name, description

name	description
setpiece-creator	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:

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

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:

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:

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