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.tslibs/bellona/unreal/src/bridge/unreal-bridge.tslibs/bellona/unreal/src/bridge/version-discovery.tslibs/bellona/unreal/src/types.tsapps/bellona/remote-host/src/adapter-registry.tsapps/bellona/remote-host/src/command-executor.tsapps/bellona/remote-host/README.mddocs/domains/bellona/extras/remote-control/adr/ADR-0001-standalone-remote-gateway-and-host.mddocs/domains/bellona/extras/remote-control/compatibility-matrix.mddocs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.mddocs/domains/bellona/extras/remote-control/blender-read-only-mvp-second-macbook.mddocs/domains/bellona/extras/remote-control/blender-primitive-rollback-and-undo.mddocs/domains/bellona/extras/remote-control/blender-safe-mutation-mvp-closure.md
Official Unreal references checked against Unreal Engine 5.6 documentation:
- Plugins: https://dev.epicgames.com/documentation/en-us/unreal-engine/working-with-plugins-in-unreal-engine?application_version=5.6
- Modules: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-modules?application_version=5.6
- Remote Control HTTP API: https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-api-http-reference-for-unreal-engine?application_version=5.6
- Remote Control WebSocket API: https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-api-websocket-reference-for-unreal-engine?application_version=5.6
- Python editor scripting: https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python
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-protocolthe 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#
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:
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 typeEditor. - Loading phase:
Defaultunless 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.1with an ephemeral session token. - Host adapter to Unreal Remote Control HTTP/WebSocket over
127.0.0.1after 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, orblocked. - Engine install path and version from
UnrealVersionDiscoverer. - Project path and
.uprojectmetadata 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: falsein mocked tests andtrueonly 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
RemoteCommandEnvelopeSchemabefore 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-safeunreal.actor.spawncommand 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.