# Bellona Unreal Plugin Architecture

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:

- 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-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`](./unreal-readonly-safe-mutation-mvp-closure.md).
