Custom carver

Carvers are used to add caves and canyons.

Carver Type

A carver type (sometimes called carver) determines what to carve. There's three carver types:

• cave - Carves a cave. A cave is a long tunnel that sometimes branches. Somtimes one or more tunnels start from a circular void.
• nether_cave - Similar to cave, but with a less frequency and wider tunnels. And aquifer doesn't work. The carved blocks below bottom_y + 32.0 are filled with lava.
• canyon - Carves a canyon.

Configured Carver

A carver type determines what to carve, but the details need to be configured additionally. After configured, it is called a configured carver, or simply called a carver.

Configured carvers are stored as JSON files within a data pack in the path data/<namespace>/worldgen/configured_carver.

JSON format

• : The root object.
  •  type: The ID of carver type.
  •  config: Configuration values for the carver.
    •  probability: The probability that each chunk attempts to generate carvers. Value between 0 and 1 (both inclusive).
    •  y: The height at which this carver attempts to generate.
      • Height provider
    •  lava_level: The Y-level below or equal to which the carved areas are filled with lava. Doesn't affect nether_cave (where lava level is always bottom_y + 31). (This field is seemingly ignored and always set to -56 (MC-237017), needs testing)
      • Choices for a vertical anchor (must choose only one of three)
    •  replaceable: Blocks that can be carved. Can be a block ID, a block tag, or a list of block IDs.
    •  debug_settings: (optional) Replaces blocks in the carved areas for debugging.
      •  debug_mode: (optional, defauts to false) Enable debug mode for this carver.
      •  air_state: (optional, defaults to acacia button's default state) Replaces air blocks.
        • Block state
      •  water_state: (optional, defaults to acacia button's default state) Replaces water blocks and then waterlogs these blocks.
        • Block state
      •  lava_state: (optional, defaults to acacia button's default state) Replaces lava blocks.
        • Block state
      •  barrier_state: (optional, defaults to acacia button's default state) Replaces barriers of aquifers.
        • Block state

      If carver type is cave or nether_cave, additional fields are as follows:

    •  yScale: Vertically scales circular voids.
      • Float provider
    •  horizontal_radius_multiplier: Horizonally scales cave tunnels. Doesn't affect the length of tunnels.
      • Float provider
    •  vertical_radius_multiplier: Vertically scales cave tunnels. Doesn't affect the length of tunnels.
      • Float provider
    •  floor_level: Value between -1.0 and 1.0 (both inclusive). Change the shape of the cave's horizontal floor. If 0.0, carves the terrain with ellipsoids. If 1.0, carves with upper semi-ellipsoids, resulting in a level floor.
      • Float provider

      If carver type is canyon, additional fields are as follows:

    •  yScale: Vertically scales canyons.
      • Float provider
    •  vertical_rotation: Vertical rotation as a canyon extends.
      • Float provider
    •  shape: The shape to use for the ravine.
      •  distance_factor: Scales the length of canyons. Higher values make canyons longer.
        • Float provider
      •  thickness: Scales the breadth and height of canyons.
        • Float provider
      •  horizontal_radius_factor: Scales the breadth of canyons. Higher values make canyons wider.
        • Float provider
      •  vertical_radius_default_factor: Vertically scales canyons. Higher values make canyons deeper.
      •  vertical_radius_center_factor: Scales the height based on the horizontal distance from the canyon's center, resulting in deeper center.
      •  width_smoothness: Higher values smooth canyon walls on the vertical axis. Must be greater than 0.

History

Java Edition
1.16.2		20w28a			Added experimental support for configured carvers in data packs.
1.17		21w06a			Removed carvers underwater_canyon and underwater_cave.
		21w08a			Added configuration for the canyon carver.
					Added optional carver field debug_settings. When enabled with debug_mode, can place blocks from air_state.
		21w11a			Renamed canyon carver field distanceFactor to distance_factor.
		21w13a			Added configuration for the cave carver.
					Replaced carver field bottom_inclusive and top_inclusive with field y, which is a height provider. Added field yScale.
					Moved canyon carver shape fields into sub-object shape.
		21w16a			Added field aquifers_enabled.
					Added fields water_state, lava_state, and barrier_state in the debug_settings object.
1.18		21w38a			Removed field aquifers_enabled.
1.19		22w15a			Added field replaceable to carver configuration.