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

---
title: Density Functions
type: docs
weight: 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

```java
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:

```yaml
Type: ConstantDensity
Value: 1.0
```

### NoiseDensity

Uses noise for terrain variation:

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

### HeightGradient

Creates flat terrain at a specific height:

```yaml
Type: HeightGradient
BaseHeight: 64
Falloff: 32
```

```java
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:

```yaml
Type: AddDensity
Functions:
  - terrain_base
  - terrain_hills
  - terrain_mountains
```

### MultiplyDensity

Multiplies function values:

```yaml
Type: MultiplyDensity
Functions:
  - terrain_base
  - mask_function
```

### BlendDensity

Blends between functions:

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

## Noise Functions

### SimplexNoise

Smooth, natural noise:

```java
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:

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

### VoronoiNoise

Cell-based noise:

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

## Terrain Shaping

### CliffFunction

Creates cliff formations:

```java
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:

```yaml
Type: TerraceDensity
TerraceHeight: 8
Smoothing: 0.5
```

### OverhangFunction

Creates overhangs and arches:

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

## Biome-Specific Functions

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

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

## Configuration

```yaml
# 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

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