VoxelForge/Standalone/UNREAL_INTEGRATION_REPORT.md

Unreal Core integration report — round 2

Date: 2026-10-08
Branch: unreal/core-integration

Result

Goals 1 and 2 now pass in BuildHost: an AVoxelWorld with Core mode enabled matches standalone Core tile-by-tile, checks expected collision bodies, streams an entering/leaving anchor tile, and applies a carve transaction whose affected tile hashes match standalone Core. Goal 3 has a narrow legacy generator baseline pass; it does not instantiate an actor with Core disabled, so that result is not an actor-level A/B comparison. The owner can now try the opt-in switch in their editor after building the plugin.

Core remains opt-in (bUseVoxelForgeCore=false by default). Core mode owns separate clip settings (radius 3, max level 8), uses 25 cm Core voxels and Core tile keys, and routes mesh payloads through the existing RealtimeMesh/collision path. No Core canonical source or owner asset was edited.

Headless AVoxelWorld evidence

Tools/TestVoxelForgeCoreWorldHost.ps1 stages the current plugin and the five copied owner world assets into BuildHost, builds the Unreal modules, and runs VoxelForgeExplore -coreworldtest=1. The commandlet resolves the staged settings/strate data and spawns a transient AVoxelWorld with Core mode enabled.

• Initial desired set: 2,226 tiles. Density, mesh, payload, topology, triangle, empty-tile and per-tile hashes match the standalone Core reference. Aggregate hashes are density 0xd528cf02858dd01d, mesh 0x747c531b4499a9a6, payload 0x5d38ea99f9c2cad0, topology 0xd9974b32dc47fc8d.
• Collision: the expected set is 125 level-0 tiles (a 5×5×5 box); all expected non-empty tiles have cooked bodies (58), and all 67 expected empty tiles are explicitly checked as no-body. The final log reports collision_ready=58; collision_no_body=318 is the actor's global no-body bookkeeping count, not the expected-box count.
• Anchor: moving the CollisionOnly anchor from Core tile (20,0,0) to (21,0,0) requests one entering tile and releases one leaving tile. FullVisual follows the same reconciliation path but has no independent assertion in this harness.
• Carve: sequence 1, digest 0xa1d628d0de1a6824, four affected keys. The carved LOD0 tile (-1,-1,-1) hashes to 0x633f3488c0800734; every affected tile is compared to standalone Core after applying the same transaction.
• Peak process memory: 2,881,925,120 bytes (approximately 2.68 GiB), below the 8 GiB cap. The run completed in seconds, below the 15-minute stop limit.

The mesh bridge copies Core vertex positions directly: the Core API returns vertices in centimetres. Inputs to Core (player/anchor/query/edit positions and brush dimensions) use 25 cm voxel conversion; high-level brush radii/extents/falloff that came from legacy 12.5 cm voxel units are multiplied by 12.5/25 to preserve their physical size. ApplyModification low-level callers supply active Core voxel units.

Switch-off baseline

The selected narrow existing test was VoxelForge.Determinism.CrossPlatformDigest, run from Tools/VoxelForgeTest.ps1 against the staged BuildHost plugin. Unreal's automation result passed with exit 0: 115,000 legacy samples, shape digest 0xB9F6E034156BDB7A, field digest 0x212DA316FBBA4401, 86,901 solid, 28,099 air, and zero NaNs. The wrapper marked its overall run failed because Unreal wrote analytics files under C:\Users\Jahni\AppData\Local\UnrealEngine\common\analytics despite the isolated user-data path and bSendUsageData=false. This was an incidental external profile write; I did not alter or remove it. The raw automation result is a legacy baseline, not a direct assertion that an actor with bUseVoxelForgeCore=false is byte-for-byte unchanged.

Files and architecture

• Source/VoxelForgeCore/VoxelForgeCore.Build.cs defines the runtime module. It validates the canonical manifest and shim inventory, uses C++20/precise FP with no PCH or unity, and exposes only Standalone/Core/include publicly.
• Source/VoxelForgeCore/Private/Manifest/ contains one include shim for each of the 18 rows in Standalone/Core/core_sources.txt. Canonical source files remain under Standalone/.
• Source/VoxelForgeCore/Private/ModuleEntry/ supplies the Unreal module entry and the isolated include of the engine CoreMinimal.h.
• VoxelForge.Build.cs and VoxelForgeEditor.Build.cs depend on VoxelForgeCore.
• Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h defines the empty standalone export macro and the UBT module export macro. No Core generation logic changed in this round.
• Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp and Source/VoxelForge/Public/VoxelForgeCoreAssetAdapter.h serialize resolved assets into schema-v1 values without passing UObjects to Core workers.
• Source/VoxelForge/Private/VoxelWorld.cpp and Public/VoxelWorld.h contain the opt-in route, Unreal task scheduler, Core tile-key/scale bridge, MPSC/epoch handling, anchor integration, and transaction edits. VoxelForgeExploreCommandlet.cpp contains the BuildHost actor proof.
• The commandlet adapter's compile scheduler still exercises the standalone compiler at worker limits 1/8/16; the runtime scheduler is the separate Unreal-task implementation above.

BuildHost evidence

Tools/BuildVoxelForgeCoreHost.ps1 stages plugin source and copied owner assets only under Saved/BuildHost/HostProject. The final UBT run completed successfully:

• UnrealEditor-VoxelForgeCore.dll and UnrealEditor-VoxelForge.dll linked in UnrealEditor Win64 Development.
• All 18 expected Core shim objects were found and audited.
• CheckCoreSymbols.ps1 reported CORE_LINK_SAFETY_PASS: 83,843 dumpbin symbol lines checked against 399 copied Unreal-style type names, with no conflicts.
• Five staged asset copies matched their source SHA-256 values:

Asset	SHA-256
DA_Settings	5D2977F57E75A63B6B73499CD6E0AA7FBBF3718CE7F70318107BF922F0819AB7
DA_Strate1	CDA1F985E589F28CA6E93A068FECC3CA92487E4AD5700F2C301C4B563E40E5F9
DA_Strate2	02F56A18CED991BAF93DFB2F69438152275E8353B5E279C1CB7DD6E079E352E2
DA_Strate3	F47437F8D156C608AA06E40C5B76716ED4A19FA0F057688E7FECC04DC976428C
DA_Strate4	279570AE3CBA7B3507269C8209A7C931EEB7A15CC3241CE07B50120996B1C656

The final logs are Saved/BuildHost/UBT-CoreIntegration.log and Saved/BuildHost/VoxelForgeCore_ue_link_safety.log.

Headless adapter evidence

Tools/TestVoxelForgeCoreAdapterHost.ps1 launches the isolated BuildHost Unreal commandlet at Normal priority. It sampled about 4.30 GiB private memory, below the 8 GiB limit. The generated JSON is retained at Saved/BuildHost/HostProject/Plugins/VoxelForge/Saved/CoreAdapterValidation/Output/owner_world.json; the commandlet log is beside it under Logs/CoreAdapterValidation.log.

For Core compile worker limits 1, 8, and 16, the validator then generated and hashed the 2,226 desired tiles serially. Each pass matched:

Hash	Expected / actual
Density	0xdb2991c73215af4c
Mesh	0x8236c5edd7fc8e4f
Payload	0x4c48fa75a543d58e
Topology	0xbea22e76b34a4dfc
Passage walkability	5,642 / 5,642

The adapter first parses the unmodified asset-derived export. The test then reparses a validation copy with the standalone CPU benchmark view settings clip_radius=3 and max_clip_level=8. The final export itself retains the asset values.

Owner hand-off and known limits

• The staged DA_Settings exports ClipRadius=6 and MaxClipLevel=6; the standalone owner JSON has clip_radius=6 and max_clip_level=8. Runtime Core mode intentionally does not read the old asset clip values; its own defaults are radius 3 and max level 8. The adapter parity test preserves the source export and applies those reference view values only to a separate validation copy.
• In the owner's Unreal editor, select the AVoxelWorld actor and enable Voxel World | Core | Use VoxelForge Core in Details. Leave Core Clip Radius = 3 and Core Max Clip Level = 8 for the first check. Save the level only if the owner wants to keep the actor setting. With the world running, expect Core terrain to stream around the player, solid LOD0 terrain to block movement, and the existing carve entry points to create a deterministic hole. Disable the switch to return to the legacy route.
• BuildHost UBT compiled the current runtime and editor modules. If the owner's editor reports a compile error, the likely integration seams to inspect first are the new reflected properties in VoxelWorld.h (UHT), the Core module dependency in VoxelForge.Build.cs, the Core/RealtimeMesh bridge in VoxelWorld.cpp, and the editor-only commandlet code. No owner-editor build was run.
• The commandlet warns that /Game/VoxelForge/Blocks/NewDataAsset is missing. /Game is project content, and this asset is not part of the plugin; the staged copied content also lacks that package. It did not prevent schema resolution, hash checks, or walkability. The owner should verify whether that reference is stale or whether the asset needs restoring in project Content.
• Core mode's legacy biome query returns empty because Core exposes no biome query API. CollisionOnly anchor movement is asserted; FullVisual uses the same reconciliation path but was not independently checked. BuildHost runs with null rendering, so the test proves generated payload and collision state, not a human visual review of the result.
• Only the five explicitly named world assets were copied and SHA-checked. No owner editor was opened, and no owner project build or asset write was performed.

Failed runs, retries, and crashes

No build or test exceeded the 15-minute limit. No process returned 0xC0000142, so no automatic retry was used. One new UECC-Windows-7B23387E4235BCFEDE42BC9D637E41CB_0000 was written under Saved/BuildHost/HostProject/Plugins/VoxelForge/Saved/CoreWorldValidation/User/Saved/Crashes/; its fatal log records duplicate WorldSettings creation in the transient actor-test world. The requested Saved/BuildHost/HostProject/Saved/Crashes/ contains only the older 2026-09-17 UECC-Windows-F1A3EFD5469F5DD62E68EBBACAC84376_0000.

The run history, including corrected failures, is:

Run	Outcome
Early UBT validation/build attempts 1–7	Failed in sequence on a shim-preamble regex, stale staged Build.cs, duplicated UHT source tree, missing API export/incorrect CoreMinimal and forwarding-header paths, malformed macro quoting, canonical C4456/C4668 warnings-as-errors, and editor-only FFilePath compat fields. Each was corrected; no source Binaries/, Intermediate/, or generated header was edited.
Initial successful BuildHost UBT runs	Passed after defining the module export macro, isolating the actual engine CoreMinimal include, and setting WITH_EDITORONLY_DATA=0. They established module links and the first symbol audit.
Adapter commandlet: first launch	Failed the commandlet's output-path guard because -out was outside the staged plugin Saved directory. The path was moved under BuildHost.
Adapter commandlet: DDC path	Exited 3 with a fatal error because the DDC path exceeded Unreal's 119-character limit. The staged DDC was moved to the shorter Saved/BuildHost/VFCoreAdapterDDC; no new UECC folder appeared.
Adapter commandlet: scale	Failed schema resolution with voxel_size_cm=12.5; the adapter was corrected to emit Core's standalone 25 cm scale.
Adapter commandlet: clip bounds	The original radius 6 exceeded the validation compiler's 160-million-node bound. The harness now applies the documented radius 3 override to a copy only.
Adapter commandlet: hash comparison	Generated 6,498 tiles and walkability 5,642/5,642, but hashes differed because the staged asset max level is 6 and the standalone reference is 8. The validation copy now applies max level 8.
UBT/commandlet wrapper status	Unreal logged successful results, but two Start-Process handles exposed empty exit-code fields; one commandlet fallback also looked for a marker absent from the abslog. The scripts now require UBT's Result: Succeeded or the commandlet's result 0 plus exact parity markers. Final UBT and adapter harness runs passed.
PowerShell helper checks	Two intermediate parser attempts failed while adding the UBT fallback; one parser check exposed a multiline -and in the commandlet fallback; a separate parser invocation also hit nested-shell variable expansion. These affected no Unreal run; the scripts were corrected and parsed successfully before final execution.
Staged standalone viewer build	The first launch failed before compilation because Start-Process split a path containing spaces. The corrected BuildHost run compiled the Core library and passed its symbol audit, then the viewer link failed with 12 unresolved VoxelForgeGpuFarViewer symbols: Standalone/Build.ps1 does not link the GpuFieldPort.cpp implementation still referenced by StandaloneViewer.cpp. No canonical standalone build file was edited.
Core actor commandlet: world creation	Unreal aborted on duplicate WorldSettings creation in the transient validation level. The UECC folder above contains the fatal log. World creation was changed to use the engine initialization values; the passing actor run no longer hits this fatal.
Core actor commandlet: lifecycle attempts	One run was manually stopped after BeginPlay did not run; another had no desired tiles after roughly 15,000 manual ticks. The harness was corrected to initialize actors for play, supply a transient game instance/context and GameMode, and advance GFrameCounter. Both were stopped well before 15 minutes and produced no crash.
Core actor commandlet: UBT	One quick compile failed with C2027 for incomplete AWorldSettings; adding GameFramework/WorldSettings.h fixed it.
Core world host final run	Passed after the lifecycle fixes and again after correcting high-level brush dimensions from 12.5 cm to 25 cm Core units. The pre-correction carve run also passed parity but affected 8 tiles; the final scale-correct run affects 4 and is the reported result.
RunVoxelForgeAutomationR2.ps1 switch-off attempt	Failed before launching Unreal because the expected Saved/VoxelForgeHarnessCommon.ps1 helper was absent. The later direct VoxelForgeTest.ps1 automation run executed the selected test and produced the analytics-write wrapper failure documented above.
Switch-off automation wrapper	Unreal automation itself passed VoxelForge.Determinism.CrossPlatformDigest with exit 0; the wrapper returned failure for the external common\analytics write. No retry was attempted and no crash was reported.

The standalone viewer build failure is separate from Unreal integration. The final adapter and actor passes match preserved standalone reference hashes; the Core worker-limit 1/8/16 adapter proof also retains the original passage walkability result.

Handoff status

The owner can now try the switch described above. BuildHost proves Core tile parity, expected collision-body bookkeeping, anchor entering/leaving, and transaction-based carving. The remaining validation is the owner's editor compile and an in-game visual/walkability/carve check; the narrow switch-off automation is not an actor-level legacy-route assertion.