---
name: scene-breakdown
description: This skill should be used when analyzing game scene images create an OpenRaster image of the different layers. It guides the process of breaking down scenes into component layers suitable for game development, particularly for creating ORA files with separated foreground and background elements, which the player might appear in front of or behind.
---

# Scene Breakdown

The user will give you an image that they want to construct a layered .ora (OpenRaster) file based on. Or they'll have some kind of instruction on how they want to change an existing ora. You will use the skills required to implement those changes

## Overview

This skill guides the process of decomposing game room/scene images into component layers. The primary use case is identifying foreground elements that players can walk behind or in front of and organizing them into ORA files for further refinement by the user in art programs like Krita or Photoshop.

## When to Use This Skill

Use this skill when:
- Analyzing a new room/scene image to a layered ora format
- Creating layered ORA files from scene images
- Editing an existing ORA masks based on instructions from the user. Note that an ora-editing skill already exists for making the edits to existing files with specific images already prepared. This scene-breakdown skill is for when new masks or alterations need to be created, and will use the ora-editing skill to make those changes.

## Workflow

### Step 1: Analyze the Scene Image

First, examine the scene image to identify all elements. You should ask the @image-expert agent to do this, giving it the filename to read:

1. **Foreground elements** - Objects closest to camera that would obscure player. Most of the time foreground elements should be put together if they overlap one another. Examples would include:
   - Large trees extending into frame
   - Foreground framing, like in a room, sometimes the foreground is all black
   - Foreground bushes and plants
   - Building overhangs and architectural features
   - Rocks and boulders in immediate foreground

If these objects are overlapped and there isn't a way for the player to pass between
them, go ahead and group them together. For example, a tree's base may also be right next
to a bush in the foreground, and the player will always appear behind both. In that case,
just put them on the same layer. 

2. **Mid-ground elements** - Objects at middle depth that would obscure a player:
   - Smaller vegetation
   - Medium-sized rocks
   - Furniture or other items in a room

3. **Background elements** - Distant objects that serve as backdrop:
   - Sky and distant landscape
   - Background trees and terrain
   - Building walls and main structures


### Step 2: Document Walk-Behind Elements

For each foreground/mid-ground element identified, note:
- Element name (descriptive, snake_case)
- Approximate location in scene - don't group them together unless they are roughly
  in the same location on the screen (e.g., left hand side)
- Separate out interactable elements that a player might manipulate, but 
  not different elements. For example, A chimney, windows, roof should just go with a house.
  A door should be its own element.
- Reason for walk-behind status (e.g., "foreground tree", "path-side bush")
- Type: foreground (full occlusion) or mid-ground (partial occlusion)

### Step 3: Create Alpha Masks

Use the alpha-mask-creator skill to create a new mask. The user may ask for a certain number of variations (default 2). Check that the mask properly isolates the element. In those case
just use the skill multiple times and it will create a different variation of the mask. Always do these one at a time, because the system might get overwhelmed if they are done in parallel.

### Step 4: Create ORA File

Use the ora-editing skill to create a layerd ORA with all of the elements that were created.

Use the ora-editing skill to summarize the layer structure for the user

## Example: Ogre's Cottage Breakdown

**Scene**: `caption_1_454377357_generated.png`

**Walk-Behind Elements Identified**:
1. **pine_tree_left** - Large pine on left edge (foreground)
2. **bushes_left** - Bushes in bottom left (foreground, grouped with the tree)
3. **small_tree** - Evergreen near cottage (mid-ground)
4. **rock_left** - Rock near path entrance (mid-ground)
5. **rock_right** - Rock in front of cottage (mid-ground)
6. **wood_stack** - Chopped firewood (mid-ground)
7. **cottage** - Main element in the scene (mid-ground)
8. **roof_overhang** - Thatched roof extension (mid-ground, should be grouped with the cottage)
9. **chimney** - Stone chimney (mid-ground, should be grouped with the cottage)
10. **wood_shed** - Shed extension (mid-ground)

**Result**: ORA file with 10 groups, each containing 2 variants with different seeds, plus base_scene layer.

## Best Practices

- **Element naming**: Use descriptive snake_case names (e.g., `pine_tree_left`, `rock_front_right`)
- **Variant count**: Always create 2 variants per element for flexibility
- **Mask quality**: Verify masks properly isolate elements without artifacts
- **Layer organization**: Group related elements (e.g., all foreground vegetation together)
- **File locations**: Save masks to `tmp/` directory, final ORA to scene folder

## Resources

This skill leverages existing project tools, but the main skills (ora-editing, alpha-mask-creator)  should be used:
- `tools/ora_edit.py` - ORA file creation and manipulation
- `tools/extract_mask.py` - AI-powered alpha mask generation
- `tools/draw_polygon.py` - Polygon outline drawing
- `tools/mask_to_polygon.py` - Collision shape generation
