Documentation/content/world/worldgen/density-functions.en.md

title, type, weight

title	type	weight
Density Functions	docs	8

Density functions define terrain shape by calculating density values at each point in 3D space.

Package: com.hypixel.hytale.builtin.hytalegenerator.density

Density Function Concept

Density functions return values that determine solid vs air:

• Positive values = solid terrain
• Negative values = air
• Zero = surface boundary

public interface DensityFunction {
    // Calculate density at position
    float calculate(int x, int y, int z, GenerationContext context);
}

Basic Density Functions

ConstantDensity

Returns a constant value:

Type: ConstantDensity
Value: 1.0

NoiseDensity

Uses noise for terrain variation:

Type: NoiseDensity
NoiseType: Simplex
Scale: 0.01
Amplitude: 1.0
Octaves: 4
Persistence: 0.5

HeightGradient

Creates flat terrain at a specific height:

Type: HeightGradient
BaseHeight: 64
Falloff: 32

public class HeightGradient implements DensityFunction {
    private int baseHeight;
    private float falloff;

    public float calculate(int x, int y, int z, GenerationContext ctx) {
        return (baseHeight - y) / falloff;
    }
}

Composite Functions

AddDensity

Combines multiple functions by addition:

Type: AddDensity
Functions:
  - terrain_base
  - terrain_hills
  - terrain_mountains

MultiplyDensity

Multiplies function values:

Type: MultiplyDensity
Functions:
  - terrain_base
  - mask_function

BlendDensity

Blends between functions:

Type: BlendDensity
FunctionA: plains_terrain
FunctionB: mountain_terrain
Blender: biome_blend

Noise Functions

SimplexNoise

Smooth, natural noise:

public class SimplexNoiseDensity implements DensityFunction {
    private SimplexNoise noise;
    private float scale;
    private int octaves;
    private float persistence;

    public float calculate(int x, int y, int z, GenerationContext ctx) {
        float value = 0;
        float amplitude = 1;
        float frequency = scale;

        for (int i = 0; i < octaves; i++) {
            value += noise.noise3D(x * frequency, y * frequency, z * frequency) * amplitude;
            amplitude *= persistence;
            frequency *= 2;
        }

        return value;
    }
}

PerlinNoise

Classic Perlin noise:

Type: PerlinNoiseDensity
Scale: 0.02
Octaves: 6
Persistence: 0.5
Lacunarity: 2.0

VoronoiNoise

Cell-based noise:

Type: VoronoiDensity
Scale: 0.005
Type: Distance  # or Edge, Cell

Terrain Shaping

CliffFunction

Creates cliff formations:

public class CliffFunction implements DensityFunction {
    private float cliffHeight;
    private float steepness;

    public float calculate(int x, int y, int z, GenerationContext ctx) {
        float baseNoise = ctx.noise2D(x, z, 0.01f);
        float cliffFactor = Math.abs(baseNoise) > 0.3f ? steepness : 1.0f;
        return (64 - y) * cliffFactor;
    }
}

TerraceFunction

Creates terraced terrain:

Type: TerraceDensity
TerraceHeight: 8
Smoothing: 0.5

OverhangFunction

Creates overhangs and arches:

Type: OverhangDensity
BaseFunction: terrain_base
OverhangNoise: overhang_noise
Threshold: 0.3

Biome-Specific Functions

# density/forest_terrain.yaml
Type: BiomeDensity
Biome: forest
Function:
  Type: AddDensity
  Functions:
    - Type: HeightGradient
      BaseHeight: 68
      Falloff: 24
    - Type: NoiseDensity
      Scale: 0.02
      Amplitude: 0.3

Mask Functions

Control where density applies:

Type: MaskedDensity
Function: mountain_terrain
Mask:
  Type: NoiseMask
  Scale: 0.001
  Threshold: 0.5

Configuration

# density/terrain_config.yaml
DensityFunctions:
  terrain_base:
    Type: HeightGradient
    BaseHeight: 64
    Falloff: 32
  terrain_hills:
    Type: NoiseDensity
    Scale: 0.01
    Amplitude: 16
  terrain_combined:
    Type: AddDensity
    Functions: [terrain_base, terrain_hills]

Custom Density Function

public class MyDensityFunction implements DensityFunction {
    @Override
    public float calculate(int x, int y, int z, GenerationContext ctx) {
        // Custom terrain logic
        float baseHeight = 64 + ctx.noise2D(x, z, 0.01f) * 20;
        return baseHeight - y;
    }
}

// Register in plugin setup
densityRegistry.register("my_terrain", new MyDensityFunction());

Best Practices

{{< callout type="info" >}} Density Function Guidelines:

• Use composite functions for complex terrain
• Balance noise scales for natural appearance
• Test with visualization tools
• Consider performance with complex functions
• Use caching for expensive calculations {{< /callout >}}