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
superRefinepolicy 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 withoutapprovalRequired=trueand anapprovalRequestId; non-allowlistedunreal.blueprint.call_function/unreal.console.executerequire 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(theBellonaUnrealEditoreditor module). Compilation proves the handlers bind to real engine symbols (FScopedTransaction,UEditorActorSubsystem,IAssetTools,UMoviePipelineQueueSubsystem,FScreenshotRequest,GShaderCompilingManager,ISourceControlModule,ILiveLinkClient, …) — seeBellonaUnrealEditor.Build.csfor the linked module list.
Normal CI does not prove:
- a real
UnrealEditorprocess 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_stackcheckpoint 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
FScopedTransactionand callsUObject::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 explicitplaceholder/not-configured/skipped/queuedstate with a reason, rather than fabricating output. The canonical examples — which an operator should expect to see when the hardware is absent — are the screenshotplaceholder(no viewport), MRQprogress: queued(no executor rendering),runUatExecutedByEditor: false(the editor does not fork the cook), Live Linknot-configured(no VP source), and benchmarkskipped(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
.uprojectwith theBellonaUnrealEditorplugin enabled and the loopback command transport listening on127.0.0.1only; - a fixture map containing at least: one
StaticMeshActor, one camera (ACameraActor), one directional light, and oneUMaterialInstanceConstantasset under/Game/Materials; - a writable
/Game/Importedcontent path and anSources/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#
- Prove the transport first: confirm the plugin
readyendpoint answers on127.0.0.1and is authenticated, and that discovery reportsplugin.status: available. - For every mutating command, capture a before
unreal.world.query(orunreal.map.list), the command result, and an afterunreal.world.query. - For every
undo_stackcommand verified live, perform one editor Undo (Ctrl+Z) and record a post-undounreal.world.queryproving the state reverted — this is the live-editor proof CI cannot give. - For import/asset commands, capture the source byte size + SHA-256 and confirm
the result
provenance.sourceSha256is the bytes hash (the live plugin re-hashes the real file; the mock's path-hash fallback does not count). - If a command only reaches a
placeholder/not-configured/queuedstate, say so explicitly — that is honest absence, not a live proof. - If a command falls back to the mocked route (
executedAgainstLiveEditor: false), the run does not count for180.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).