VoxelForge/Standalone/Research/WorldAssemblerM3/Research27/first-pass.md

# VoxelForge R27 — water MVP research

## What exists

- **Core:** `BuildSurfaceStratumPlan` resolves one fixed water level and enable flag per stratum. `Heightfield2D::point` returns `waterSurfaceSubvoxels` and, for evaluator v2+, a `waterFillSubvoxels` value only in open space between the local ground and that level. It is a useful starting channel, but it describes a stratum-wide vertical fill; there are no pool or stream records. [`WorldAssemblyStratumPlanV1` and sample fields](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:560>), [`BuildSurfaceStratumPlan`](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp:320>), [`Heightfield2D::point`](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/WorldAssemblerInternal.h:2576>)

- **Bounds and meshing:** Core’s `FieldInterval` bounds density, not water; it has no water interval query or water-body BVH. The Core contract mentions a water channel, but the current bounds do not cover it. The existing terrain mesh and collision paths are density based, so water needs its own surface-mesh path. [`FieldInterval`](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:1301>), [Core interval contract](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/API.md:120>)

- **Unreal:** `UVoxelContentManager::UpdateWater` uses the player’s stratum water level to place one large, movable `/Engine/BasicShapes/Plane` at the player’s snapped cell, scaled to cover the view. The component has collision disabled and uses the stratum’s `WaterMaterial`. `AVoxelWorld::Tick` calls it each tick. The asset comment explicitly describes water as aesthetic, with no swim or flow simulation. [`UpdateWater`](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelContentManager.cpp:2499>), [`WaterMaterial` and water settings](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Public/VoxelStrateDefinition.h:211>), [tick call](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelWorld.cpp:7038>)

- **Reusable pieces:** retain Core’s fixed-point sampling, stratum water datum, `WaterMaterial`/`WaterColor`, and the terrain bed’s normal collision. Replace the global plane for this profile with a local water-body renderer. Legacy `Underwater` currently builds the same tunnel density stack as `TunnelNetwork`; its water flag is consumed on the rendering side. The atmosphere manager provides fog and skylight, but I found no water-specific swim handling or underwater post-processing. [`Underwater` dispatch](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelGenerator.cpp:2638>), [`ApplyFogSky`](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelAtmosphereManager.cpp:127>)

## Design

Resolve the terrain and mouth route first. At plan time, trace a deterministic steepest-descent path from a chosen source toward the pool across the resolved surface, then store the result as a fixed polyline or spline. Use Core’s integer coordinates, fixed sampling steps and tie-breaking order; if descent reaches a local minimum, use a deterministic path search to the basin. Store the resolved path, elevations, width and stable body ID in the plan so clients can reproduce or receive the same geometry. This honors the earlier downhill-path preference without simulating water.

Carve a shallow channel along that path, joining it into a basin with a **flat, fixed pool surface**. As initial design ranges, try a 1–2 m stream, a bed about 0.3–0.5 m below adjacent ground, and 0.15–0.3 m of water over the bed. The pool can start in R24’s 4–12 m radius and 0.3–1 m depth range; the shoreline is where the surrounding bank meets the fixed surface. Make stream elevation descend into the pool and record a stable downstream direction for its material. [R24 water proposal](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research24/REPORT.md:25>), [R20 pool dimensions and route guidance](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research20/REPORT.md:133>)

Add a separate positive-inside occupancy field `W` for the pool and stream. Return occupancy and local surface height per query, independently of rock density. Give water its own conservative interval query and BVH over body bounds; use those bounds to schedule water-only tiles even where the rock field classifies as air. Emit a separate water surface mesh from the body records or water field. The density mesher should continue to own rock geometry and collision. This follows R24’s proposed pool/stream records and water-specific tile scheduling. [R24 records and mesh proposal](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research24/REPORT.md:27>)

Comparable games offer different scopes; these references describe player-facing behavior, not necessarily their internal representations:

- **Minecraft** treats water as blocks that spread into adjacent air; its generated rivers are calm and held at sea level. That is a useful example of authored water bodies without visible flow simulation. [Water](https://www.minecraft.net/en-us/article/block-week-water), [Rivers](https://www.minecraft.net/en-us/article/around-block--river)
- **Astroneer:** official material I found describes fluid canisters and a simulated aquarium that needs no water; separate **STARSEEKER** material advertises swimming and diving. I found no official outdoor river or pool system for mainline Astroneer. [Megatech notes](https://blog.astroneer.space/patch-notes/megatech-update/), [STARSEEKER overview](https://blog.astroneer.space/p/starseeker-direct-recap/)
- **Enshrouded** is the full-simulation comparison: its 2025 update adds dynamic water, flow redirection, swimming, diving and oxygen gameplay. That is well beyond this static MVP. [Wake of the Water](https://enshrouded.com/en-US/news/enshrouded-wake-of-the-water-update)
- **Valheim** uses water as world traversal, including sailing; official patch notes also track water VFX and water damage. Those notes do not document its rendering implementation. [Official FAQ](https://www.valheimgame.com/faq/), [Patch 1.0.14](https://www.valheimgame.com/news/patch-1-0-14/)
- **No Man’s Sky** is a richer presentation reference: its official notes describe enhanced water rendering, waves, deep-water hazards and underwater effects. [Worlds Part II](https://www.nomanssky.com/worlds-part-ii-update/), [The Abyss](https://www.nomanssky.com/abyss-update/)
- **Deep Rock Galactic** presents frozen lakes as slippery environmental hazards, a useful cave-navigation comparison rather than a flowing-water model. [Official updates](https://www.deeprockgalactic.com/updatesold)

## Unreal minimum

Use local pool and stream surface meshes with the existing water material as a starting point, plus visible bed, bank and shoreline geometry to establish depth. Add restrained reflection/Fresnel, water tint and depth cues; keep directional flow cues stable and avoid strong animated motion in VR.

Keep the water surface non-colliding. The carved terrain bed remains the walking collision. Add a query-only water volume for immersion state; if the pool is deep enough to swim in, that volume can also switch character movement to swimming. Apply a subtle underwater post-process when the player’s camera is inside the body and below its surface. If the MVP stays shallow, swimming and underwater effects can wait.

Unreal’s Water plugin documents separate spline-defined water bodies, generated surface meshes, depth/flow queries and underwater post-processing. Its automatic terrain carving is Landscape-brush based, so it would not replace the Core bed and occupancy work here. [Water System](https://dev.epicgames.com/documentation/unreal-engine/water-system-in-unreal-engine), [Water Body Actors](https://dev.epicgames.com/documentation/en-us/unreal-engine/water-body-actors-in-unreal-engine)

## Walkability

Keep the mouth-to-mouth capsule route supported and never dependent on swimming. Core already audits a 0.34 m radius, 1.76 m high capsule, support and a 15° maximum grade, but that audit does not evaluate water depth. Extend the route checks to the water channel. A ford can be allowed where water over the walking bed is at most about **0.3 m**; any deeper crossing needs a dry bypass or bridge. [Route audit contract](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/API.md:140>)

## Slices and evidence

1. **Core records:** Add stable pool/stream records, occupancy and surface queries, intervals and BVH. Verify determinism and bounds; capture a diagnostic cross-section showing water and rock separately.
2. **Carved bed:** Add the channel and basin to the resolved terrain. Verify bank/shoreline shape, capsule support and grade; capture an oblique view and a cutaway.
3. **Water mesh:** Generate the pool and stream surfaces separately from density, including water-only tiles. Verify body bounds and tile joins; capture the whole source-to-pool view, shoreline and ford/bridge.
4. **Unreal:** Add local rendering, immersion volumes and optional underwater presentation. Check host/client agreement; capture eye-level, waterline and underwater views where applicable.

No scripts, tests, builds, binaries or edits were made.

**Reference image:** I could not find an image under `Docs`; that directory contains archived Markdown only. The nearest file is [owner_normals_pool_before.png](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/data/owner_normals_pool_before.png), an older global-plane capture rather than a local stream-to-pool reference.

## Owner questions

- Should the first pool remain wadeable at ≤0.3 m, or should the MVP include swimming and underwater post-processing?
- Can you point me to the missing `Docs` reference image or restore it in this checkout?