progress

.opencode/skills/alpha-mask-creator/SKILL.md

@@ -8,6 +8,9 @@ This skill creates alpha masks from images based on user requests. Use this when
 
 ## Workflow
 
+### 0. Extract layer (conditional)
+If the user provided a layer name from an ora file, you should use the ora-editing skill to extract a png of that layer. First use the inspect to list the layers, then use the extract.
+
 ### 1. Draw Polygon Outline
 Use the `polygon-drawer` skill to draw a polygon outline around the identified object. Save the output to `./tmp/` with a sensible filename:
 - Format: `<original_name>.<object>.png`
@@ -36,6 +39,9 @@ Tell the user:
 - Location of the mask: `./tmp/<original_name>.<object>.mask.png`
 - Confirm the mask quality is acceptable
 
+### 6. Integrate into existing ora file
+If the user asked to create an alpha mask for a layer from an ora file, offer to add the masked element to the ora file, using the ora-editing skill.
+
 ## Naming Conventions
 
 | User Request | Original File | Output Files |

.opencode/skills/ora-editing/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: ora-editing
+description: Creates and edits OpenRaster (ORA) files for game asset management using ora_edit.py. Use when creating layered game assets, masking entities, extracting layers as PNGs, composing scenes with multiple interactive elements, or managing game graphics with alpha masks.
+---
+
+# ORA Editing for Game Assets
+
+Manage layered game assets using OpenRaster format. Create ORA files from PNGs, mask entities for interactive objects, extract layers as PNGs, and inspect asset structure.
+
+## Quick Start
+
+Create a layered asset from a scene:
+
+```bash
+# Create ORA from scene
+python3 tools/ora_edit.py create scene.png scene.ora --layer-name "room"
+
+# Add masked interactive elements
+python3 tools/ora_edit.py mask_element scene.ora --mask door_mask.png --entity "door"
+python3 tools/ora_edit.py mask_element scene.ora --mask chest_mask.png --entity "chest"
+
+# Check structure
+python3 tools/ora_edit.py inspect scene.ora
+```
+
+## Commands
+
+### create
+
+Create an ORA file from a PNG image.
+
+```bash
+python3 tools/ora_edit.py create <input.png> [output.ora] [--layer-name NAME]
+```
+
+**Examples:**
+
+```bash
+# Create with default "base" layer
+python3 tools/ora_edit.py create background.png room.ora
+
+# Create with custom layer name
+python3 tools/ora_edit.py create forest.png forest.ora --layer-name "trees"
+```
+
+### mask_element
+
+Create a masked layer for an entity using a black-and-white mask.
+
+```bash
+python3 tools/ora_edit.py mask_element <input> --mask <mask.png> --entity <name> [--layer LAYER] [--output OUTPUT]
+```
+
+**Examples:**
+
+```bash
+# Mask using default "base" layer
+python3 tools/ora_edit.py mask_element room.ora --mask door_alpha.png --entity "door"
+
+# Specify source layer
+python3 tools/ora_edit.py mask_element room.ora --mask window_alpha.png --entity "window" --layer "room"
+
+# Chain PNG → ORA conversion with masking
+python3 tools/ora_edit.py mask_element scene.png --mask tree_mask.png --entity "tree" --output composed.ora
+```
+
+**Layer naming:** Entities get auto-incremented names: `door_0`, `door_1`, `door_2`...
+
+### inspect
+
+Display the structure of an ORA file.
+
+```bash
+python3 tools/ora_edit.py inspect <ora_file>
+```
+
+### extract_png
+
+Extract a layer from an ORA file as a PNG image.
+
+```bash
+python3 tools/ora_edit.py extract_png <ora_file> --layer <layer_name> [--output <output.png>]
+```
+
+**Examples:**
+
+```bash
+# Extract layer with default output name
+python3 tools/ora_edit.py extract_png scene.ora --layer door_0
+
+# Extract with custom output name
+python3 tools/ora_edit.py extract_png scene.ora --layer background --output bg.png
+
+# Extract multiple layers for use in Godot
+python3 tools/ora_edit.py extract_png character.ora --layer arm_0 --output arm.png
+python3 tools/ora_edit.py extract_png character.ora --layer head_0 --output head.png
+```
+
+## Workflows
+
+### Creating Interactive Scene Assets
+
+Build a scene with multiple interactive elements:
+
+```bash
+# 1. Create base scene
+python3 tools/ora_edit.py create room_base.png room.ora --layer-name "background"
+
+# 2. Add interactive elements
+python3 tools/ora_edit.py mask_element room.ora --mask door_closed.png --entity "door" --layer "background"
+python3 tools/ora_edit.py mask_element room.ora --mask chest_closed.png --entity "chest" --layer "background"
+python3 tools/ora_edit.py mask_element room.ora --mask window_day.png --entity "window" --layer "background"
+
+# 3. Verify structure
+python3 tools/ora_edit.py inspect room.ora
+```
+
+**Result:**
+```
+📁 Group: door
+   └─ door_0
+📁 Group: chest
+   └─ chest_0
+📁 Group: window
+   └─ window_0
+🖼️  Base: background
+```
+
+
+### AI-Assisted Masking Workflow
+
+Combine with AI mask extraction:
+1. Use the alpha-mask-creator skill to create an alpha mask
+
+```bash
+
+# 2. Apply to ORA
+python3 tools/ora_edit.py mask_element scene.ora --mask <provided mask> --entity "door"
+
+# 3. Verify
+python3 tools/ora_edit.py inspect scene.ora
+```
+
+## Asset Structure Guidelines
+
+**Layer Organization:**
+- Entity groups appear first (toggleable in GIMP/Krita)
+- Base layers at the bottom
+- Each entity group contains numbered variants
+
+**Naming Conventions:**
+- Use descriptive entity names: `door`, `chest`, `magic_potion`
+- Layer variants auto-number: `door_0`, `door_1`
+- Base layer should describe the content: `background`, `room`, `forest`
+
+**Mask Requirements:**
+- Grayscale or RGB/RGBA accepted
+- White = opaque, Black = transparent
+- Partial transparency supported
+
+## Common Patterns
+
+### Pattern: Scene Composition
+
+Multiple interactive objects in one scene:
+
+```bash
+python3 tools/ora_edit.py create bg.png scene.ora --layer-name "room"
+python3 tools/ora_edit.py mask_element scene.ora --mask obj1.png --entity "door"
+python3 tools/ora_edit.py mask_element scene.ora --mask obj2.png --entity "key"
+python3 tools/ora_edit.py mask_element scene.ora --mask obj3.png --entity "chest"
+```
+
+### Pattern: State Variants
+
+Multiple states for the same object:
+
+```bash
+# Closed door
+python3 tools/ora_edit.py mask_element scene.ora --mask door_closed.png --entity "door"
+
+# Open door (creates door_1)
+python3 tools/ora_edit.py mask_element scene.ora --mask door_open.png --entity "door"
+```
+
+### Pattern: Inspection Before Export
+
+Always verify before using in game:
+
+```bash
+python3 tools/ora_edit.py inspect scene.ora
+# Confirm structure matches Godot scene requirements
+```
+
+### Pattern: Extracting Layers for Game Use
+
+Export individual layers for use as Godot sprites:
+
+```bash
+# Extract all interactive elements
+python3 tools/ora_edit.py extract_png scene.ora --layer door_0 --output door_sprite.png
+python3 tools/ora_edit.py extract_png scene.ora --layer chest_0 --output chest_sprite.png
+
+# Extract base layer for background
+python3 tools/ora_edit.py extract_png scene.ora --layer background --output room_bg.png
+```
+
+## Integration with Godot
+
+After creating ORA assets:
+
+1. Export layers using `extract_png`:
+   ```bash
+   python3 tools/ora_edit.py extract_png scene.ora --layer door_0 --output door.png
+   python3 tools/ora_edit.py extract_png scene.ora --layer background --output bg.png
+   ```
+2. Use in Godot scenes as Sprite2D textures
+3. Use `mask_to_polygon.py` to generate collision polygons:
+   ```bash
+   python3 tools/mask_to_polygon.py door_mask.png --output door_collision.tres
+   ```
+
+## Error Handling
+
+**Missing layer:**
+```bash
+$ python3 tools/ora_edit.py mask_element scene.ora --mask x.png --entity door --layer "missing"
+Error: Layer 'missing' not found in ORA file
+Available layers:
+  - base
+  - door_0
+```
+
+**Fix:** Use one of the listed layers with `--layer`
+
+**Invalid ORA:**
+```bash
+$ python3 tools/ora_edit.py inspect corrupted.ora
+Error: Invalid ORA file: corrupted.ora
+```
+
+**Fix:** Recreate the ORA using `create` command
+
+## Tips
+
+- **Preview first:** Use `inspect` to check existing structure before adding elements
+- **Descriptive names:** Entity names appear in Godot, use clear identifiers
+- **Version control:** ORA files are binary; track source PNGs and masks separately
+- **Batch processing:** Chain commands in shell scripts for repetitive tasks
+
+## See Also
+
+- `extract_mask.py` - AI-powered mask generation
+- `mask_to_polygon.py` - Convert masks to Godot collision shapes
+- `ora_edit_README.md` - Full command documentation