Ralpha Brain
Getting started with the Ralpha Brain
What the Brain is
The Ralpha Brain is an app that builds a scene in your open Unreal project from a text prompt or a reference image, then improves it over several iterations. It plans each change and scores each frame with Claude, through your own Claude Code sign-in.
The Ralpha Brain is free during early release. If we introduce paid plans later, we'll announce it at least 30 days in advance, and the version you've downloaded will keep working.
Requirements
- Unreal Engine 5.8 with the Ralpha plugin from Fab (free for individuals), enabled in the project you want to build in. The Brain needs plugin 1.2.0 or later. See the plugin page to install it.
- Claude Code, installed and signed in. The Brain runs on your own Claude subscription; it does not include a model or an account of its own.
- A Mac with Apple silicon, or a Windows 64-bit PC. There is no Linux build of the Brain.
Download and unzip
Download the zip for your computer from the download page. Each is just under 1 GB. Unzip it anywhere; inside is the ralpha-brain program (ralpha-brain.exe on Windows).
The Windows build is not code-signed yet, so Windows may warn about an unknown publisher. Choose More info, then Run anyway.
Mac
The Mac build is signed and notarized by Apple. Double-click the zip in Finder to unzip it.
Windows
The Windows build is not code-signed yet, so Windows does not know who published it and may warn you. What you see depends on your settings:
- Your browser may say the zip isn’t commonly downloaded. Choose to keep the file.
- When the program first runs, Microsoft Defender SmartScreen may show “Windows protected your PC” with the publisher as unknown. Select More info, then Run anyway.
To clear the warning for every file at once, right-click the zip before you unzip it, choose Properties, tick Unblock and select OK.
Set up
Open Terminal (Mac) or PowerShell (Windows) in the unzipped folder and run setup:
./ralpha-brain setup.\ralpha-brain.exe setupSetup does two things:
- It installs the Brain into
~/.ralpha(on Windows,.ralphain your user folder), whereralpha-brain updatekeeps it current. - It configures Claude Code, Claude Desktop and Cursor. In Claude Code it registers two servers for your user:
unreal, which is Unreal’s own MCP server athttp://127.0.0.1:30030/mcp, andralpha, which is the Brain. It never replaces anunrealentry you made yourself. If Claude Code is not signed in, it says so.
Restart Claude Code, Claude Desktop or Cursor afterwards so it picks up the change. Useful options:
--client claude-codeconfigures Claude Code only.--dry-runprints what setup would change without changing it.--native-portsets the port of Unreal’s MCP server, if you use one other than 30030.
From now on, run the installed copy: ~/.ralpha/current/ralpha-brain on a Mac, or ~\.ralpha\cache\v1.3.1\ralpha-brain.exe in PowerShell on Windows. The rest of this page writes it as ralpha-brain.
Check with doctor
Open your project in Unreal first, then run:
ralpha-brain doctorDoctor checks the Brain’s install, Unreal’s MCP server on port 30030, the Ralpha plugin on TCP port 30010 and its version, and Claude Code: that it is installed, signed in, and has the unreal and ralpha servers. Its checks only read, and change nothing in the editor. A healthy result ends with All checks passed:
Ralpha Brain — Doctor
Brain version ralpha-brain 1.3.1 (build …)
RALPHA_HOME /Users/you/.ralpha
…
Unreal MCP @ 30030 reachable on http://127.0.0.1:30030/mcp
Ralpha TCP @ 30010 reachable on 127.0.0.1:30010
Plugin version v1.3.2 (this brain requires >= v1.2.0)
Claude Code … (/usr/local/bin/claude)
Claude Code login signed in (…)
Claude Code 'unreal' http://127.0.0.1:30030/mcp
Claude Code 'ralpha' /Users/you/.ralpha/current/ralpha-brain
All checks passed.When a check fails, doctor ends with a numbered list of next steps instead. The usual ones:
- Unreal MCP @ 30030: NOT reachable
- Unreal’s own MCP server is off. Enable the Model Context Protocol plugin in your project, then in Editor Preferences → Model Context Protocol tick Auto Start Server and set the port to 30030. Claude Code’s
unrealserver needs this; the Brain’s own runs use the plugin’s TCP port and work without it. - Unreal MCP: “not an HTTP MCP endpoint” or “Ralpha’s direct HTTP endpoint”
- Something else is on that port. If you moved Unreal’s MCP server, pass its port:
ralpha-brain doctor --native-port 8000. - Ralpha TCP @ 30010: NOT reachable
- Open your project in UE 5.8 with the Ralpha plugin enabled, wait for the editor to finish loading, and run doctor again.
- Plugin version: “doesn’t expose version”
- The plugin is probably older than this Brain supports. Update it from your Fab library.
- Claude Code: NOT installed
- Install Claude Code, sign in, then run
ralpha-brain setup --client claude-code. - Claude Code login: NOT signed in
- Run
claude auth login, or startclaudeonce and sign in. - Claude Code 'unreal' or 'ralpha': not registered, or MISSING on disk
- Run
ralpha-brain setup --client claude-code.
Your first run
The Brain builds in a new level in the project you have open, so save your work first and use a project you are happy for it to change. Describe a scene:
ralpha-brain --prompt "a calm mountain lake at sunset" --llm claude-code --max-iterations 3Or give it a photo to match:
ralpha-brain --reference image.jpg --llm claude-code --max-iterations 3Always pass --llm claude-code: it is what makes the Brain use your Claude Code sign-in. Without --max-iterations a run can go on for up to 50 iterations by default, so set a small number for a first try.
What you see
- A pre-flight check. If it cannot reach the editor, it stops and says so.
- The Brain reads your prompt or image and lists what the scene contains. This takes a couple of minutes.
- It creates a new level and builds the scene in the editor: sky, sun, light, and the elements your project has assets for. You can watch it in the viewport.
- Each iteration plans changes, makes them, captures a frame and scores it. An iteration takes about 12–15 minutes, so a three-iteration run takes around 45 minutes.
The terminal prints each step as it goes. Add --dashboard to follow the run in a browser page served from your own machine.
The Brain uses only what your project contains. In a new, empty project there are no terrain, plant or prop assets, so most scenes come out as sky, light and water; the run records each element it had no asset for.
Update
ralpha-brain update --check-only
ralpha-brain update--check-only tells you whether a newer Brain is out. Without it, update downloads the new version, keeps the old one, and switches to the new one. To go back, run ralpha-brain rollback.
update also prints a check for the plugin. Plugin updates come from your Fab library.
Where runs are saved
Each run gets its own folder under ~/.ralpha/sessions/runs/ (on Windows, .ralpha\sessions\runs in your user folder), named for the date and time it started. The terminal prints the folder as Session directory when the run begins. Inside:
result/best.png: the best-scoring frame, andresult/metadata.jsonwith its score.screenshots/: the frame from every iteration.history/: what each iteration changed.
At the end of a run the Brain tries to put the editor back on the best scene. If that fails, it reports RESTORE_FAILED and the editor stays on a later scene; result/best.png is still the best frame.
Getting help
Ask in the forum thread linked from the Ralpha listing on Fab. Include the output of ralpha-brain doctor; it shows your versions, ports and paths, and never prints your Claude account’s email.
Version notes: Brain 1.3.1 · support@ralpha.io