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

---
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 >}}