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