106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# 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.
|