prgores

.opencode/skills/setpiece-creator/SKILL.md

@@ -0,0 +1,163 @@
+---
+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.
+
+### 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/background.png \
+  /tmp/[entity]_mask.png
+```
+
+**Subject phrasing:** Use descriptive phrasing like "the door of the ogre's cottage" for better results.
+
+### 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