Init

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

@@ -0,0 +1,270 @@
+---
+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 >}}