Eve library

Unreal Command Hardware And Live-Editor Verification

Guide

Revision 1

On this page

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).

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.

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).