# 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:

```powershell
.\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** |