# Unreal Command Hardware And Live-Editor Verification

Runbook date: 2026-06-22

Scope: `180.C.23.09` (the Unreal analogue of the Blender
`180.C.17.09` runbook,
[`blender-production-command-hardware-verification.md`](./blender-production-command-hardware-verification.md)).

This note records, for **every** Unreal remote-control command in
`180.C.23` and `180.C.24`, exactly which parts are proven by normal CI and which
parts can only be proven on a real Unreal Engine workstation — and the manual
steps an operator runs to prove the runtime behaviour.

## What normal CI already proves (and what it does not)

The deterministic CI path (run on any box, no GPU, no live editor) proves:

- **Protocol ownership + schema validation** — every command's argument schema,
  envelope schema, and result schema, plus the `superRefine` policy gates
  (`libs/bellona/remote-protocol/src/unreal.test.ts`).
- **Risk / approval / allowlist logic** — read-only commands reject approval
  metadata; destructive commands (`unreal.actor.destroy`, `unreal.asset.delete`)
  are refused without `approvalRequired=true` **and** an `approvalRequestId`;
  non-allowlisted `unreal.blueprint.call_function` / `unreal.console.execute`
  require a granted approval and a high-risk audit flag.
- **Host routing + mocked result normalization** — the host adapter dispatches
  each command and re-parses the result through its schema
  (`apps/bellona/remote-host/src/unreal-adapter.test.ts`).
- **End-to-end fixture scenarios** — map open/save, actor mutation, material
  update, asset import/provenance, Blueprint call, console allowlist,
  undo/transaction metadata, and policy denial, driven through the adapter mock
  harness (`apps/bellona/remote-host/src/unreal-adapter-fixtures.test.ts`,
  `180.C.23.08`).
- **The C++ editor plugin compiles.** The on-box build produces
  `libUnrealEditor-BellonaUnrealEditor.so` (the
  `BellonaUnrealEditor` editor module). Compilation proves the handlers bind to
  real engine symbols (`FScopedTransaction`, `UEditorActorSubsystem`,
  `IAssetTools`, `UMoviePipelineQueueSubsystem`, `FScreenshotRequest`,
  `GShaderCompilingManager`, `ISourceControlModule`, `ILiveLinkClient`, …) —
  see `BellonaUnrealEditor.Build.cs` for the linked module list.

Normal CI does **not** prove:

- a real `UnrealEditor` process running on the target rig with a loaded world;
- any editor mutation actually changing the live world / asset (the mock builder
  returns a protocol-valid result computed from the command args; it explicitly
  flags `executedAgainstLiveEditor: false`);
- a real viewport screenshot, a GPU Movie Render Queue (MRQ) render, a cook /
  package via `RunUAT`, a Play-In-Editor (PIE) session, or a Virtual Production
  Live Link source;
- editor undo-operator behaviour in a live session (CI proves the result carries
  the `undo_stack` checkpoint metadata, not that the editor undo restores state).

Do not treat the deterministic CI coverage as hardware signoff for live Unreal
command execution.

## The honesty contract in the C++ dispatcher

The live-editor handlers
(`libs/bellona/unreal/plugin/BellonaUnrealEditor/Source/BellonaUnrealEditor/Private/BellonaEditorCommandDispatcher.cpp`)
never report a success they did not perform:

- Every mutating handler is wrapped in an `FScopedTransaction` and calls
  `UObject::Modify()` before writing, so the editor undo stack can revert it.
- A handler that cannot reach its hardware **fails loud** (`requires a running
  editor world …`, `… require a WITH_EDITOR build.`) or returns an explicit
  `placeholder` / `not-configured` / `skipped` / `queued` state with a reason,
  rather than fabricating output. The canonical examples — which an operator
  should expect to see when the hardware is absent — are the screenshot
  `placeholder` (no viewport), MRQ `progress: queued` (no executor rendering),
  `runUatExecutedByEditor: false` (the editor does not fork the cook), Live Link
  `not-configured` (no VP source), and benchmark `skipped` (GPU/cook/PIE ops).

## Required rig

Use a workstation running the on-box UE5.5.4 source build (the editor refuses to
run as root; run as the `ueagent` user), with:

- the repo commit under review built into
  `libUnrealEditor-BellonaUnrealEditor.so`;
- a fixture `.uproject` with the `BellonaUnrealEditor` plugin enabled and the
  loopback command transport listening on `127.0.0.1` only;
- a fixture map containing at least: one `StaticMeshActor`, one camera
  (`ACameraActor`), one directional light, and one `UMaterialInstanceConstant`
  asset under `/Game/Materials`;
- a writable `/Game/Imported` content path and an `Sources/` directory with real
  GLB / FBX / texture files for import;
- for MRQ / cook claims: a GPU + the platform SDK and `RunUAT.sh`;
- for VP claims: a Live Link source (camera or transform subject); optionally an
  nDisplay cluster.

Record every run under
`docs/domains/bellona/extras/remote-control/evidence/180.C.23.09/<date>-<rig>-unreal-commands.md`
with: rig id, engine version, plugin version, repo commit, confirmation the
transport stayed loopback-only, the command envelope(s), and result JSON
excerpts including transaction ids, undo-checkpoint ids, provenance hashes,
artifact ids, and any explicit `placeholder` / `not-configured` / `queued`
blockers.

## Verification rules

1. Prove the transport first: confirm the plugin `ready` endpoint answers on
   `127.0.0.1` and is authenticated, and that discovery reports
   `plugin.status: available`.
2. For every mutating command, capture a before `unreal.world.query` (or
   `unreal.map.list`), the command result, and an after `unreal.world.query`.
3. For every `undo_stack` command verified live, perform one editor **Undo**
   (`Ctrl+Z`) and record a post-undo `unreal.world.query` proving the state
   reverted — this is the live-editor proof CI cannot give.
4. For import/asset commands, capture the source byte size + SHA-256 and confirm
   the result `provenance.sourceSha256` is the **bytes** hash (the live plugin
   re-hashes the real file; the mock's path-hash fallback does not count).
5. If a command only reaches a `placeholder` / `not-configured` / `queued`
   state, say so explicitly — that is honest absence, not a live proof.
6. If a command falls back to the mocked route (`executedAgainstLiveEditor:
   false`), the run does not count for `180.C.23.09`.

---

## Group A — loaded editor world / asset registry only

These need a running `UnrealEditor` with a loaded world and the
AssetRegistry / AssetTools modules, but **no** GPU, viewport, cook, or play
session. CI proves the schema + risk/approval logic + mocked result; the live
proof is that the mutation changes the real world/asset and undoes correctly.

| Command | Live UE API it calls (why it needs a live editor) | How to verify on hardware |
| --- | --- | --- |
| `unreal.map.list` | `IAssetRegistry::SearchAllAssets` + `GetAssetsByClass(UWorld)`; active map via `World->GetOutermost()->GetName()`. Fails loud if `GEditor` world is null. | Open the fixture project; run the command; confirm the listed maps + the active map match the editor, and per-map dirty / source-control state match the Content Browser. |
| `unreal.map.open` | `ULevelEditorSubsystem::LoadLevel` (pre-checked with `FPackageName::DoesPackageExist`). | Run against a second fixture map; confirm the editor switches maps and the freshly-loaded map reports clean (`dirtyAfter: false`). |
| `unreal.map.save` | `ULevelEditorSubsystem::SaveCurrentLevel`; dirty via `FindPackage(...)->IsDirty()`. | Dirty the level (move an actor), run save; confirm `dirtyBefore: true → dirtyAfter: false`, the `.umap` mtime advances, and the package is the one written. |
| `unreal.map.create` | `ULevelEditorSubsystem::NewLevel(path, bWorldPartition)` then `SaveCurrentLevel`. | Run with a new package path; confirm the `.umap` is created on disk and opens. |
| `unreal.actor.select` | `UEditorActorSubsystem::SetSelectedLevelActors` / `SetActorSelectionState` / `GetSelectedLevelActors` inside an `FScopedTransaction`. | Run replace/add/toggle modes; confirm the viewport + World Outliner selection matches the returned ids. |
| `unreal.actor.set_transform` | `FScopedTransaction` + `Actor->Modify()` + `SetActorTransform(..., ETeleportType::TeleportPhysics)` + `MarkComponentsRenderStateDirty()`; reads `GetActorTransform()` as `previousTransform`. | Run the canonical transform; confirm the actor moves to the applied transform in the viewport, then **Undo** and confirm it returns to `previousTransform`. |
| `unreal.actor.set_property` | Reflection: `FindFProperty` + `ImportText_Direct` / `ExportText_Direct` + `PostEditChangeProperty`, inside an `FScopedTransaction`. | Set a known UPROPERTY (e.g. a light `Intensity`); confirm the Details panel value changes and Undo restores it. |
| `unreal.actor.attach` | `FScopedTransaction` + `AttachToActor(parent, FAttachmentTransformRules, socket)` (and `DetachFromActor` first). | Attach mesh→camera; confirm the Outliner parenting and Undo detaches. |
| `unreal.actor.destroy` | `UEditorActorSubsystem::DestroyActor` (+ `GetAttachedActors`) inside an `FScopedTransaction`. **Refuses without `__approvalRequestId`.** | With a granted approval, destroy a seeded actor; confirm it is gone from the Outliner and Undo restores it. Confirm a request without approval is refused before any editor call. |
| `unreal.blueprint.call_function` | `StaticLoadObject` → CDO/`UBlueprint::GeneratedClass`; `UObject::FindFunction`; param marshalling (`InitializeValue_InContainer`, `ImportText_Direct`); `UObject::ProcessEvent` (the live invoke); readback via `ExportText_Direct` / `FBoolProperty` / `FNumericProperty`. Allowlist + approval gate. | Call an allowlisted `UFUNCTION` on a Blueprint actor; confirm the real return values + the function's side effect in the world. A non-allowlisted name without approval must be refused. |
| `unreal.material.set_parameter` | `GetMaterial(slot)` or `StaticLoadObject(UMaterialInterface)`; requires a `UMaterialInstanceConstant`; `SetScalar/Vector/TextureParameterValueEditorOnly` (read back from `MIC->*ParameterValues`) + `PostEditChange()` + `MarkPackageDirty()`, inside an `FScopedTransaction`. **Screenshot evidence is a `placeholder` here** — capture is deferred to `unreal.viewport.screenshot` (Group B). | Set a vector parameter on an MIC; confirm the value in the Material Instance editor and the shader preview, then Undo. For visual evidence, follow with a viewport screenshot. |
| `unreal.asset.import` | `NewObject<UAssetImportTask>` → `IAssetTools::ImportAssetTasks` (the Interchange pipeline) → `GetObjects()`. Source bytes hashed (FIPS 180-4 SHA-256) for provenance, with asserted-digest-mismatch fail-loud. | Import a real GLB/FBX/texture; confirm the `.uasset` appears, opens, and the result `provenance.sourceSha256` equals the **file bytes** hash + `sourceBytes` is the real size. |
| `unreal.asset.reimport` | `FReimportManager::Instance()->UpdateReimportPaths` + `Reimport(asset, …, bAutomated=true)`; save via `UPackage::SavePackage`. | Edit the source file, reimport; confirm the asset content updates and the new source path/hash is recorded. |
| `unreal.asset.find` | `IAssetRegistry::GetAssets(FARFilter{ ClassPaths, PackagePaths, bRecursive… })`; `FAssetData::GetSoftObjectPath()`. | Query by class/path; confirm the returned set matches a Content Browser filter. |
| `unreal.asset.rename` / `unreal.asset.move` | `IAssetTools::RenameAssets(TArray<FAssetRenameData>)` (leaves a `UObjectRedirector`); `SavePackage` for the new + redirector packages. | Rename/move a fixture asset; confirm the new path, the redirector at the old path, and that references still resolve. |
| `unreal.asset.delete` | `IAssetRegistry::GetReferencers` (to block referenced deletes) then `ObjectTools::DeleteAssets(..., bShowConfirmation=false)`. **Refuses without `__approvalRequestId`.** | With a granted approval, delete an unreferenced fixture asset; confirm removal. Confirm a referenced asset is blocked and an unapproved request is refused. |
| `unreal.asset.fixup_redirectors` | `IAssetRegistry` scoped to `UObjectRedirector` + `IAssetTools::FixupReferencers(..., bCheckoutDialogPrompt=false)`. | After a rename, run fixup; confirm the redirectors are consumed and references point at the new asset. |
| `unreal.console.execute` | `GEngine->Exec(World, *Command, FStringOutputDevice)` (captures output). Allowlist-verb gate + approval + high-risk audit for non-allowlisted. | Run an allowlisted command (e.g. `stat unit`); confirm the captured output lines match the editor console. A non-allowlisted command without approval must be refused. |
| `unreal.sequencer.list` | `ULevelSequenceEditorBlueprintLibrary` / asset-registry enumeration of `ULevelSequence`. | Run with a fixture Level Sequence; confirm the listed sequences + bound tracks match the Sequencer. |
| `unreal.sequencer.open` / `unreal.sequencer.set_frame` / `unreal.sequencer.play` | `ULevelSequenceEditorBlueprintLibrary` (open editor, set playhead, play) — a loaded editor with the Sequencer module. | Open the fixture sequence; set a frame and confirm the playhead; play and confirm transport. |
| `unreal.status.query` | `GShaderCompilingManager->GetNumRemainingJobs()` / `IsCompiling()`; `GetDerivedDataCacheRef()`; `IAssetRegistry::IsLoadingAssets()`; `ISourceControlModule::Get().GetProvider().GetState(...)`. Honest `unavailable` when SCM is off. | Trigger a shader recompile; confirm the command reports the live remaining-jobs count and that source-control state matches the provider. |
| `unreal.diagnostics.bundle` | `FPlatformOutputDevices::GetAbsoluteLogFilename()` + `FFileHelper::LoadFileToStringArray`; crash dirs under `FPaths::ProjectSavedDir()/Crashes`; `FEngineVersion::Current()`; live session counters (`GBellonaCommandsHandled/Succeeded/Failed`) + `FPlatformTime::Seconds()` uptime; whole-body SHA-256 `integrityHash`; home-path + sensitive-key redaction. | Run after exercising commands; confirm the bundled log tail + counters reflect this editor session and the integrity hash verifies. |

---

## Group B — live interactive viewport required (screenshot)

| Command | Live UE API it calls (why it needs a viewport) | How to verify on hardware |
| --- | --- | --- |
| `unreal.viewport.screenshot` | `GEditor->GetActiveViewport()`; `GetHighResScreenshotConfig().SetResolution/SetHDRCapture/FilenameOverride`; `FScreenshotRequest::RequestScreenshot(path, …)`; `ActiveViewport->TakeHighResScreenShot()`. Optional camera pilot via `GEditor->GetLevelViewportClients()` + `SetActorLock`. **With no interactive viewport it returns `status: "placeholder"` (no fabricated image).** | In a live editor with an open viewport, run the command; confirm the PNG is written to the output path (`FPaths::FileExists`), at the requested resolution, showing the expected camera framing. A headless `-run=…` commandlet has no viewport and must return the placeholder. |

---

## Group C — GPU + rendering context required (Movie Render Queue)

All MRQ commands allocate a job on `UMoviePipelineQueueSubsystem` and render with
the PIE executor; the actual frame rasterization needs a GPU + render context.

| Command | Live UE API it calls (why it needs a GPU) | How to verify on hardware |
| --- | --- | --- |
| `unreal.render.create_job` | `GEditor->GetEditorSubsystem<UMoviePipelineQueueSubsystem>()` → `GetQueue()->AllocateNewJob(UMoviePipelineExecutorJob)`; sets `Job->Sequence` / `Job->Map`; config via `UMoviePipelinePrimaryConfig` + `UMoviePipelineOutputSetting` / `UMoviePipelineDeferredPassBase` / `UMoviePipelineImageSequenceOutput_PNG`. | On a GPU rig, create a job for the fixture sequence; confirm the job appears in the MRQ with the expected output settings. |
| `unreal.sequencer.render_preview` / `unreal.render.launch` | `UMoviePipelineQueueSubsystem::RenderQueueWithExecutor(UMoviePipelinePIEExecutor)`. | Launch the render; confirm frames rasterize to the output dir. This cannot run on a headless no-GPU box. |
| `unreal.render.progress` | `Executor->IsRendering()`. Reports `queued` (not a fabricated success) when no executor is active. | While rendering, poll progress; confirm it reflects the live executor. |
| `unreal.render.cancel` | `GetActiveExecutor()` → `CancelAllJobs()`. | Cancel a running render; confirm the executor stops. |
| `unreal.render.collect_output` | `IFileManager::FindFilesRecursive` over the output dir + SHA-256 per artifact (classifies `png/exr → frame`, `mov/mp4 → movie`). | After a render, collect output; confirm the frame files + per-frame hashes match the produced files. |

---

## Group D — play session required (Play-In-Editor)

All use the `GUnrealEd` global and need a running PIE world.

| Command | Live UE API it calls (why it needs PIE) | How to verify on hardware |
| --- | --- | --- |
| `unreal.pie.start` | `GUnrealEd->RequestPlaySession(FRequestPlaySessionParams{ WorldType = PlayInEditor/SimulateInEditor })` + `StartQueuedPlaySessionRequest()`. | Start PIE; confirm the play world begins and the state reports `playing`/`simulating`. |
| `unreal.pie.stop` | `GUnrealEd->RequestEndPlayMap()` when `PlayWorld != nullptr`. | Stop PIE; confirm the editor returns to edit mode. |
| `unreal.pie.eject` | `GUnrealEd->RequestToggleBetweenPIEandSIE()`. | During PIE, eject; confirm the toggle to Simulate. |
| `unreal.pie.state` | Read-only `GUnrealEd->PlayWorld` + `bIsSimulatingInEditor`. | Confirm `not-running`/`playing`/`simulating` matches the editor. |
| `unreal.pie.inject_input` | `PlayWorld->GetFirstPlayerController()` → `InputKey(FInputKeyParams)` / `InputAxis(FKey, value, …)`. **Privileged: refuses without `__approvalRequestId`**, high-risk audited; reports `injected: false` + reason if no live PIE controller. | During PIE with a granted approval, inject a key/axis; confirm the controller responds in the play session. |

---

## Group E — platform SDK + RunUAT required (build / cook / package)

| Command | Live UE API / toolchain (why it needs a cook rig) | How to verify on hardware |
| --- | --- | --- |
| `unreal.build.run` | Builds the **real `RunUAT BuildCookRun` argument vector** (`-project=`, `-platform=`, `-clientconfig=`, `-build`/`-nocompile`, `-cook`, `-allmaps`/`-map=`, `-stage`, `-pak`, `-archive`, `-unattended`, `-noP4`, …) with `FPaths::GetProjectFilePath()` + `EngineDir()/Build/BatchFiles/RunUAT.sh`. **The editor does not fork RunUAT itself — `runUatExecutedByEditor: false`**; the host job runner spawns it. | On a rig with the target platform SDK, run the returned `RunUAT` command; confirm the cook/package completes and the output appears in the staging directory. |
| `unreal.build.progress` / `unreal.build.cancel` | No live editor API (the UAT process is host-owned); returns `queued` / `cancelled`, deferring terminal state to the host job queue. | Drive against a real host-spawned UAT job; confirm progress/cancel reflect the process. |
| `unreal.build.collect_output` | `IFileManager::FindFilesRecursive` + SHA-256 per artifact (`pak/utoc/ucas/zip → archive`, `uasset/umap → cooked-package`, `log → log`). | After a cook, collect output; confirm the cooked/packaged artifacts + hashes match the staging dir. |

---

## Group F — Virtual Production / Live Link source required

| Command | Live UE API it calls (why it needs a VP source) | How to verify on hardware |
| --- | --- | --- |
| `unreal.vp.status` | Live Link via `IModularFeatures::Get().GetModularFeature<ILiveLinkClient>(...)`; `GetSubjects` + `EvaluateFrame_AnyThread(subject, ULiveLinkCameraRole/ULiveLinkTransformRole, …)` → `FLiveLinkCameraFrameData` (Transform/FOV/FocalLength/FocusDistance/Aperture). nDisplay via `IPluginManager::FindPlugin("nDisplay")->IsEnabled()`. stageMonitor delegates to the viewport screenshot (Group B). **No Live Link client → `status: "not-configured"`; no nDisplay → `not-available` with reason (honest absence).** | With a Live Link source streaming a camera/transform subject, run the command; confirm the subjects + evaluated frame data match the Live Link panel. Without a source, confirm the honest `not-configured`. |

---

## Group H — mixed benchmark (real timing; GPU/cook/PIE ops skipped honestly)

| Command | Live UE API it calls | How to verify on hardware |
| --- | --- | --- |
| `unreal.benchmark.run` | Real timing with `FPlatformTime::Seconds()` (p50/min/max/mean from measured samples). `world-query` times `TActorIterator<AActor>`; `actor-mutation` times `SpawnActorFromClass → SetActorLocation → DestroyActor`; `asset-import` times `IAssetRegistry::GetAssetsByPath("/Game")`. **`screenshot-capture` / `render-job` / `build-command` return `status: "skipped"`** (need a viewport / launched render / cook the host owns — no fabricated timings). | On a live editor, run the benchmark; confirm the world/actor/asset ops report measured timings and the GPU/cook ops report `skipped` with reasons. On a full GPU + cook rig, drive those ops through their own commands (Groups B/C/E) for real timings. |

---

## Command coverage cross-check

Every command listed above is owned by the protocol (`commandName` literals in
`libs/bellona/remote-protocol/src/unreal.ts`, and `unreal.vp.status` in the
sibling `live-link.ts` re-exported by `unreal.ts`). The full surface
(`180.C.23` + `180.C.24`):

- **Group A (loaded editor world):** `unreal.map.list`, `unreal.map.open`,
  `unreal.map.save`, `unreal.map.create`, `unreal.actor.select`,
  `unreal.actor.set_transform`, `unreal.actor.set_property`,
  `unreal.actor.attach`, `unreal.actor.destroy`,
  `unreal.blueprint.call_function`, `unreal.material.set_parameter`,
  `unreal.asset.import`, `unreal.asset.reimport`, `unreal.asset.find`,
  `unreal.asset.rename`, `unreal.asset.move`, `unreal.asset.delete`,
  `unreal.asset.fixup_redirectors`, `unreal.console.execute`,
  `unreal.sequencer.list`, `unreal.sequencer.open`, `unreal.sequencer.set_frame`,
  `unreal.sequencer.play`, `unreal.status.query`, `unreal.diagnostics.bundle`.
- **Group B (viewport):** `unreal.viewport.screenshot`.
- **Group C (GPU / MRQ):** `unreal.sequencer.render_preview`,
  `unreal.render.create_job`, `unreal.render.launch`, `unreal.render.progress`,
  `unreal.render.cancel`, `unreal.render.collect_output`.
- **Group D (PIE):** `unreal.pie.start`, `unreal.pie.stop`, `unreal.pie.eject`,
  `unreal.pie.state`, `unreal.pie.inject_input`.
- **Group E (cook / RunUAT):** `unreal.build.run`, `unreal.build.progress`,
  `unreal.build.cancel`, `unreal.build.collect_output`.
- **Group F (Virtual Production):** `unreal.vp.status`.
- **Group H (mixed benchmark):** `unreal.benchmark.run`.

The read-only discovery commands `unreal.project.info`, `unreal.world.query`, and
the safe `unreal.actor.spawn` (`180.C.15.07`) are already exercised by the
adapter discovery tests; they need only a loaded editor for live confirmation of
the project / world / spawned-actor data and follow the Group A pattern.

Do not collapse unverified live-editor behaviour into a generic "Unreal commands
passed" statement. The evidence file must say exactly which commands were proven,
on which rig, under which engine version, and by which verification mode
(headless / live-editor / GPU-render / cook / PIE / VP).
