Eve library

Unreal Read-Only And Safe Mutation MVP Closure

Guide

Revision 1

On this page

Closure date: 2026-04-23

This note closes 180.C.15 for the Unreal read-only and first safe mutation MVP. It records the evidence that Unreal commands now follow the same Bellona Remote Creative Control Plane path used by Blender: protocol-owned schemas, gateway policy and audit, Remote Host adapter routing, transaction/undo metadata, evidence placeholders, and documented optional hardware smoke.

Closure Scope#

The closed command path is:

  • read-only protocol commands: unreal.project.info and unreal.world.query
  • first safe mutation protocol command: unreal.actor.spawn
  • host adapter: adapter:unreal-local
  • required mutation permission scope: project.write
  • mutation risk class: safe-mutation
  • rollback strategy: undo_stack
  • mutation result fields: actor summary, object reference, editor transaction, undo checkpoint id, evidence references, and visual verification placeholder

This closure does not claim broad Unreal Editor control. It closes the Stage 15 MVP surface only: discovery, project info, world query, and a fixture-safe actor spawn command with mocked editor transaction behavior and an optional hardware smoke entry point.

Implementation Evidence#

The closed path is backed by the following completed Phase 180 items:

  • 180.C.15.01: Unreal plugin architecture, security boundary, command order, and Stage 15 gate documented.
  • 180.C.15.02: Unreal adapter discovery for engine, project, plugin, editor, Remote Control, and supported command state.
  • 180.C.15.03: protocol-owned unreal.project.info schema, fixture, and mocked adapter response.
  • 180.C.15.04: protocol-owned unreal.world.query schema, fixture, and mocked adapter response.
  • 180.C.15.05: editor-only Unreal plugin bundle plus authenticated localhost-only readiness transport.
  • 180.C.15.06: gateway-host routing for unreal.project.info and unreal.world.query with timeline and audit visibility.
  • 180.C.15.07: protocol, policy, host adapter, gateway routing, transaction, undo checkpoint, object reference, and evidence placeholder support for unreal.actor.spawn.
  • 180.C.15.08: mocked failure matrix for missing Unreal, missing plugin, project/editor not ready, successful read-only query, actor spawn, policy deny, and failed transaction results.
  • 180.C.15.09: optional fixture-project smoke command for read-only query and actor spawn, with structured skip behavior when hardware is not configured.

Deterministic Remote Evidence#

The read-only remote smoke validates the gateway-host-adapter path with deterministic fixture-backed Unreal outputs:

bash
pnpm nx unreal:readonly-remote-smoke @bellona/remote-host --skip-nx-cache --verbose

The actor-spawn fixture smoke validates the protocol output shape for unreal.project.info, unreal.world.query, and unreal.actor.spawn, and exits with a structured skip unless a fixture Unreal project is explicitly enabled:

bash
pnpm nx unreal:actor-spawn-remote-smoke @bellona/remote-host --skip-nx-cache --verbose

Result on this machine:

json
{
  "status": "skipped",
  "required": false,
  "reason": "Set BELLONA_UNREAL_HARDWARE_SMOKE=1 and BELLONA_UNREAL_PROJECT_PATH to run the optional Unreal fixture smoke."
}

The deterministic package tests also validate:

  • protocol schema acceptance and rejection paths for Unreal commands
  • policy scope inference and denial for unreal.actor.spawn
  • adapter registration and observe-only mutation blocking
  • read-only project/world query outputs
  • actor-spawn transaction success and failure output
  • gateway command dispatch, audit entries, timeline events, and client result routing

Hardware Evidence Boundary#

No live Unreal Editor process, compiled plugin binary loaded in an editor, Remote Control endpoint, second MacBook, WebRTC stream, approval backend, browser profile, desktop helper, Blender process, or cloud model was exercised for this closure.

Live fixture evidence remains available through:

bash
BELLONA_UNREAL_HARDWARE_SMOKE=1 \
BELLONA_UNREAL_PROJECT_PATH=/path/to/FixtureProject.uproject \
pnpm nx unreal:actor-spawn-remote-smoke @bellona/remote-host -- --required

When hardware is configured, the smoke records project path, plugin descriptor, plugin connection status, editor process id, command ids, actor id, transaction id, undo checkpoint id, screenshot placeholder status, and whether a live editor connection was exercised.

Rollback Note For Review Records#

For this closure, review records should attach the following note:

json
{
  "commandId": "command:unreal-actor-spawn-fixture-smoke-001",
  "rollbackStrategy": "undo_stack",
  "undoCheckpointId": "undo-checkpoint:command:unreal-actor-spawn-fixture-smoke-001",
  "transactionStatus": "committed",
  "actorId": "actor:bellona-spawned-static-mesh-001",
  "objectReference": "actor:bellona-spawned-static-mesh-001",
  "visualVerification": "screenshot_placeholder",
  "rollbackAttempted": false,
  "rollbackResult": "documented_manual_editor_undo",
  "limitations": [
    "Stage 15 actor spawn uses mocked transaction output unless an Unreal fixture project is explicitly configured.",
    "Unreal undo stack validity is scoped to the active editor transaction history.",
    "The MVP does not expose a remote rollback command.",
    "Screenshot capture remains a placeholder until later visual evidence work replaces it."
  ]
}

Closure Decision#

180.C.15 is closed for the Unreal read-only and safe mutation MVP because the system now has:

  • canonical protocol ownership for Unreal discovery, read-only query, and first safe mutation commands
  • localhost-only plugin readiness transport and loopback validation
  • Remote Host adapter registration, capability reporting, and observe-only mutation denial
  • gateway policy, audit, timeline, and client result routing for read-only and safe mutation commands
  • transaction and undo checkpoint metadata for the mutation result
  • evidence references and screenshot placeholder status
  • mocked success and failure coverage for the Stage 15 command surface
  • optional hardware smoke entry point with explicit skip and required modes
  • documented limitations for live editor, undo, and visual evidence

The next unchecked Phase 180 item is 180.C.16.01, but this closure note does not start that stage.