5.9 KiB

Raw Blame History

Ralpha UE5 - Kitchen Sink Asset Project

Comprehensive UE5 asset library and scene templates for AI-controlled rendering with Ralpha.

Quick Start

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

{
  "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:

{
  "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:

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

For full metadata extraction (requires UE Editor):

python RalphaData/scripts/generate_catalogue.py --project Ralpha.uproject --ue-path /path/to/UnrealEditor

License Policy

See 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

ralpha - Main tooling, plugin, API
ralpha-ue5-metahumans - MetaHuman characters (optional)

Contributing

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

5.9 KiB Raw Blame History