Documentation/content/world/worldgen/material-providers.en.md

title, type, weight

title	type	weight
Material Providers	docs	9

Material providers determine which blocks are placed at each position during terrain generation.

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

Material Provider Concept

Material providers select blocks based on context:

public interface MaterialProvider {
    // Get block for position
    BlockType getBlock(int x, int y, int z, MaterialContext context);
}

public class MaterialContext {
    private Biome biome;
    private float density;
    private int surfaceHeight;
    private int depth;  // Depth below surface
    private boolean underwater;
}

Basic Providers

SingleMaterialProvider

Returns a single block type:

Type: SingleMaterial
Block: stone

DepthMaterialProvider

Changes blocks based on depth:

Type: DepthMaterial
Layers:
  - Depth: 0
    Block: grass_block
  - Depth: 1
    Block: dirt
  - Depth: 4
    Block: stone

public class DepthMaterialProvider implements MaterialProvider {
    private List<DepthLayer> layers;

    public BlockType getBlock(int x, int y, int z, MaterialContext ctx) {
        for (DepthLayer layer : layers) {
            if (ctx.depth >= layer.minDepth) {
                return layer.block;
            }
        }
        return defaultBlock;
    }
}

Biome-Based Providers

BiomeMaterialProvider

Selects materials based on biome:

Type: BiomeMaterial
Biomes:
  forest:
    Surface: grass_block
    Subsurface: dirt
    Stone: stone
  desert:
    Surface: sand
    Subsurface: sandstone
    Stone: sandstone
  tundra:
    Surface: snow_block
    Subsurface: permafrost
    Stone: stone

BiomeSurfaceProvider

Surface-specific provider:

public class BiomeSurfaceProvider implements MaterialProvider {
    private Map<String, SurfaceMaterials> biomeMaterials;

    public BlockType getBlock(int x, int y, int z, MaterialContext ctx) {
        SurfaceMaterials materials = biomeMaterials.get(ctx.biome.getId());
        if (materials == null) {
            materials = defaultMaterials;
        }

        if (ctx.depth == 0) {
            return materials.surface;
        } else if (ctx.depth < 4) {
            return materials.subsurface;
        } else {
            return materials.stone;
        }
    }
}

Noise-Based Providers

NoiseMaterialProvider

Uses noise for variation:

Type: NoiseMaterial
Noise:
  Scale: 0.1
  Threshold: 0.5
Materials:
  Above: stone
  Below: granite

GradientMaterialProvider

Blends materials based on value:

public class GradientMaterialProvider implements MaterialProvider {
    private SimplexNoise noise;
    private List<MaterialStop> stops;

    public BlockType getBlock(int x, int y, int z, MaterialContext ctx) {
        float value = noise.noise3D(x * 0.05f, y * 0.05f, z * 0.05f);

        for (int i = stops.size() - 1; i >= 0; i--) {
            if (value >= stops.get(i).threshold) {
                return stops.get(i).block;
            }
        }
        return defaultBlock;
    }
}

Composite Providers

LayeredMaterialProvider

Stacks multiple providers:

Type: LayeredMaterial
Layers:
  - Provider: bedrock_layer
    MaxY: 5
  - Provider: stone_layer
    MaxY: 60
  - Provider: surface_layer
    MaxY: 256

ConditionalMaterialProvider

Conditional block selection:

Type: ConditionalMaterial
Conditions:
  - Condition:
      Type: Underwater
    Provider: sand_material
  - Condition:
      Type: NearCave
      Distance: 2
    Provider: cave_stone
  - Default: default_material

Special Providers

OreMaterialProvider

Places ore veins:

Type: OreMaterial
Ores:
  - Type: iron_ore
    MinY: 0
    MaxY: 64
    Frequency: 0.02
    Size: 9
  - Type: diamond_ore
    MinY: 0
    MaxY: 16
    Frequency: 0.001
    Size: 4

CaveMaterialProvider

Materials for cave surfaces:

Type: CaveMaterial
Floor: gravel
Ceiling: stone
Walls: mossy_stone
WaterLevel: 10
WaterBlock: water

Configuration

# materialproviders/config.yaml
MaterialProviders:
  default:
    Type: BiomeMaterial
    Biomes:
      forest:
        Surface: grass_block
        Subsurface: dirt
        Stone: stone
  cave:
    Type: CaveMaterial
    Floor: gravel
    Walls: stone

Custom Provider

public class MyMaterialProvider implements MaterialProvider {
    @Override
    public BlockType getBlock(int x, int y, int z, MaterialContext ctx) {
        // Custom material logic
        if (ctx.underwater) {
            return BlockTypes.SAND;
        }
        if (ctx.depth == 0) {
            return BlockTypes.GRASS_BLOCK;
        }
        return BlockTypes.STONE;
    }
}

// Register
materialRegistry.register("my_materials", new MyMaterialProvider());

Best Practices

{{< callout type="info" >}} Material Provider Guidelines:

• Use biome-aware providers for variety
• Layer providers for complex surfaces
• Add noise for natural variation
• Consider special cases (underwater, caves)
• Test material transitions between biomes {{< /callout >}}