# ralpha-ue5

**Kitchen Sink Starter Project** - Comprehensive UE5 asset library for AI-controlled rendering.

## Repository Architecture

This project is split across two repositories:

| Repository | Purpose | Storage |
|------------|---------|---------|
| **ralpha** | Code: plugin, API, website, Redis, Supabase | Regular Git |
| **ralpha-ue5** | Assets: UE5 maps, meshes, textures, MetaHumans | Git LFS |

The split keeps the code repository fast and lean (~50MB) while the asset repository can grow to 50-100GB with full LFS support.

## Design Philosophy

> "Any missing element takes hours to find, build, and refine."

This project prioritizes **breadth over perfection**. Every common object, environment, and scenario should have a ready-to-use representation. Speed of iteration matters more than photorealism of any single asset.

When matching a reference image, Claude should be able to:
1. Identify what's needed
2. Find it in the catalogue
3. Place and configure it
4. Capture screenshot

All within **seconds**, not minutes or hours.

## Structure

```
ralpha-ue5/
├── RalphaData/                 # Text files (NOT in LFS)
│   ├── catalogue.json          # Machine-readable asset index
│   ├── thumbnails/             # Small preview images
│   ├── recipes/                # Scene composition recipes
│   ├── presets/                # Lighting, post, scene presets
│   └── scripts/                # Asset management tools
│
├── Content/Ralpha/             # UE5 assets (IN LFS)
│   ├── Maps/                   # Template levels
│   ├── Assets/                 # Props, furniture, vehicles
│   ├── Materials/              # PBR materials
│   ├── HDRI/                   # Environment maps
│   └── LUTs/                   # Color grading
│
├── Plugins/                    # Symlink to ralpha/plugin
└── RalphaProject.uproject
```

## Template Maps

| Map | Purpose |
|-----|---------|
| `Template_Empty` | Bare minimum scene (sky, floor) |
| `Template_Studio` | Lighting rig, backdrop, camera |
| `Template_Outdoor` | Sky atmosphere, terrain base |
| `Template_Interior` | Room shell, interior lighting |

## Setup

1. Clone with LFS:
   ```bash
   git lfs install
   git clone https://github.com/yourusername/ralpha-ue5.git
   ```

2. Link the plugin:
   ```bash
   # macOS
   ln -s /path/to/ralpha/plugin Plugins/RalphaPlugin
   
   # Windows (as admin)
   mklink /J Plugins\RalphaPlugin E:\Github\ralpha\plugin
   ```

3. Open `RalphaProject.uproject` in UE5.4+

## MCP Commands

This project extends the Ralpha MCP protocol with:

```json
{"type":"get_version"}
{"type":"load_template","parameters":{"template":"Studio"}}
{"type":"drop_to_floor","parameters":{"actor_id":"Chair_01"}}
{"type":"snap_to_surface","parameters":{"actor_id":"Painting","surface":"wall"}}
{"type":"place_on","parameters":{"actor_id":"Vase","target":"Table_01"}}
{"type":"spawn_recipe","parameters":{"recipe":"living_room_modern"}}
{"type":"search_catalogue","parameters":{"query":"red chair"}}
```

## Asset Quality Standards

- Game-ready poly counts
- PBR materials (albedo, normal, roughness, metallic)
- Consistent scale (1 unit = 1 cm)
- Pivots at bottom center
- LODs for complex assets
- Collision for interactive items

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for asset import guidelines and naming conventions.