ralpha-assets/README.md

# Ralpha UE5 - Kitchen Sink Asset Project

Comprehensive UE5 asset library and scene templates for AI-controlled rendering with [Ralpha](https://github.com/jamestagg/ralpha).

## Quick Start

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

# Open in UE5.4+
# File > Open Project > ralpha-ue5/Ralpha.uproject
```

## Architecture

This repo contains **assets only**. The MCP plugin and tooling live in the main [ralpha](https://github.com/jamestagg/ralpha) repo.

```
ralpha-ue5/          <- You are here (assets, templates, presets)
    │
    └── Plugins/RalphaPlugin/  <- Symlink to ralpha/plugin
            │
            ├── MCP Server (port 30010)
            └── 69 Command Handlers

ralpha/              <- Main repo (tooling, API, frontend)
    │
    ├── plugin/      <- UE5 plugin source
    ├── ralpha-api/  <- Backend API
    └── frontend/    <- Web interface
```

## Repository Structure

```
ralpha-ue5/
├── RalphaData/                    # NOT in LFS - text/JSON files
│   ├── catalogue/
│   │   ├── catalogue.json         # Machine-readable asset index
│   │   └── catalogue.schema.json  # JSON schema
│   ├── thumbnails/                # Small preview images
│   ├── recipes/                   # Scene composition templates
│   │   ├── recipe.schema.json
│   │   ├── living_room_modern.json
│   │   ├── portrait_studio_white.json
│   │   └── office_corporate.json
│   ├── presets/
│   │   ├── lighting/              # Lighting configurations
│   │   ├── post/                  # Post-processing profiles
│   │   ├── scene/                 # Full scene configs
│   │   └── camera/                # Camera presets
│   └── scripts/
│       └── generate_catalogue.py  # Asset indexing tool
│
├── Content/                       # IN LFS - large binary files
│   └── Ralpha/
│       ├── Maps/                  # Template levels
│       │   ├── Template_Empty.umap
│       │   ├── Template_Studio.umap
│       │   ├── Template_Outdoor.umap
│       │   └── Template_Interior.umap
│       ├── Assets/                # Props, furniture, etc.
│       │   ├── Furniture/
│       │   ├── Electronics/
│       │   ├── Food/
│       │   ├── Vehicles/
│       │   ├── Nature/
│       │   └── ...
│       ├── Materials/
│       ├── HDRI/
│       └── LUTs/
│
└── Plugins/
    └── RalphaPlugin/              # Symlink to ralpha/plugin
```

## Key Concepts

### Template Maps vs Heavy Maps

Instead of 50+ bespoke maps, we use **4 templates** + **JSON presets**:

| Template | Use Case |
|----------|----------|
| `Template_Empty` | Bare minimum - sky + ground |
| `Template_Studio` | Portrait/product - cyclorama + lights |
| `Template_Outdoor` | Landscapes - terrain + atmosphere |
| `Template_Interior` | Rooms - walls + ceiling + basic lighting |

Scene variation comes from presets, not map duplication.

### Recipe System

Recipes define composite scenes that can be spawned instantly:

```json
{
  "recipe_id": "living_room_modern",
  "components": [
    {"asset": "sofa_modern_3seat", "position": "center"},
    {"asset": "coffee_table_rect", "position": "in_front_of:sofa"},
    {"asset": "tv_65inch", "position": "wall:opposite_sofa"}
  ],
  "lighting_preset": "Interior_Evening"
}
```

MCP command: `{"type":"spawn_recipe","parameters":{"recipe":"living_room_modern"}}`

### Asset Catalogue

All assets are indexed in `catalogue.json` for programmatic discovery:

```json
{
  "id": "sofa_modern_3seat",
  "name": "Modern 3-Seat Sofa",
  "category": "Furniture/Seating",
  "unreal_path": "/Game/Ralpha/Assets/Furniture/Seating/Sofa_Modern_3Seat",
  "tags": ["sofa", "couch", "seating", "modern", "living room"],
  "bounds": {"x": 220, "y": 90, "z": 85},
  "placement_modes": ["floor"]
}
```

MCP command: `{"type":"search_catalogue","parameters":{"query":"modern sofa"}}`

## MCP Commands

These commands interface with this asset library:

| Command | Description |
|---------|-------------|
| `load_template` | Load a base template map |
| `apply_scene_preset` | Apply lighting/post/camera preset |
| `spawn_recipe` | Spawn a full scene composition |
| `spawn_catalogue_item` | Spawn single asset from catalogue |
| `search_catalogue` | Search assets by tags/name |
| `get_version` | Get plugin + catalogue version |

## Asset Standards

All assets must meet these requirements:

- **Scale**: 1 unit = 1 cm
- **Pivot**: Bottom center (for floor items)
- **Collision**: Present for interactive items
- **LODs**: At least 2 levels for complex meshes
- **Materials**: PBR with proper slots
- **Naming**: `Category_Type_Variant` (e.g., `Sofa_Modern_Grey`)

## Regenerating Catalogue

After adding assets, regenerate the catalogue:

```bash
cd ralpha-ue5
python RalphaData/scripts/generate_catalogue.py --scan-only
```

For full metadata extraction (requires UE Editor):
```bash
python RalphaData/scripts/generate_catalogue.py --project Ralpha.uproject --ue-path /path/to/UnrealEditor
```

## License Policy

See [LICENSE_POLICY.md](LICENSE_POLICY.md) for asset provenance requirements.

- **CC0/Public Domain**: Preferred, no restrictions
- **CC-BY**: Allowed, attribution in catalogue
- **Megascans**: Allowed (free with UE)
- **Marketplace**: Allowed for purchased assets
- **Restricted**: Separate folder, excluded by default

## Related Repositories

- [ralpha](https://github.com/jamestagg/ralpha) - Main tooling, plugin, API
- [ralpha-ue5-metahumans](https://github.com/jamestagg/ralpha-ue5-metahumans) - MetaHuman characters (optional)

## Contributing

1. Import asset following standards above
2. Run `generate_catalogue.py`
3. Add to appropriate recipe if applicable
4. Submit PR with asset source/license info