feat(config): add visibility + MinCaveY fields and cave-gen docs

Core/Configuration.cs

@@ -1,9 +1,28 @@
 namespace VoxelEngine.Core;
 
+using OpenTK.Mathematics;
+
 public sealed class Configuration
 {
     public int RenderDistanceHorizontal { get; set; } = 8;
+    // Player-slab half-height in chunks. NOTE: repurposed by the visibility
+    // rework — this is no longer a global vertical load-box. It is how many
+    // chunks load above and below the player's chunk across the whole
+    // horizontal region, so caves at the player's depth render to the full
+    // horizontal distance.
     public int RenderDistanceVertical { get; set; } = 2;
+
+    // Chunks loaded below the lowest surface chunk of each column. Gives the
+    // surface chunk a solid neighbor below (so its buried bottom faces cull)
+    // and covers cave mouths just under the surface.
+    public int SurfaceShellSkirtBelow { get; set; } = 1;
+
+    // Distance fog begins at this fraction of the fog-end distance (fog end is
+    // derived from RenderDistanceHorizontal). 0.7 → fog starts at 70% of the edge.
+    public float FogStartFraction { get; set; } = 0.7f;
+
+    // Sky / clear color, also the distance-fog target color.
+    public Vector3 SkyColor { get; set; } = new(0.45f, 0.65f, 0.95f);
     public int SpawnReadyRadiusHorizontal { get; set; } = 1;
 
     public int MaxGenerateJobsInFlight { get; set; } = 8;
@@ -25,13 +44,26 @@ public sealed class Configuration
     public int? Seed { get; set; } = null;
 
     // -- Cave generation tuning --
+
+    // Spatial frequency of the 3D simplex cave-density field; higher = smaller,
+    // more frequent pockets.
     public float CaveNoiseFrequency           { get; set; } = 0.03f;
+    // Density cutoff below which a solid voxel becomes air; higher = more cave.
     public float CaveNoiseThreshold           { get; set; } = -0.3f;
+    // Edge length (blocks) of a worm-spawn grid cell; one worm candidate per cell.
     public int   WormCellSize                 { get; set; } = 64;
+    // Per-cell chance out of 1000 that a worm spawns; 300 = 30%.
     public int   WormSpawnProbabilityPermille { get; set; } = 300;
+    // Number of trace steps (≈ blocks) a worm travels.
     public int   WormMaxLength                { get; set; } = 80;
+    // Worm tunnel radius bounds; interpolated + sine-modulated along the path
+    // to form bulges/chambers.
     public float WormMinRadius                { get; set; } = 1.5f;
     public float WormMaxRadius                { get; set; } = 3.5f;
+    // Ceiling: caves carve only at or below this world-Y ("no caves above").
+    // Default 127 = world top (WorldHeight - 1) → no effective ceiling. Lower it
+    // to keep caves away from the surface (removes surface cave mouths).
+    public int   MinCaveY                     { get; set; } = 127;
 
     // -- Cave lighting (fog-distance darkness) --
     public float CaveDarkStartY    { get; set; } = 72f;   // WorldConstants.SeaLevel + 8

VoxelEngine.Tests/ConfigurationTests.cs

@@ -74,4 +74,15 @@ public class ConfigurationTests
         Assert.Equal(32f,   c.CaveDarkEndY);      // SeaLevel (64) - 32
         Assert.Equal(0.15f, c.CaveMinBrightness);
     }
+
+    [Fact]
+    public void Defaults_HaveVisibilityAndCaveCeilingConstants()
+    {
+        var c = new Configuration();
+
+        Assert.Equal(1, c.SurfaceShellSkirtBelow);
+        Assert.Equal(0.7f, c.FogStartFraction);
+        Assert.Equal(new OpenTK.Mathematics.Vector3(0.45f, 0.65f, 0.95f), c.SkyColor);
+        Assert.Equal(127, c.MinCaveY);
+    }
 }