Init

content/world/worldgen/cave-generation.en.md

@@ -0,0 +1,252 @@
+---
+title: Cave Generation
+type: docs
+weight: 2
+---
+
+The cave generation system creates underground cave networks, caverns, and subterranean features.
+
+**Package:** `com.hypixel.hytale.server.worldgen.cave`
+
+## Cave Generator
+
+The `CaveGenerator` carves out underground spaces:
+
+```java
+public class CaveGenerator {
+    // Generate caves for chunk
+    public void generateCaves(GenerationContainer container, int chunkX, int chunkZ);
+
+    // Check if position is in cave
+    public boolean isInCave(int x, int y, int z);
+
+    // Get cave density at position
+    public float getCaveDensity(int x, int y, int z);
+}
+```
+
+## Cave Types
+
+### Tunnel Caves
+
+Winding tunnels through terrain:
+
+```yaml
+CaveType: Tunnel
+Width: 3.0
+Height: 4.0
+Length: 50-200
+Frequency: 0.02
+MinY: 10
+MaxY: 60
+```
+
+### Cavern Caves
+
+Large open underground spaces:
+
+```yaml
+CaveType: Cavern
+MinRadius: 10
+MaxRadius: 30
+MinHeight: 8
+MaxHeight: 20
+Frequency: 0.005
+MinY: 5
+MaxY: 40
+```
+
+### Ravine Caves
+
+Vertical crack formations:
+
+```yaml
+CaveType: Ravine
+Width: 5-15
+Depth: 30-60
+Length: 100-300
+Frequency: 0.001
+```
+
+## Noise-Based Generation
+
+Caves use 3D noise for natural shapes:
+
+```java
+public class CaveNoiseGenerator {
+    private SimplexNoise primaryNoise;
+    private SimplexNoise secondaryNoise;
+    private float threshold;
+
+    public boolean shouldCarve(int x, int y, int z) {
+        float noise1 = primaryNoise.noise3D(x * 0.05f, y * 0.1f, z * 0.05f);
+        float noise2 = secondaryNoise.noise3D(x * 0.02f, y * 0.05f, z * 0.02f);
+
+        float combined = (noise1 + noise2) / 2.0f;
+        return combined > threshold;
+    }
+}
+```
+
+## Cave Carving
+
+```java
+public class CaveCarver {
+    // Carve sphere at position
+    public void carveSphere(GenerationContainer container, Vector3d center, float radius);
+
+    // Carve tunnel between points
+    public void carveTunnel(
+        GenerationContainer container,
+        Vector3d start,
+        Vector3d end,
+        float radius
+    );
+
+    // Carve with noise
+    public void carveWithNoise(
+        GenerationContainer container,
+        Vector3d position,
+        NoiseGenerator noise,
+        float threshold
+    );
+}
+```
+
+## Cave Decoration
+
+After carving, caves are decorated:
+
+```java
+public class CaveDecorator {
+    // Add stalactites/stalagmites
+    public void addStalactites(GenerationContainer container, int x, int y, int z);
+
+    // Add crystal formations
+    public void addCrystals(GenerationContainer container, int x, int y, int z);
+
+    // Add water/lava pools
+    public void addPool(GenerationContainer container, int x, int y, int z, FluidType type);
+
+    // Add cave vegetation
+    public void addMushrooms(GenerationContainer container, int x, int y, int z);
+}
+```
+
+## Cave Biomes
+
+Different cave biomes with unique features:
+
+```yaml
+# cave_biomes/crystal_cave.yaml
+Type: CaveBiome
+Id: crystal_cave
+Features:
+  - Type: CrystalCluster
+    Frequency: 0.1
+    MinSize: 2
+    MaxSize: 8
+  - Type: GlowingMushroom
+    Frequency: 0.05
+AmbientLight: 0.2
+Blocks:
+  Floor: crystal_stone
+  Ceiling: crystal_stone
+  Walls: smooth_stone
+```
+
+## Cave Configuration
+
+```yaml
+# worldgen/cave_config.yaml
+CaveGeneration:
+  Enabled: true
+  Types:
+    - Type: Tunnel
+      Weight: 0.6
+      MinY: 10
+      MaxY: 60
+    - Type: Cavern
+      Weight: 0.3
+      MinY: 5
+      MaxY: 40
+    - Type: Ravine
+      Weight: 0.1
+      MinY: 0
+      MaxY: 64
+  Decoration:
+    Stalactites: true
+    Pools: true
+    Vegetation: true
+  NoiseSettings:
+    Octaves: 4
+    Persistence: 0.5
+    Scale: 0.05
+```
+
+## Cave Systems
+
+Connected cave networks:
+
+```java
+public class CaveSystem {
+    private List<CaveNode> nodes;
+    private List<CaveConnection> connections;
+
+    // Generate connected system
+    public void generate(GenerationContainer container) {
+        // Create nodes
+        for (int i = 0; i < nodeCount; i++) {
+            nodes.add(createCaveNode());
+        }
+
+        // Connect nodes
+        for (CaveNode node : nodes) {
+            CaveNode nearest = findNearest(node);
+            connections.add(new CaveConnection(node, nearest));
+        }
+
+        // Carve caves
+        for (CaveNode node : nodes) {
+            carver.carveCavern(container, node.position, node.radius);
+        }
+
+        // Carve tunnels
+        for (CaveConnection conn : connections) {
+            carver.carveTunnel(container, conn.start, conn.end, conn.radius);
+        }
+    }
+}
+```
+
+## Integration with Terrain
+
+```java
+public class TerrainCaveIntegration {
+    // Prevent caves from breaking surface
+    public boolean shouldCarve(int x, int y, int z, int surfaceY) {
+        // Don't carve within 5 blocks of surface
+        if (y > surfaceY - 5) {
+            return false;
+        }
+
+        // Don't carve below bedrock level
+        if (y < 5) {
+            return false;
+        }
+
+        return caveNoise.shouldCarve(x, y, z);
+    }
+}
+```
+
+## Best Practices
+
+{{< callout type="info" >}}
+**Cave Guidelines:**
+- Balance cave frequency with world density
+- Use noise for natural-looking shapes
+- Connect cave systems for exploration
+- Add decoration for visual interest
+- Consider performance with large caverns
+{{< /callout >}}