# RalphaData - Kitchen Sink Asset Library

This directory contains the JSON data files that define all searchable assets, presets, and configurations for the Ralpha Kitchen Sink UE5 project.

## Directory Structure

```
RalphaData/
├── catalogue.json          # Main asset catalogue (250+ items)
├── hdris.json              # HDRI environment library (18 HDRIs)
├── luts.json               # Color LUT library (32 LUTs)
├── postprocess.json        # Post-processing presets (15 presets)
├── metahumans/
│   ├── registry.json       # MetaHuman character registry (20 characters)
│   ├── animations.json     # Animation library (32 animations)
│   ├── expressions.json    # Facial expression presets (16 expressions)
│   └── clothing.json       # Clothing preset library (8 presets)
└── README.md               # This file
```

## File Descriptions

### catalogue.json
The main asset catalogue containing 250+ props, furniture, vehicles, nature elements, and more.

**Categories:**
- Furniture (65+ items): Seating, tables, storage, bedroom
- Vehicles (40 items): Cars, motorcycles, bicycles, aircraft, watercraft, emergency
- Nature (30 items): Trees, plants, flowers, rocks, terrain
- Urban (21 items): Street furniture, signage, barriers, commercial
- Architecture (25 items): Walls, floors, doors, windows, stairs, columns
- Tools (13 items): Hand tools, power tools, garden tools
- Sports (15 items): Equipment, balls, furniture
- Animals (14 items): Pets, farm, wildlife
- Electronics, Decor, Equipment, Studio items

**Schema:**
```json
{
  "id": "unique_asset_id",
  "name": "Human Readable Name",
  "category": "Category/Subcategory",
  "tags": ["searchable", "tags"],
  "path": "/Game/Ralpha/Assets/Category/SM_AssetName",
  "dimensions": {"x": 100, "y": 100, "z": 100},
  "has_collision": true
}
```

### hdris.json
HDRI environment maps for image-based lighting.

**Categories:**
- Studio (4): Softbox, Hard Light, Natural, Gradient
- Outdoor (8): Clear Day, Overcast, Sunset, Night, Forest, Beach, Mountain, Desert
- Urban (6): City Day, City Night, Street, Parking, Office Interior, Home Interior

**Schema:**
```json
{
  "id": "HDRI_Category_Name",
  "name": "Display Name",
  "category": "Studio|Outdoor|Urban",
  "description": "Description of lighting quality",
  "path": "/Game/Ralpha/HDRI/Category/HDRI_Name",
  "resolution": "8K|4K",
  "dynamic_range": "High|Medium|Low",
  "sun_position": {"altitude": 60, "azimuth": 180},
  "tags": ["searchable", "tags"]
}
```

### luts.json
Color Look-Up Tables for color grading.

**Categories:**
- Base (2): Neutral, Rec.709
- Film (10): Kodak Portra, Ektar, Gold, Fuji Pro 400H, Velvia, Cinestill, Vision3
- Cinematic (1): Teal & Orange
- Vintage (5): Faded, Warm, Cool, 70s, Polaroid
- Black & White (5): Classic, High Contrast, Low Contrast, Noir, Sepia
- Creative (10): Cyberpunk, Vaporwave, Cross Process, Bleach Bypass, Horror, etc.

**Schema:**
```json
{
  "id": "LUT_Category_Name",
  "name": "Display Name",
  "category": "Base|Film|Vintage|Black & White|Creative",
  "description": "Description of the look",
  "path": "/Game/Ralpha/PostProcess/LUTs/LUT_Name",
  "tags": ["searchable", "tags"]
}
```

### postprocess.json
Post-processing presets with full parameter definitions.

**Presets:**
- Neutral, Filmic, Cinematic, High Contrast, Low Contrast
- Warm, Cool, Desaturated, Vibrant, Vintage
- Black & White, Noir, Bleach Bypass, Cross Process, HDR

**Schema:**
```json
{
  "id": "PP_PresetName",
  "name": "Display Name",
  "description": "Description",
  "use_case": "When to use this preset",
  "path": "/Game/Ralpha/PostProcess/Profiles/PP_Name",
  "settings": {
    "color_grading": {
      "temperature": 6500,
      "saturation": 1.0,
      "contrast": 1.0
    },
    "bloom": 0.0,
    "vignette": 0.0,
    "film_grain": 0.0
  },
  "tags": ["searchable", "tags"]
}
```

### metahumans/registry.json
Registry of 20 diverse MetaHuman characters.

**Demographics:**
- 10 Male, 10 Female
- Age ranges: 20s, 30s, 40s, 50s, 60s
- Ethnicities: Caucasian, African, East Asian, Hispanic, South Asian, Mixed

**Schema:**
```json
{
  "id": "MH_[M|F]_[Age]_[Ethnicity]",
  "name": "Character Name",
  "gender": "Male|Female",
  "age_range": "20s|30s|40s|50s|60s",
  "ethnicity": "Ethnicity",
  "description": "Character description",
  "blueprint_path": "/Game/Ralpha/MetaHumans/[Gender]/BP_...",
  "default_clothing": "Casual|Business",
  "available_clothing": ["Casual", "Business", "Athletic", "Evening", "Uniform"]
}
```

### metahumans/animations.json
32 animations for MetaHuman characters.

**Categories:**
- Idle (5): Standing Relaxed, Standing Formal, Sitting Chair, Sitting Sofa, Leaning Wall
- Pose (5): Portrait 3/4, Portrait Profile, Hands Pockets, Arms Crossed, Thinking
- Action (12): Walk, Run, Sit, Stand, Pick Up, Wave, Nod, Shake Head, Shrug, etc.
- Interaction (10): Type, Phone, Drink, Eat, Talk, Listen, Point, Handshake, Clap

**Schema:**
```json
{
  "id": "Animation_ID",
  "name": "Display Name",
  "category": "Idle|Pose|Action|Interaction",
  "description": "What the animation shows",
  "path": "/Game/Ralpha/Animations/Category/Anim_Name",
  "looping": true|false,
  "duration": 2.0
}
```

### metahumans/expressions.json
16 facial expression presets using ARKit morph targets.

**Expressions:**
Neutral, Happy, Sad, Angry, Surprised, Thinking, Laughing, Serious,
Confused, Disgusted, Fearful, Skeptical, Smirk, Determined, Wink, Sleepy

**Schema:**
```json
{
  "id": "ExpressionName",
  "name": "Display Name",
  "description": "What the expression conveys",
  "morph_targets": {
    "mouthSmile_L": 0.8,
    "mouthSmile_R": 0.8,
    "cheekSquint_L": 0.4
  }
}
```

### metahumans/clothing.json
8 clothing presets with gender-specific variants.

**Presets:**
Casual, Business, Athletic, Evening, Uniform, Medical, Swimwear, Winter

**Schema:**
```json
{
  "id": "PresetName",
  "name": "Display Name",
  "description": "Style description",
  "gender_variants": {
    "male": {
      "top_path": "/Game/Ralpha/MetaHumans/Clothing/Male/SK_...",
      "bottom_path": "/Game/...",
      "shoes_path": "/Game/...",
      "accessories": ["SK_Accessory1", "SK_Accessory2"]
    },
    "female": { ... }
  }
}
```

## MCP Commands

### Search Commands
```json
// Unified search across all catalogues
{"type": "search", "parameters": {"query": "red chair", "max_results": 50}}

// Search specific type
{"type": "search_by_type", "parameters": {"query": "sunset", "type": "hdri"}}

// List searchable types
{"type": "list_searchable_types"}

// Get all tags (optionally filtered by type)
{"type": "get_tags", "parameters": {"type": "asset"}}

// Get categories for a type
{"type": "get_categories", "parameters": {"type": "lut"}}
```

### Catalogue Commands
```json
// Search catalogue
{"type": "search_catalogue", "parameters": {"query": "modern sofa"}}

// Spawn asset
{"type": "spawn_catalogue_item", "parameters": {
  "id": "furniture_sofa_modern_3seat",
  "location": [0, 0, 0],
  "rotation": [0, 0, 0]
}}
```

### MetaHuman Commands
```json
// Spawn MetaHuman
{"type": "spawn_metahuman", "parameters": {
  "id": "MH_F_25_African",
  "location": [0, 200, 0],
  "clothing": "Business",
  "expression": "Happy"
}}

// Set expression
{"type": "set_expression", "parameters": {
  "actor_name": "MetaHuman_1",
  "expression": "Thinking"
}}

// Play animation
{"type": "play_animation", "parameters": {
  "actor_name": "MetaHuman_1",
  "animation": "Wave"
}}
```

### Post-Processing Commands
```json
// Apply post-process preset
{"type": "apply_post_preset", "parameters": {"preset": "PP_Cinematic"}}

// Set LUT
{"type": "set_lut", "parameters": {"lut": "LUT_Teal_Orange"}}

// Set HDRI
{"type": "set_hdri", "parameters": {"hdri": "HDRI_Studio_Softbox"}}
```

## Searchable Types

| Type | Count | Description |
|------|-------|-------------|
| asset | 250 | Props, furniture, vehicles, etc. |
| metahuman | 20 | Character presets |
| hdri | 18 | Environment lighting |
| lut | 32 | Color grading |
| postprocess | 15 | Post-processing presets |
| animation | 32 | Character animations |
| expression | 16 | Facial expressions |
| clothing | 8 | Clothing presets |

## Version History

- **v1.0** - Initial release with basic catalogue
- **v2.0** - Phase 5: Expanded to 250+ assets, added vehicles, nature, urban, architecture, tools, sports, animals
- **v2.1** - Phase 6: Added HDRIs, LUTs, post-processing presets, unified search system