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

title, type, weight

title	type	weight
Cave Generation	docs	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:

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:

CaveType: Tunnel
Width: 3.0
Height: 4.0
Length: 50-200
Frequency: 0.02
MinY: 10
MaxY: 60

Cavern Caves

Large open underground spaces:

CaveType: Cavern
MinRadius: 10
MaxRadius: 30
MinHeight: 8
MaxHeight: 20
Frequency: 0.005
MinY: 5
MaxY: 40

Ravine Caves

Vertical crack formations:

CaveType: Ravine
Width: 5-15
Depth: 30-60
Length: 100-300
Frequency: 0.001

Noise-Based Generation

Caves use 3D noise for natural shapes:

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

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:

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:

# 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

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

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

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