Hayba — Engine Agentico para Worldbuilding Espacial em UE5
zajalist/hayba
100+ ferramentas para IA construir mundos 3D em UE5 via MCP
Ver no GitHubMCP server que capacita agentes de IA (Claude, GPT) a autoria de cenas Unreal Engine 5 diretamente: spawning de atores, construção de grafos PCG, validação de física, geração procedural de terreno e execução de Python sandboxado. Inclui registro PCG com SQLite, mapa cognitivo 2D nativo e grounding visual com SpatialCLIP para validação de física e semântica espacial.
Instalação
npx convez-ai zajalist/hayba1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Geração procedural de levels e ambientes 3D em tempo real via agentes IA
- Validação automática de física, layout espacial e integridade de cenas
- Prototipagem rápida de worldbuilding com lógica procedural (PCG, foliage, terreno)
Veredito

Ferramenta altamente especializada e madura para desenvolvimento de mundos procedurais em UE5. A integração nativa de SpatialCLIP, registro PCG e validação física a diferencia, mas exige expertise profunda em Unreal Engine e arquitetura de agentes IA.
README
A tradução para o português deste README ainda está na fila.
Hayba
The agentic engine for spatial and procedural world-building in Unreal Engine 5 — plus the worldbuilding packages and web front-end around it.
Hayba lets your AI agent (Claude / GPT / any MCP host) author UE5 scenes directly: spawn actors, build PCG graphs, validate physics, generate terrain, run sandboxed Python, and more — over a single MCP connection. Spatial-first: where every other MCP server treats UE as a 2D code repository, Hayba ships a PCG SQLite registry, a native 2D Slate cognitive map, and a SpatialCLIP visual grounding sidecar.
This repo holds the MCP server, the UE5 C++ plugin, the worldbuilding libraries, and the public website. The tectonic simulation and its Tauri desktop viewer live in their own repo: hayba-explorer.
Features
- 100+ tools across 33 domains — Actor / Level / Scene / Asset / Blueprint / Material / Foliage / Spline / World Partition / ISM / Physics / Python / Editor / Docs / PCG / Sequencer / Animation / Niagara / Audio / MetaSound / GAS / Behavior Tree / Input / UI / Net / Mesh / Texture / Data / Project / Build / Test / Memory / Plan / Conventions
- PCG SQLite registry — 344 PCGEx nodes / 356 pins / 2270 properties scraped from C++ headers, queryable with semantic + structural intent
- Cognitive Map — 2D top-down semantic clustering of every actor in the level, force-directed mindmap renderer
- Visual sidecar — FastAPI + CLIP / SpatialCLIP / OWL-ViT for deep physics validation and spatial grounding
- Plan Mode + native transactions — every destructive AI op wrapped in
GEditor->BeginTransactionso Ctrl+Z just works - Code Mode meta-tools — 3 tools (
list_tool_categories/get_tool_signature/python_run) reduce initial payload by 92%, full catalog discovered on demand - Worldbuilding packages — deterministic linguistics (conlang/phonology), planet physics (habitability, tidal locking), procedural architecture (cultures, style schema)
- Multi-instance safe — dynamic port allocation (52342-52350) + heartbeat registry so multiple UE instances coexist
Repository layout
| Path | What it is |
|---|---|
mcp-tools/hayba-mcp | Core product — the Node/TypeScript MCP server (tool surface, schema registry, TCP client to UE) |
mcp-tools/hayba-mcp/addons/visual-embeddings | Python FastAPI visual sidecar (CLIP / SpatialCLIP / OWL-ViT) |
mcp-tools/gaea-server | TCP bridge between UE5 and Gaea terrain generation |
mcp-tools/gaea · mcp-tools/pcgex | Locator / parked supporting tooling (see their READMEs) |
unreal/HaybaMCPToolkit | The UE5 C++ editor plugin — 33 command-handler domains, Slate panels, the TCP server half of the protocol |
packages/linguistics · packages/planet-physics | Worldbuilding libs consumed by the MCP server (conlang/phonology, planet habitability) |
packages/architecture | Procedural architecture engine (cultures, style schema, validation) |
website/ | Public website (static HTML/CSS/JS) — landing, waitlist, login, admin |
infra/, supabase/ | Self-host infra (docker-compose, Caddy, Cloudflare tunnel) + Supabase backend (auth, migrations, edge functions) |
Quick start
1. Install the UE plugin
Copy unreal/HaybaMCPToolkit/ into your UE project's Plugins/ folder, regenerate Visual Studio project files, recompile (UE 5.7+, VS 2022).
2. Register the MCP server with your agent host
# Claude Code
claude mcp add hayba-toolkit -- node /path/to/hayba/mcp-tools/hayba-mcp/dist/index.js
// Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"hayba-toolkit": {
"command": "node",
"args": ["/path/to/hayba/mcp-tools/hayba-mcp/dist/index.js"]
}
}
}
3. Run the editor
Open UE; the Hayba MCP Toolkit panel appears in the toolbar. Pick Integrated (your MCP host drives the agent) or API Key (in-editor chat drives Anthropic/OpenAI directly).
Then ask Claude: "Search the PCG node catalog for voronoi, propose a 3-step plan to author a Voronoi graph, and execute it after I approve."
Architecture
┌──────────────────┐ stdio ┌──────────────────┐ TCP ┌────────────────┐
│ Agent Host │ ◄────► │ Node MCP Server │ ◄────► │ UE5 Plugin │
│ (Claude / GPT) │ │ mcp-tools/ │ :52342 │ unreal/ │
└──────────────────┘ │ hayba-mcp │ │ HaybaMCP... │
│ Zod · PCGEx DB │ │ 33 handlers │
└──────────────────┘ └────────────────┘
Two language boundaries, one protocol. The TCP envelope on :52342 (auto-fallback :52343-52350) carries length-prefixed JSON. Plan Mode + the editor transaction system gate every destructive op. See docs/ARCHITECTURE.md and CONTEXT.md.
Documentation
- CONTEXT.md — domain glossary + repo philosophy (read this first)
- Architecture — language boundaries, the TCP seam, data flows
- Getting started — local dev setup and first run
- Wiki — guides, tool reference, troubleshooting
- ADRs — architectural decision records
- Contributing · Changelog · Security · Code of Conduct
Roadmap
Status of everything planned. [x] done · [~] in progress · [ ] not started.
Repo restructure & re-emulation (foundational)
- Monorepo restructure (
packages/hayba→mcp-tools/hayba-mcp,apps/, workspace globs) — PR #136 - Re-emulate PRs #110/#112/#113/#134 onto the restructured layout (linguistics L9, sidecar discovery, prompt tools, ESLint/Prettier/CI)
- Local gate green (build
@hayba/*deps →tsc+ 185 tests inmcp-tools/hayba-mcp) - CI workflow repointed to the new layout; Node bumped to 22
Incorporation (this initiative)
- [~] Website → top-level
website/(re-emulated fromfeat/website-integration, not merged) - [~]
supabase/(auth, migrations, edge functions) + reconcileinfra/ - [~] UE plugin →
unreal/HaybaMCPToolkit/(snapshot; build artifacts gitignored) - Deferred: linguistics workbench as the website
/app+/lang/:id— to be wired during a dedicated linguistics → Hayba Explorer integration step (now cross-repo; see ADR-0005). Until then/appand/lang/:idare graceful placeholders, no@hayba/linguisticsbuild coupling. - Vercel deploy verified end-to-end (env-var injection, rewrites)
Documentation & professionalism
- [~]
CONTEXT.md(domain glossary) - [~]
docs/adr/seeded (re-emulation doctrine, website location, plugin location, deferred linguistics integration) - [~]
docs/ARCHITECTURE.md - [~] Per-workspace READMEs (
mcp-tools/hayba-mcp,gaea-server,website,unreal/HaybaMCPToolkit) - [~]
docs/wiki/scaffold (glossary, setup, MCP tool reference, UE handler map, troubleshooting) - [~] Hygiene:
CODE_OF_CONDUCT.md,.nvmrc,.github/CODEOWNERS,.github/dependabot.yml, rootpackage.jsonmetadata - Expand
docs/getting-started.md(prerequisites → MCP host registration → UE connect → sidecar) - MCP tool catalog reference (auto-generated from Zod schemas)
- Coherent versioning + release process (changesets?)
Architecture deepening (surfaced; future grilling)
Deletion-test-positive opportunities from the friction walk (tectonic excluded) — each needs its own grilling pass before implementation:
- Fragment the 1606-line tool-registration surface (
mcp-tools/hayba-mcp/src/tools/index.ts) into per-domain self-registration - Consolidate config into a deep
@hayba/config(hayba-mcp ↔ gaea-server share ports/paths/keys) - Collapse thin worldbuilding handler wrappers — derive handlers from package schemas (one schema source)
- Replace the manual schema-registry bottleneck (registration + schema as one operation)
- Versioned TCP envelope between
gaea-server/hayba-mcpand the UE plugin - Make the dashboard-vs-Tauri decision explicit; inject
architecture-handlersdata root instead ofimport.meta.urlpath math
Known constraints
- The authoritative gate is local: build
@hayba/*deps, thentsc+npm testinmcp-tools/hayba-mcp. Run it before pushing. - Tectonic plate-sim work lives in hayba-explorer, not here.
The full backlog with priority/effort lives in open issues.
Development
npm install # all workspaces (Node ≥ 22.5 — see .nvmrc)
npm run -w @hayba/linguistics build # build workspace TS deps the MCP server needs…
npm run -w @hayba/architecture build # …(also @hayba/planet-physics)
npm --prefix mcp-tools/hayba-mcp test # the authoritative gate (tsc + vitest)
Run the gate locally before pushing.
License
Hayba's source code is MIT-licensed (see LICENSE).