Biomes, noise & density

The biome definition and the noise machinery beneath it: noise settings, density functions, surface rules, and custom noise — the math that actually shapes terrain.

The biome definition

A biome file (data/<ns>/worldgen/biome/<id>.json) controls climate (for grass/foliage tint and rain/snow), client-side effects (colors, fog, particles, sound/music), mob spawning, cave carvers, and the list of placed features generated in each of the 11 generation steps.

Biome effects

The effects object drives all client-side rendering.

Spawners & features

spawners — keys are spawn categories: monster, creature, ambient, water_creature, underground_water_creature, water_ambient, misc, axolotls. Each is a list of { "type": <entity>, "weight": int, "minCount": int>0, "maxCount": int≥minCount }.

spawn_costs — per entity { "energy_budget": double, "charge": double } (density-based spawn limiting, used by soul-sand-valley-style crowding control).

features — an array of 11 sub-arrays, one per generation step (indices 0–10 inclusive), each holding placed-feature IDs (or #tags) run in that step:

Biome example

data/example/worldgen/biome/my_plains.json

{
  "has_precipitation": true,
  "temperature": 0.8,
  "temperature_modifier": "none",
  "downfall": 0.4,
  "effects": {
    "fog_color": 12638463,
    "sky_color": 7907327,
    "water_color": 4159204,
    "water_fog_color": 329011,
    "foliage_color": 9215022,
    "grass_color": 9287662,
    "grass_color_modifier": "none",
    "mood_sound": {
      "sound": "minecraft:ambient.cave",
      "tick_delay": 6000,
      "block_search_extent": 8,
      "offset": 2.0
    }
  },
  "spawners": {
    "creature": [
      { "type": "minecraft:sheep", "weight": 12, "minCount": 4, "maxCount": 4 },
      { "type": "minecraft:pig",   "weight": 10, "minCount": 4, "maxCount": 4 }
    ],
    "monster": [
      { "type": "minecraft:zombie", "weight": 100, "minCount": 4, "maxCount": 4 }
    ]
  },
  "spawn_costs": {},
  "carvers": [],
  "features": [
    [], [], [], [],
    [], [],
    ["minecraft:ore_dirt", "minecraft:ore_gravel"],
    [], [],
    ["minecraft:trees_plains", "minecraft:patch_grass_plain"],
    []
  ]
}

Noise settings

Noise settings (data/<ns>/worldgen/noise_settings/<id>.json) drive noise-based terrain: the default block/fluid, the world's vertical envelope, aquifers, ore veins, the noise router (which wires density functions into named generation slots), spawn targeting, and the surface rule decision tree. This is the most complex worldgen file; the heavy math lives in density functions.

The noise object sets the vertical envelope and cell size:

The noise router

The noise_router maps density functions (inline object, referenced ID, or a constant) into named generation slots. Grouped by purpose:

Key insight: temperature/vegetation/continents/erosion/depth/ridges do NOT shape terrain — they only feed the multi_noise biome source. Terrain height is decided solely by final_density.

data/example/worldgen/noise_settings/my_settings.json — a void world (final_density: 0)

{
  "sea_level": 63,
  "disable_mob_generation": false,
  "aquifers_enabled": true,
  "ore_veins_enabled": true,
  "legacy_random_source": false,
  "default_block": { "Name": "minecraft:stone" },
  "default_fluid": { "Name": "minecraft:water", "Properties": { "level": "0" } },
  "noise": {
    "min_y": -64,
    "height": 384,
    "size_horizontal": 1,
    "size_vertical": 2
  },
  "noise_router": {
    "barrier": 0,
    "fluid_level_floodedness": 0,
    "fluid_level_spread": 0,
    "lava": 0,
    "temperature": 0,
    "vegetation": 0,
    "continents": 0,
    "erosion": 0,
    "depth": 0,
    "ridges": 0,
    "initial_density_without_jaggedness": 0,
    "final_density": { "type": "minecraft:constant", "argument": 0 },
    "vein_toggle": 0,
    "vein_ridged": 0,
    "vein_gap": 0
  },
  "spawn_target": [],
  "surface_rule": { "type": "minecraft:block", "result_state": { "Name": "minecraft:stone" } }
}

For real terrain, copy data/minecraft/worldgen/noise_settings/overworld.json from the vanilla data and edit incrementally — hand-writing a full router is impractical.

Density functions

Density functions (data/<ns>/worldgen/density_function/<id>.json) are JSON-encoded math expressions of position (x,y,z) returning a number. They compose into the noise-router slots. A function is either referenced (a string ID, e.g. "minecraft:overworld/sloped_cheese") or inline (a { "type": ... } object). A bare number is shorthand for a constant. Exception: clamp's input accepts only an inline definition, not a string ID.

Unary transforms & constants

Unary transforms take argument = a density function:

Binary & caching

Binary: add, mul, min, max — each {argument1, argument2}.

Caching / performance (take argument): interpolated (interpolate across cell corners), flat_cache (compute once per 4×4 column at Y=0), cache_2d (once per XZ column), cache_once (compute once per position even if referenced twice), cache_all_in_cell (engine-internal — avoid in datapacks).

Noise-based

Shift helpers (argument = a noise ID, sample downscaled by 4): shift_a (samples at x/4,0,z/4), shift_b (z/4,x/4,0), shift (x/4,y/4,z/4).

Range, blending, splines

Inline example — unary + constant

{ "type": "minecraft:abs", "argument": { "type": "minecraft:constant", "argument": -5.0 } }

A y_clamped_gradient — the simplest "flat surface at a Y level" terrain

{
  "type": "minecraft:y_clamped_gradient",
  "from_y": -64,
  "to_y": 320,
  "from_value": 1.0,
  "to_value": -1.0
}

Used as final_density, this alone makes solid ground low and air high.

Surface rules

Surface rules (the surface_rule field inside noise_settings) decide which block goes at each solid surface position — grass over dirt over stone, sand in deserts, deepslate below a Y band, bedrock at the floor. It is a decision tree of three node types evaluated top-down.

Condition types (if_true):

Y anchors (anchor, true_at_and_below, …) are objects like { "absolute": 63 }, { "above_bottom": 0 }, or { "below_top": 0 }.

surface_rule inside noise_settings — desert sand, else grass→dirt cap, else stone

{
  "type": "minecraft:sequence",
  "sequence": [
    {
      "type": "minecraft:condition",
      "if_true": { "type": "minecraft:biome", "biome_is": ["minecraft:desert"] },
      "then_run": { "type": "minecraft:block", "result_state": { "Name": "minecraft:sand" } }
    },
    {
      "type": "minecraft:condition",
      "if_true": {
        "type": "minecraft:stone_depth",
        "surface_type": "floor",
        "offset": 0,
        "add_surface_depth": true,
        "secondary_depth_range": 0
      },
      "then_run": { "type": "minecraft:block", "result_state": { "Name": "minecraft:grass_block", "Properties": { "snowy": "false" } } }
    },
    { "type": "minecraft:block", "result_state": { "Name": "minecraft:dirt" } }
  ]
}

Custom noise

A custom noise definition (data/<ns>/worldgen/noise/<id>.json) supplies a Perlin/octave noise referenced by density functions (noise, shifted_noise, shift*). Two fields only.

Each amplitude's normalized contribution follows roughly 1.04 · value · 2^(n−i−1) / (2^n − 1) where n = amplitudes.length. Lower octaves = broad shape, higher octaves = fine detail.

data/example/worldgen/noise/rolling.json

{
  "firstOctave": -3,
  "amplitudes": [1.0, 1.0, 0.5, 0.25]
}

Sources

• Minecraft Wiki — Biome definition
• Minecraft Wiki — Noise settings
• Minecraft Wiki — Noise router
• Minecraft Wiki — Density function
• Minecraft Wiki — Surface rule
• Minecraft Wiki — Noise