Hayba

Build Unreal worlds with agents that can share an editor.

Inspect, plan, build, and validate Unreal Engine worlds through MCP. Native editor checks keep agent work accountable to the state of the project.

Install Hayba 0.4.1 on Windows with Unreal Engine 5.9, step by step

Explore the architecture | Browse the tools | Changelog | Contribute

Hayba connects MCP-capable agents to Unreal Editor. It gives them a wide tool library, a focused in-editor workspace, and a native safety boundary for changes to a shared project.

Release status: v0.4.1 is the latest release. It is tested on Unreal Engine 5.9 (5.7 and 5.8 may work but were not tested for this release) and ships the new editor workspace, multi-agent editor leases and the editor safety train. See the changelog and versioning.

Actual scratch-editor captures of the editor workspace. Chat shows the empty workspace; it does not demonstrate a connected conversation. World shows 130,048 sampled points from 1,024 synthetic actors, not an entire unloaded project.

See the workflow

A typical request is concrete: “Inspect this level, propose a route to the focal point, then make the approved changes.” Hayba exposes the scene and relevant tools, lets the agent prepare a reviewable plan, and checks the editor before writes. The install guide walks through setup step by step.

Related MCP server: unreal-engine-mcp

Why Hayba

The tool reference covers individual operations. Optional GAS and MetaSound plugins extend the core. The distinction is how the tools work together under a shared editor's live constraints.

See the safety boundary

The TypeScript MCP server routes requests to the C++ editor plugin. The editor plugin checks state and ownership where writes actually happen. The visual sidecar is optional. Explore the architecture.

Safety is part of the workflow

Release 0.4.1 includes a coordinated set of protections: sticky refusal after a contained native fault, PIE and asset-busy checks, guarded save paths, owner-bound leases with recovery, and bounded batch execution. These address a shared editor's real failure modes: one agent can hold a resource while another reads stale state, Play can begin during a build, or a native fault can leave the editor unsafe for more writes. The scratch-host safety guide records the live verification boundaries.

Hayba does not treat every refusal as failure. A structured refusal tells the agent whether to wait, refresh state, request a lease, stop Play, or return control to the user. Plan Mode requires approval for destructive commands when enabled; owner-bound leases, PIE and editor-health guards apply independently. Native undo covers supported operations, with documented exceptions. Read the safety model · Security policy · Decision records

World, from scene evidence

The current preview progressively scans loaded static meshes. The scratch-editor capture above shows 130,048 surface samples from 1,024 synthetic actors, with source links for those mesh samples. A second scratch capture includes 37,277 depth-derived points from a 256×256 capture of first-visible surfaces. A zoom-local tile adds 8,192 points sampled from mesh triangles. An agent can start a loaded-world tile capture with world_tile_capture, then inspect its bounded geometry, source nodes, and authored semantic groups with world_semantic_snapshot. The latest depth observation also has queryable pages with a capture ID, camera, coverage, and gaps. Uncaptured regions report not_captured. The depth pass covers one editor-camera view, not an entire level; only sparse depth-matched collision labels identify possible sources. Unloaded cells and occluded surfaces remain unknown.

Open the World capture · Zoom-local mesh detail · Read the World model

The next World layer

The next layer will use that evidence to compare scene composition and production options: sightlines, routes, streaming and NPC pressure, memory, texel density, PCG placement, and hand-placed focal assets. It should score alternatives with measured constraints and call out unknowns. That decision layer is planned work, not a shipped capability. Read the World direction.

Install

Requirements: Windows, Unreal Engine 5.9, Node.js 22.5 or newer, Git, and the Visual Studio C++ tools Unreal uses to compile plugins. The optional visual sidecar has separate Python dependencies.

Follow the step-by-step install guide. It covers every click and command, how to check each part works, and a troubleshooting table. The short version, in PowerShell:

git clone --branch v0.4.1 https://github.com/zajalist/hayba.git C:\Tools\hayba
Set-Location C:\Tools\hayba; npm install; npm run build
$Project = "C:\path\to\YourProject"   # the folder with your .uproject
New-Item -ItemType Directory -Force "$Project\Plugins"
New-Item -ItemType Junction -Path "$Project\Plugins\HaybaMCPToolkit" -Target "C:\Tools\hayba\unreal\HaybaMCPToolkit"
& "C:\Program Files\Epic Games\UE_5.9\Engine\Build\BatchFiles\Build.bat" UnrealEditor Win64 Development -Project="$((Get-ChildItem $Project -Filter *.uproject).FullName)" -WaitMutex
claude mcp add hayba-toolkit -- node C:\Tools\hayba\mcp-tools\hayba-mcp\dist\bootstrap.js

Then open the project. The Hayba MCP Toolkit panel opens by itself the first time (later: Tools > Hayba MCP Toolkit). Start with a scratch project while evaluating any tool that can modify editor state. Getting started covers add-ons and other MCP hosts.

Explore the repository

Developers can run npm --prefix mcp-tools/hayba-mcp test for the Node gate. Unreal tests require a separately built project; CONTEXT.md and the architecture guide explain the boundaries before changing them.

A worldbuilding tool should understand the world—and know when to stop.

Getting started · Changelog · License