ai-game-2/.opencode/skills/ora-editing/SKILL.md

name, description

name	description
ora-editing	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:

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

python3 tools/ora_edit.py create <input.png> [output.ora] [--layer-name NAME]

Examples:

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

python3 tools/ora_edit.py mask_element <input> --mask <mask.png> --entity <name> [--layer LAYER] [--output OUTPUT]

Examples:

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

python3 tools/ora_edit.py inspect <ora_file>

extract_png

Extract a layer from an ORA file as a PNG image.

python3 tools/ora_edit.py extract_png <ora_file> --layer <layer_name> [--output <output.png>]

Examples:

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

# 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

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

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:

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

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:

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

   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:

   python3 tools/mask_to_polygon.py door_mask.png --output door_collision.tres
   

Error Handling

Missing layer:

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

$ 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