VoxelForge/Standalone/README.md

VoxelForge standalone world

This C++20 program loads the owner snapshot from data/owner_world.json, runs the copied VoxelForge density pipeline and marching-cubes mesher, builds all clipmap levels with six worker threads, and displays them through Direct3D 11. Unreal is not linked or needed at run time.

Build and launch

From the plugin root, run:

.\Standalone\Build.ps1
.\Standalone\bin\VoxelForgeStandalone.exe

The build uses the configured VS 2022 vcvars64.bat, MSVC /std:c++20 /O2 /arch:AVX2 /fp:precise. The executable finds the JSON beside itself under Standalone\data\.

Controls

• Hold right mouse button and move to look.
• WASD moves; Space/Ctrl or E/Q moves vertically; Shift moves faster; the wheel changes speed.
• F toggles wireframe.
• 1 through 7 toggle clipmap levels 0 through 6 individually; 0 toggles every level.
• N/P changes the seed. T switches between the owner's base tunnels and the research-shaped round, winding tunnel option. Either action rebuilds the clipmap. Moving three chunks from its center also recenters and rebuilds it.
• Esc exits.

The console reports density parity at startup, each level's generation time, and the total time.

Copied code and compatibility layer

Source\VoxelForge\ contains the plugin's density evaluator and operator stack, cave morphology, passage geometry, strate definitions/layout/manager/composer, noise, voxel math and types, marching-cubes tables/mesher, and clipmap tile selection. These are copies. Plugin runtime source is untouched apart from the allowed editor commandlet export addition.

Compat\CoreMinimal.h supplies the UE-style arrays/maps/sets, vectors and boxes, math helpers, strings, smart pointers, locks, logging/stat macros, UObject-like data holders, and platform helpers needed by the copied CPU code. The Compat subfolders cover the UE include paths used by those copies. Perlin 2D/3D uses the copied UE 5.7 implementation in UnrealPerlin.cpp and UnrealPerlinHelpers.inl. OwnerWorldLoader.h maps the exported settings, resolved strate definitions, biomes, and terrain operations into copied holders; soft references resolve through a small local asset registry. The copied strate manager reconstructs runtime passages from that data and seed. The export also records their geometry in JSON for reference.

Behavior differences

• Standalone VOXEL_SIZE is 25 cm; the plugin's checked-out value remains 12.5 cm. No other voxel conversion constant needed changing. Mesh vertices stay in centimetres in the copied mesher and the viewer converts them to metres at upload.
• The compatibility TMap and TSet are vector-backed containers, so lookup is linear and their iteration follows insertion order rather than Unreal hash-table order. Owner strate slots and passages are read from ordered JSON arrays. Perlin noise and deterministic DetSinCos are copied unchanged; MSVC uses /fp:precise without fast-math/FMA contraction.
• Unreal reflection and UObject construction are replaced by explicit JSON-to-holder mapping. Density-relevant settings, resolved strate layouts, passages, biome parameters, and terrain-op assets are loaded. Runtime actor/material assets are not instantiated; the viewer uses one lit rock material for all generated geometry.
• The owner export has no active season. Standalone season loading is not implemented; an active season would need to be exported and mapped before it could affect this viewer.
• WITH_EDITOR research/debug branches, Unreal logging, startup trace, profiling counters, and reflection metadata do not run in the standalone. The base generator path is the default.
• T selects a standalone-only tunnel-shape port. It disables the owner's first-strate tunnel connections and adds the research field's cubic winding centerline and round elliptical tunnel profile (144-voxel pitch, 28-voxel radius, 26-voxel half-height, deterministic variable radius and vertical wave), anchored around the camera's current height. It reuses the base rooms and passages; it does not port the research field's room planner or full parameterized density field.

Owner data and parity

data/owner_world.json came from one default-off VoxelForgeExploreCommandlet export using the guarded Tools\VoxelForgeTest.ps1 -Scenario standalone-export -Build -Assets owner path. The snapshot contains the resolved settings/strates/passages and 3,436 plugin density samples. For that commandlet build, VOXEL_SIZE was temporarily set to 25 cm in the worktree and restored afterward; the exported JSON records 25 cm and the checked-out plugin source still records 12.5 cm.

Standalone comparison: 3,436/3,436 bit-identical, zero mismatches. Samples covered strate boundaries (2,420), varied world coordinates including negative and far-from-origin points (768), tunnel interiors (222), room interiors (12), inter-strate passages (10), and passage landings (4).

Baseline clipmap timing

Owner seed 0, base world, 25 cm voxels, six workers; the final viewer run generated the full seven-level clipmap (12,054 tiles, 6,605,189 vertices, 36,307,137 indices) in 515.117 seconds. These level timers cover CPU meshing and queue handoff; D3D11 buffer upload is separate. An earlier headless pass over the same tiles took 408.719 seconds, so use one run mode consistently when comparing later speed changes.

Level	Seconds	Tiles	Vertices	Density samples
0	70.201	2,744	957,655	117.65 M
1	65.376	2,009	657,423	86.14 M
2	9.042	1,274	292,267	8.74 M
3	25.689	588	235,755	4.03 M
4	24.248	441	229,720	3.02 M
5	23.809	294	199,503	2.02 M
6	296.304	4,704	4,032,866	32.26 M
Total	515.117	12,054	6,605,189	253.86 M