VoxelForge/Standalone/UNREAL_INTEGRATION_REPORT.md

# Unreal Core integration report — rounds 2–3

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

The initial sections preserve the round-2 integration baseline. The round-3 addendum records the
owner's visual findings and current status, superseding earlier statements where indicated.

## 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.
- At the end of round 2, Core mode's legacy biome query returned empty because Core exposed no biome
  query API. Round 3 adds a Core-mode query through the copied owner biome evaluator; it does not add
  biome terrain or decorations to the Core field. `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.

## Round 3 — owner visual report, classification, and fixes (2026-10-08)

The owner had already built the plugin in his own game and confirmed that the Core toggle worked and
performance looked fine. I compared the four small images in `Standalone/owner_shots/unreal_core_r2/`
with owner-field and shape-world viewer modes at the B and surface locations, checked the owner's
`BuildOriginLandingGeometry`/passage definitions, and extended the BuildHost actor proof to inspect
desired keys, hashes, meshes, and LOD faces. Viewer comparisons were captured before the geometry
correction; the final test recompiled the corrected field in BuildHost.

| Reported defect | Standalone and layout evidence | Unreal Core headless evidence | Classification and outcome |
|---|---|---|---|
| 1. Capsule rings at the city/surface opening | Owner passage is a short entry into a finite origin room. Core shape-world instead added a segmented 256-voxel bore; owner-field mode has no such continuation. | Room center `+4.125` (air); floor below center and side `-4.125` (solid); above floor center and side `+4.125` (air). | **(ii) Core world defect, also visible in shape-world. Fixed.** Removed the synthetic bore and added the finite room/floor. |
| 2. Bore continues through a normal cave room | Owner layout ends the entry at the room; no shaft continues through it or into the lower seal. The same Core bore passed through it. | 32 voxels below the room floor samples `-4.125` (solid). | **(ii) Core world defect, also visible in shape-world. Fixed.** |
| 3. B-side landing has jagged/sawtooth edges | At B, owner-field and shape-world fields differ: Core shows a smooth cavern/floor while owner reference has the authored landing/terrain form. The landing is in the lower biome/SurfaceWorld portion of the layout. | All expected 2,553 visual keys load and match standalone hashes. B travel compiled 960 fine tiles; 3,438 neighbour faces checked, including 432 LOD-transition faces; no expected visual key is missing. | **(iii) Missing Core SurfaceWorld/biome representation is best supported.** The suspected missing-neighbour/LOD coverage fault is absent at the tested pose. Null-render headless testing cannot rule out a final RMC presentation artifact; owner should recheck after rebuild. |
| 4a. Surface strate is not surfacy | Shape-world viewer lacks the owner's biome-composed SurfaceWorld; owner-field mode shows rolling biome terrain. The owner separately confirmed the surface strate type is absent in his viewer. | Core query reports `Biome_Surface_Plain`, index 2, but geometry remains the Core shape field. | **(iii) Missing Core feature: biome terrain. Not implemented this round.** Cheap biome query is implemented. |
| 4b. Coarse shapes may not page detail | Hypothesis: travel failed to trigger fine compilation. Standalone Core uses the same clipmap policy. | Surface travel compiled 640 fine tiles. Visual set and tile hashes match standalone; 3,588 neighbour faces checked, including 448 LOD-transition faces, with no missing expected visual key. | **(i) Unreal paging bug not reproduced.** `StartPendingCoreRegionCompile` paged detail at the tested location. Extra loaded keys included collision-only/stale support; validator filters these and proves the exact visual set. |

### Changes and hashes

- `Standalone/Core/src/ShapeWorldInternal.h`: add the owner-layout finite origin room/floor per
  strate, remove the synthetic long surface-entry bore, and ignore invalid/default passage landing
  descriptors that made tiny false landings.
- `Source/VoxelForge/Private/VoxelWorld.cpp`: Core-mode `GetBiomeAtWorldLocation` now calls the
  copied owner biome evaluator using its authored 12.5 cm query scale. Core terrain still uses 25 cm
  voxels; the exception is local to this legacy biome query.
- `Source/VoxelForgeEditor/Private/VoxelForgeExploreCommandlet.cpp` and
  `Tools/TestVoxelForgeCoreWorldHost.ps1`: probe the room/floor, W1/W8/W16 determinism, travel to B
  and surface, exact visual keys/hashes, LOD face coverage, fine compilation, and biome result.

The corrected world intentionally changes the four aggregate hashes. W1/W8/W16 initial clipmap
results are identical:

| Hash | New value | R2 value |
|---|---:|---:|
| Density | `0xa8bcb72d41092503` | `0xdb2991c73215af4c` |
| Mesh | `0x90f29ba15e24579f` | `0x8236c5edd7fc8e4f` |
| Payload | `0x82c6b489e7bb7fd7` | `0x4c48fa75a543d58e` |
| Topology | `0x7b99448a1f844f2c` | `0xbea22e76b34a4dfc` |

B travel hashes: density `0x02ffd603879b7fdc`, mesh `0xde3bfc6069854070`, payload
`0x14f98868de7986c5`, topology `0xdf960f8a26aafdc0`. Surface travel hashes: density
`0x7f878c0933972c7f`, mesh `0x18d63306f5215f10`, payload `0x18b6e682e2a17505`, topology
`0xe89da4150dc053c9`. At surface `desired=2553`, while actor `loaded=3334` includes support/stale
keys during the move. The validator filters collision-only support, then proves every expected visual
key and hash; it does not claim support-set quiescence.

### Biome design proposal

Recommended direction: add a deterministic `SurfaceWorld` evaluator to the Core shape-world model,
fed by resolved biome definitions, surface-generation parameters, and fixed-order noise. Keep biome
identity/blend selection in the immutable worker snapshot and add per-column height/biome caching so
mesh samples reuse height work. This makes the surface, biome query, and decoration inputs one pure
field. The port is medium-to-large work. Uncached per-sample biome/noise could slow detail tiles;
column caching bounds the added cost. Determinism is straightforward to preserve with fixed coordinate
hashing/math and worker-count hash tests.

Routing only SurfaceWorld strates through the copied legacy `UVoxelGenerator` in Core is a smaller
compatibility bridge with higher immediate visual fidelity. It likely costs about the legacy field
evaluation per sample, duplicates a second field implementation, and inherits legacy float/platform
behavior. It should be checked across worker counts and platforms. A better staged design is an
explicit strate-evaluator interface: use the port long-term and allow the copied evaluator as a
temporary per-strate fallback when exact behavior is needed earlier. This round implemented the cheap
biome query only; a full biome surface port did not fit alongside the geometry and streaming checks.

### BuildHost outcome and run ledger

`Tools/BuildVoxelForgeCoreHost.ps1` and `Tools/TestVoxelForgeCoreWorldHost.ps1 -TimeoutSeconds 900`
passed. The actor test reported `streaming=1 collision=1 anchor_move=1 carve=1`; peak commandlet
private memory was 2,997,526,528 bytes (about 2.8 GiB). No step exceeded 15 minutes, no `0xC0000142`
retry occurred, and no new UECC folder appeared. The requested `Saved/BuildHost/HostProject/Saved/Crashes/`
contained only its prior crash folder.

| Round-3 attempt | Outcome |
|---|---|
| First standalone viewer capture invocation | Failed because an owner-data path with spaces was passed in the wrong form. Corrected auto-discovery invocation produced all four Core/owner B/surface captures with exit 0. |
| `Standalone/Build.ps1 -Target All` | Core library built and symbol audit passed; viewer link failed on 12 unresolved `VoxelForgeGpuFarViewer` symbols because the script omits `GpuFieldPort.cpp`. Canonical build files were left unchanged. |
| First expanded surface actor test | Manually stopped after repeated collision-only region compiles prevented the overly broad settled-state condition from completing. Narrowed the test to expected visual keys/hashes; final run passed. No new UECC. |
| Origin-room sign assertion | Failed quickly because expected signs were reversed. Core uses positive=air and negative=solid; corrected assertion passed. |
| Intermediate commandlet builds | One failed on non-exported `GetEffectiveOriginSpineRadius`; another used protected `OriginSpineRadius`. Harness now computes effective radius from settings/season data. Later UBT builds passed. |
| Final UBT and Core world test | Passed W1/W8/W16 hashes, origin floor, B/surface coverage and paging, biome query, anchor movement, collision, and carve markers. |

After the owner's rebuild, with **Use VoxelForge Core** enabled, inspect these exact places:

1. At the city/surface opening, confirm one short entry reaches a finite rounded room without capsule
   rings; stand on the floor and confirm it is flat and walkable.
2. Continue into the normal cave room and look down: the entry should not continue as a deep shaft.
3. Walk through the A→B landing to the B side. Check whether jagged edges/sky gaps remain after
   nearby tiles settle. Headless key and LOD coverage is complete; a remaining artifact needs a
   screenshot from this same view to isolate final mesh presentation.
4. Travel to the surface strate. Wait for coarse-to-fine transition and confirm nearby detail appears.
   The biome query identifies `Biome_Surface_Plain`, but biome-driven surface geometry is still
   missing, so the broad surface terrain should not yet be judged as fixed.

Switch-off continues through the legacy generator. The owner rebuild/editor review is the remaining
visual check.