Eve library

Bellona Unreal Plugin Architecture

Guide

Revision 1

On this page

Status: Phase 180.C.15.01 architecture note.

Implementation date: 2026-04-23.

This note defines the target architecture for bringing Unreal Editor under the Bellona Remote Creative Control Plane. It is intentionally narrower than the older apps/bellona/bridge-unreal bridge: the plugin is not a network-facing remote-control authority. It is a host-local editor integration that receives already-authorized commands from the Bellona Remote Host, executes a small allow-listed command surface inside Unreal Editor, and returns protocol-shaped results, progress, and evidence to the gateway path.

Sources Reviewed#

Local implementation and architecture references:

  • apps/bellona/bridge-unreal/src/main.ts
  • libs/bellona/unreal/src/bridge/unreal-bridge.ts
  • libs/bellona/unreal/src/bridge/version-discovery.ts
  • libs/bellona/unreal/src/types.ts
  • apps/bellona/remote-host/src/adapter-registry.ts
  • apps/bellona/remote-host/src/command-executor.ts
  • apps/bellona/remote-host/README.md
  • docs/domains/bellona/extras/remote-control/adr/ADR-0001-standalone-remote-gateway-and-host.md
  • docs/domains/bellona/extras/remote-control/compatibility-matrix.md
  • docs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.md
  • docs/domains/bellona/extras/remote-control/blender-read-only-mvp-second-macbook.md
  • docs/domains/bellona/extras/remote-control/blender-primitive-rollback-and-undo.md
  • docs/domains/bellona/extras/remote-control/blender-safe-mutation-mvp-closure.md

Official Unreal references checked against Unreal Engine 5.6 documentation:

Design Goals#

  • Keep Unreal Editor APIs localhost-only and never expose the editor, Remote Control API, Python scripting, or a custom plugin listener directly to LAN or internet clients.
  • Reuse the completed gateway-host-adapter shape instead of reviving the older bridge as a privileged service.
  • Make libs/bellona/remote-protocol the command/result source of truth for Stage 15 commands.
  • Start with read-only capability and world queries before any mutation.
  • Treat spawn/mutation work as an editor transaction with undo/evidence and gateway-visible audit.
  • Fail closed when the editor, project, plugin, policy, approval, transaction, or evidence path is missing.

Architecture Boundary#

text
MCP client / Control Room / agent
  -> Bellona Remote Gateway
  -> outbound Remote Host connection
  -> Remote Host adapter registry
  -> adapter:unreal-local
  -> localhost-only Unreal plugin or localhost-only Unreal Remote Control API
  -> Unreal Editor

The gateway owns device identity, session lifecycle, policy, approval, idempotency, timeline, artifacts, and audit records. The Remote Host owns local adapter registration, command execution, cancellation, dynamic readiness, and macOS diagnostics. The Unreal plugin owns only editor-side execution and editor-side state introspection.

The older apps/bellona/bridge-unreal shape remains a useful implementation reference for request/response forwarding and connected-editor detection, but it must not become the Stage 15 authority. Stage 15 commands must enter through the gateway-host command executor and must be visible in the same timeline and audit records as Blender and browser commands.

Target Package Layout#

The first implementation should keep the Bellona host adapter in TypeScript and the Unreal plugin in an editor plugin bundle:

text
apps/bellona/remote-host/src/unreal-adapter.ts
apps/bellona/remote-host/src/unreal-adapter.test.ts
apps/bellona/remote-host/scripts/unreal-readonly-remote-smoke.ts
apps/bellona/remote-host/scripts/unreal-actor-spawn-remote-smoke.ts
libs/bellona/unreal/
  src/bridge/version-discovery.ts
  src/project/project-parser.ts
  src/project/project-writer.ts
  plugin/BellonaUnrealEditor/BellonaUnrealEditor.uplugin
  plugin/BellonaUnrealEditor/Source/BellonaUnrealEditor/

The TypeScript adapter should use existing libs/bellona/unreal version and project parsing helpers for discovery. The editor plugin can be added under libs/bellona/unreal/plugin/ when 180.C.15.05 starts real editor connection work. Until then, mocked adapter tests must define the contract.

Plugin Module Shape#

The plugin should be a project or engine plugin with an editor-only primary module:

  • Plugin descriptor: BellonaUnrealEditor.uplugin.
  • Primary module: BellonaUnrealEditor, module type Editor.
  • Loading phase: Default unless later hardware testing proves a narrower phase is required for startup readiness.
  • Runtime module: deferred. Stage 15 controls Unreal Editor, not packaged games.
  • Content: disabled unless a fixture asset or editor utility asset is introduced by a later tested task.

The editor module should initialize only inside Unreal Editor and should not start network listeners by default. If a listener is required, it must bind to 127.0.0.1 and require a per-session token issued by the Remote Host. A safer first implementation is for the TypeScript host adapter to talk to Unreal's existing localhost Remote Control HTTP/WebSocket endpoint after verifying it is loopback-only and after the Bellona plugin reports readiness.

180.C.15.05 adds that first editor plugin bundle at libs/bellona/unreal/plugin/BellonaUnrealEditor/ and keeps it editor-only, content-free, and disabled by default. The plugin starts its HTTP readiness listener only when a session token is supplied through BELLONA_UNREAL_PLUGIN_SESSION_TOKEN or -BellonaUnrealPluginToken=.... The listener publishes only GET /bellona/unreal/v1/ready, requires an Authorization: Bearer <token> header, and sets the Unreal HTTP server bind address to 127.0.0.1 before registering the route. The TypeScript @bellona/unreal transport helper and Remote Host adapter both reject non-loopback endpoints before probing.

Transport Model#

Allowed local transports:

  • Host adapter to Unreal plugin over 127.0.0.1 with an ephemeral session token.
  • Host adapter to Unreal Remote Control HTTP/WebSocket over 127.0.0.1 after explicit loopback validation.
  • Host adapter to Unreal process/project discovery through local filesystem and process inspection.

Blocked transports:

  • Any Unreal listener on 0.0.0.0, LAN IPs, public IPs, or cloud-facing hosts.
  • Direct MCP client to Unreal, direct Control Room to Unreal, or direct agent to Unreal.
  • Direct use of Unreal console commands, arbitrary Python, arbitrary Blueprint calls, or raw Remote Control object mutation before protocol, policy, approval, undo, evidence, and audit gates are complete.

Transport records must include editor process id when available, project path, engine version, plugin version, Remote Control endpoint provenance, and whether the endpoint was verified loopback-only.

Command Surface#

Stage 15 should introduce the Unreal command surface in this order:

Command Stage Risk Required behavior
unreal.adapter.discovery 180.C.15.02 read-only Report install path, engine version, project path, plugin state, editor running state, Remote Control endpoint state, and supported command list.
unreal.project.info 180.C.15.03 read-only Return protocol-valid project metadata without mutating project files.
unreal.world.query 180.C.15.04 read-only Return current world/map/level/actor summary with bounded result size.
unreal.actor.spawn 180.C.15.07 mutating Require policy allow, approval when configured, editor transaction/undo, result actor reference, and screenshot/evidence placeholder.

The command names above deliberately use the unreal.* namespace from libs/bellona/remote-protocol/src/namespaces.ts. Older bridge commands such as unreal:get-world-info and unreal:spawn-actor are implementation references only and should not leak into the Phase 180 remote protocol.

Capability Discovery Contract#

adapter:unreal-local should report capability and readiness separately:

  • Adapter health: healthy, degraded, unavailable, or blocked.
  • Engine install path and version from UnrealVersionDiscoverer.
  • Project path and .uproject metadata from existing project parsing helpers.
  • Editor running state and process metadata.
  • Plugin installed/enabled/loaded state.
  • Remote Control enabled state, endpoint, and loopback validation result.
  • Supported command names and blocked command names.
  • Hardware evidence marker, initially liveEditorExercised: false in mocked tests and true only in optional fixture smoke output.

The adapter must advertise read-only capability before mutation capability. If the plugin is missing or the editor is not running, discovery still succeeds but returns degraded or unavailable state with remediation text rather than throwing an opaque error.

Read-Only Query Rules#

unreal.project.info may read:

  • Engine association and engine version.
  • Project name, path, plugins, modules, target platforms, and config summary.
  • Whether the project root is read-only under host filesystem permissions.
  • Whether Remote Control and Bellona plugin support are available.

It must not write .uproject, config files, generated project files, or plugin state.

unreal.world.query may read:

  • Open map/world names.
  • Persistent level and streaming level summaries.
  • Actor counts by class and a bounded actor sample.
  • Selection state if exposed by a safe editor API.
  • Shader compile count or editor busy state when available.

It must cap result size, redact local absolute paths unless required by policy, and return a structured blocker when the editor is in PIE, compiling, loading, or showing a modal dialog.

Safe Mutation Rule For Actor Spawn#

unreal.actor.spawn is the first allowed mutation and must be implemented only after read-only discovery/query pass. The mutation must:

  • Require a protocol command envelope with rollbackStrategy: "undo_stack".
  • Require gateway policy allow and approval if project or actor class policy requires it.
  • Limit spawnable classes to an allow list, starting with simple fixture-safe actors.
  • Execute inside an Unreal editor transaction so Undo can reverse the spawn.
  • Return actor path, actor label, class, transform, transaction id or undo marker, and evidence references.
  • Emit progress and final result through the existing Remote Host command executor.
  • Fail closed if transaction creation, spawn, evidence capture, or audit registration fails.

Arbitrary actor destruction, Blueprint function calls, console commands, sequencer operations, build/cook/package, project saves, and asset writes remain blocked until later protocol schemas and risk controls explicitly unlock them.

Security And Policy Requirements#

  • The Remote Host validates every command with RemoteCommandEnvelopeSchema before adapter routing.
  • The adapter rejects commands outside its advertised capability list.
  • Project roots must be checked for read-only state before mutation.
  • The plugin never accepts unauthenticated network traffic.
  • Absolute project paths, user home paths, and engine install paths are audit metadata, not free-form agent-visible text unless the command result schema requires them.
  • Any Remote Control endpoint must be verified as loopback-only before use.
  • Unreal Python execution is not a Stage 15 command surface.
  • Unreal console execution is not a Stage 15 command surface.
  • Desktop fallback may observe Unreal for evidence only after the typed adapter path attempts the command and the visual verification policy requires it.

Testing Plan#

Required automated coverage before checking later Stage 15 implementation items:

  • Mocked adapter discovery: Unreal missing, plugin missing, project closed, Remote Control disabled, Remote Control non-loopback, and healthy editor.
  • Read-only project info success and project-root read-only reporting.
  • Read-only world query success, bounded actor result size, editor busy blocker, and modal/dialog blocker.
  • Actor spawn success, policy deny, approval required/denied, transaction failure, spawn failure, evidence placeholder failure, and cancellation.
  • Gateway-host routing evidence: command accepted, started, progress, completed/failed/denied, timeline entry, and audit artifact references.

Optional hardware evidence for 180.C.15.09 must record:

  • Mac hardware id from docs/domains/bellona/extras/remote-control/hardware-rig-inventory.md.
  • macOS version, Unreal version, project path, plugin commit/version, and editor process id.
  • Discovery output with liveEditorExercised: true.
  • unreal.project.info, unreal.world.query, and fixture-safe unreal.actor.spawn command ids.
  • Undo verification or documented manual undo evidence for spawned actor.
  • Screenshot/evidence artifact ids.

Stage 15 Gate#

180.C.15.10 can close only when Unreal follows the same verified path as the completed Blender/browser/host work:

  • protocol-owned command/result schemas
  • host adapter registration and capability reporting
  • gateway-host command routing
  • policy and approval checks
  • rollback/undo strategy for mutation
  • timeline and audit visibility
  • evidence placeholders or screenshots
  • mocked tests for failure modes
  • optional hardware smoke evidence clearly separated from deterministic CI

Stage 15 closure evidence is recorded in unreal-readonly-safe-mutation-mvp-closure.md.