World Generator Configuration


CoFH World lets users or modpack authors specify custom types of ores, plants, boulders, spikes, lakes and more to be generated in the world. This guide explains how to do that.

Note: A good understanding of JSON is required. JSON terms will be used to describe the format of the configuration files.


File structure

Custom world generation is specified by .json files in the cofh/world folder inside Minecraft Forge’s config folder. By default, this folder contains one or more files: 00_minecraft.json, and several files for Thermal Foundation if it is also installed.

These files may be edited to change the default types of world generation. It is also possible to add new .json files to be read by CoFH World. This is not required when adding more world generation types, but can improve readability. The folder is read recursively, so the .json files may be grouped in subfolders.

Editing 00_minecraft.json will only have effect if the option ReplaceStandardGeneration is set to true in CoFH World’s configuration file. It is set to false by default.

If world generation is not working as intended, try checking the log. Any errors that are found in the files are logged while the game starts.


File format

Every world generation file consists of one root object. This object must contain a value populate, which describes the things to generate in the world. The object may also contain a value dependencies, describing what mods must be loaded in order to read the world generation file.

populate

The populate value is another object, whose values are generation entries. It describes the features to populate the world with.

dependencies

The dependencies value is either a single Forge mod entry, or an array of them. If one of the specified dependencies is not loaded, the entire file will be skipped by CoFH World.


Generation entry format

A generation entry describes a feature to generate in the world. It is an object that can contain the following values.

Name Required Type Default Description
distribution Yes String N/A How the generated features are distributed in the world. Depending on the type of distribution, more values may need to be added to the generation entry. See Distribution types for a list of available distribution types.
generator Yes Generator entry / weighted array of generator entries N/A The type of feature to generate. May be specified as a weighted array with multiple types of features to randomly choose from.
cluster-count Yes Number (integer) N/A How many attempts to generate the feature are done per chunk.
chunk-chance No Number (integer) 1 The chance of the feature being generated in a chunk. Read as follows: one in [chance] chunks.
in-village No Boolean true Whether the feature may be generated in villages.
biome No Biome restriction entry (Any biome) In which biomes the feature may be generated.
dimension No Dimension restriction entry (Any dimension) In which dimensions the feature may be generated.
enabled No Boolean true Whether the entry is active. If false, the feature will not be generated.
retrogen No Boolean false Whether to generate in previously generated chunks. This will only have effect if the option RetroactiveGeneration is set to true in CoFH World's configuration file. To retroactively generate in chunks where the feature already generated, change the entry's name.

Generator entries

A generator entry specifies which generator to use to generate a feature, and also configures said generator. Not to be confused with generation entries. It is an object that can contain the following values.

Name Required Type Default Description
type No String (Set by distribution type) Which generator type to use to generate the feature. Depending on the type of generator, more values may need to be added to the generator entry. See Generator types for a list of available generator types.
block Yes Block entry / weighted array of block entries N/A The type(s) of block to generate.
material No Block entry / array of block entries (Set by distribution type) The type(s) of block that may be replaced to generate the feature, like stone for ore blocks.

Biome restriction entries

A biome restriction entry specifies the biomes in which a feature may be generated. It is an object that contains the following values.

Name Required Type Default Description
restriction Yes String N/A Whether the given list of biomes should be used as a blacklist or as a whitelist of biomes to generate in. Can be either "blacklist" or "whitelist".
value Yes Array of biome entries N/A The biomes that the restriction applies to.

Dimension restriction entries

A dimension restriction entry specifies the dimensions in which a feature may be generated. It is an object that contains the following values.

Name Required Type Default Description
restriction Yes String N/A Whether the given list of dimensions should be used as a blacklist or as a whitelist of biomes to generate in. Can be either "blacklist" or "whitelist".
value Yes Array of numbers (integers) N/A The IDs of the dimensions that the restriction applies to. The vanilla dimensions' IDs are as follows: 0 for the Overworld, -1 for the Nether and 1 for the End.

Distribution and generator types

This section lists the available distribution and generator types that may be used.

Distribution types

Click on the name of a distribution type to see information about it.

  • With the uniform distribution, features are uniformly distributed between a minimum and a maximum altitude. This is the most common distribution for ores.

    • The default generator type is cluster.
    • The default generator material is stone.

    The following values must be added to a generation entry for this distribution type:

    Name Required Type Default Description
    min-height Yes Number (integer) N/A The minimum altitude at which features can be generated.
    max-height Yes Number (integer) N/A The maximum altitude at which features can be generated. Must be higher than min-height.
  • With the gaussian distribution, features are distributed around a certain altitude. The features generate commonly near this altitude, and less commonly further from this altitude. Lapis lazuli ore is generated like this.

    • The default generator type is cluster.
    • The default generator material is stone.

    The following values must be added to a generation entry for this distribution type:

    Name Required Type Default Description
    center-height Yes Number (integer) N/A The altitude around which features are generated.
    spread Yes Number (integer) N/A How many blocks away from the center altitude features may be generated.
    smoothness No Number (integer) 2 How smoothly the amount of features generated declines when further from the center altitude. Must be higher than 0.
  • With the surface distribution, features are distributed on the surface (wherever the sky is directly visible).

    • The default generator type is cluster.
    • The default generator materials are stone, grass blocks, dirt, sand, gravel, snow, water and air. Air is in this list because this allows features to be generated on top of the surface (replacing air blocks), and not just into the surface (replacing the other block types).

    The following value may be added to a generation entry for this distribution type:

    Name Required Type Default Description
    material No Block entry / array of block entries Same as default generator materials The type(s) of block that features may be generated in. This is checked before generating an entire feature, unlike generator materials, which are checked for every block while already generating a feature.
    follow-terrain No Boolean false When set to true, blocks like tall grass, leaves and fluids do not count when finding the highest block to generate on top of.
  • The decoration distribution is mostly the same as surface, except the default generator is decoration and the default generator material is only air.

    This is useful when using the decoration generator, because said generator only generates blocks on top of surfaces, so only air blocks should have to be replaced.

  • With the underfluid distribution, features are distributed at the bottom of bodies of fluid.

    • The default generator type is cluster.
    • The default generator materials are grass blocks and dirt.

    The following value may be added to a generation entry for this distribution type:

    Name Required Type Default Description
    fluid No String / array of strings (see description) Below which fluid types features may be generated. The fluids' registry names (like lava and cryotheum) should be used here. Note that the default value is not water. Instead, when this value is not specified, features are generated below any blocks with the 'water' material.
    material No Block entry / array of block entries Same as default generator materials The type(s) of block that features may be generated in. This is checked before generating an entire feature, unlike generator materials, which are checked for every block while already generating a feature.
  • The underwater distribution is a shortcut to using underfluid without setting the value fluid.

    • The default generator type is plate instead of cluster.
  • With the cave distribution, features are distributed on floors or ceilings of underground spaces. This typically only works below sea level. If sea level is below block layer 20, however, it will work on any altitude instead.

    • The default generator type is cluster.
    • The default generator material is stone.

    The following value may be added to a generation entry for this distribution type:

    Name Required Type Default Description
    ceiling No Boolean false Whether features are generated on ceilings or on floors. If true, features are generated on ceilings, and if false, features are generated on floors.
  • With the fractal distribution, multiple features are distributed together in large clusters, also known as veins.

    • The default generator type is large-vein.
    • The default generator material is stone.

    The following values must be added to a generation entry for this distribution type:

    Name Required Type Default Description
    min-height Yes Number (integer) N/A The minimum altitude at which veins can be generated.
    vein-height Yes Number (integer) N/A The vertical diameter of veins, measured in blocks along the Y axis.
    vein-diameter Yes Number (integer) N/A The horizontal diameter of veins, measured in blocks along the X and Z axes.
    vertical-density Yes Number (integer) N/A How dense veins are along the Y axis. Higher numbers mean that features in veins are closer together, making veins contain more blocks in total. This value is not measured in blocks; some experimenting will be needed to obtain the desired result.
    horizontal-density Yes Number (integer) N/A The same as vertical-density, except along the X and Z axes.

Generator types

Click on the name of a generator type to see information about it.

  • The cluster generator creates simple groups of blocks (clusters). Ore blocks are generated like this, as well as deposits of dirt, gravel, granite, diorite and andesite.

    The following value must be added to a generator entry for this generator type:

    Name Required Type Default Description
    cluster-size Yes Number (integer) N/A How large clusters of blocks are. This value is not measured in blocks; some experimenting will be needed to obtain the desired result.
  • The sparse-cluster generator is mostly the same as the cluster generator, with one exception. When the cluster-size value is set to less than 4, clusters will only have a certain chance to actually generate, instead of generating a single block or so every time. At 3, one in 3 clusters will actually generate. At 2 it is one in 6 clusters, and at 1 it is one in 12 clusters.

  • The large-vein generator is similar to cluster, except the groups of blocks it creates can be much larger. Use with caution.

    The following values can be added to a generator entry for this generator type:

    Name Required Type Default Description
    cluster-size Yes Number (integer) N/A How large clusters of blocks are. This value is not measured in blocks; some experimenting will be needed to obtain the desired result.
    sparse No Boolean true If true, veins are generated smaller and more spread out, looking somewhat like neurons. If false, veins are generated much larger and more dense, closer to how the cluster generator works.
  • The decoration generator creates groups of single blocks scattered around on a surface. Small plants and cacti are generated like this, as well as fire blocks in the Nether.

    Meant to be used with the decoration distribution.

    The following values must or may be added to a generator entry for this generator type:

    Name Required Type Default Description
    cluster-size Yes Number (integer) N/A How many blocks a single group of blocks may contain at most.
    surface No Block entry / array of block entries Grass block The block type or block types that blocks in a group may generate on top of.
    see-sky No Boolean true Whether to only generate in places with a direct line of sight to the sky.
    check-stay No Boolean true Specifies whether to only generate blocks that can be sustained by the blocks they are generated on top of. For example, sugar cane cannot be sustained by blocks that are not directly next to water.
    stack-height No Number (integer) 1 How many times to stack a single generated block upwards. Used for things like cacti and sugar cane.
    x-variance No Number (integer) 8 How spread out a group of blocks may be, in blocks along the X axis.
    y-variance No Number (integer) 4 Ditto, except along the Y axis.
    z-variance No Number (integer) 8 Ditto, except along the Z axis.
  • The small-tree generator creates simple trees. Small oak and birch trees are generated like this.

    The block value in generator entries is used to generate the trunks of the trees.

    The following values can be added to a generator entry for this generator type:

    Name Required Type Default Description
    surface No Block entry / array of block entries Any block type, or grass blocks and dirt if invalid The block type or block types that trees may generate on top of.
    leaves No Block entry / weighted array of block entries None What blocks the leaves of trees are made of.
    min-height No Number (integer) 5 The minimum height of trees, in blocks.
    height-variance No Number (integer) 3 How much may be added randomly the the minimum height of trees, in blocks.
    tree-checks No Boolean true Whether to verify that trees can properly 'grow' in the locations determined by the distribution type.
    relaxed-growth No Boolean false Whether trees may have blocks adjacent to their trunk at the bottom-most layer. For example, this could let trees generate one block deep in water.
    water-loving No Boolean false Whether to allow trees to generate in water, up to the leaves.
    leaf-variance No Boolean true Whether or not blocks may be missing from the corners of the leaves, giving them a more natural look.
  • The plate generator creates groups of blocks as cylinders (plates). Clay deposits are generated like this.

    The following values must or may be added to a generator entry for this generator type:

    Name Required Type Default Description
    radius Yes Number (integer) N/A The radius of plates in blocks.
    height No Number (integer) 1 Used to determine the height of plates in blocks. This value is used as some kind of radius around a layer of blocks that is always generated. For example, using 1 here will result in a plate that is 3 blocks high: the middle layer, 1 layer above and 1 layer below.
    slim No Boolean false If true, generated plates are 1 block less tall at the top. By default, the plates are an odd number of blocks high due to the way they are generated (see height), so this option allows plates that are an even amount of blocks high to be generated.
  • The boulder generator creates clusters of sphere-like groups of blocks. Moss stone boulders in the mega taiga biome are generated like this.

    The following values must or may be added to a generator entry for this generator type:

    Name Required Type Default Description
    diameter Yes Number (integer) N/A The diameter of boulders in blocks.
    size-variance No Number (integer) 2 How much a particular boulder's diameter may differ from the set value.
    count No Number (integer) 3 How many boulders a single cluster of boulders can contain.
    count-variance No Number (integer) 0 How much the amount of boulders may differ per cluster of boulders.
    hollow No Boolean false Whether boulders have a room filled with air blocks inside.
    hollow-size No Number (floating-point) 0.1665 (one sixth) How large the hollow part of hollow boulders is, relatively to the size of the boulders. Can be any value between 0.0 (exclusive) and 1.0 (exclusive).
    hollow-variance No Number (floating-point) 0.0 How much the size of the hollow part may differ per hollow boulder.
    The resulting size of the hollow part is calculated as follows: size * (1 - [random 0.0-1.0] * variance).
  • The lake generator creates small bodies of fluid (lakes). If needed, space is carved out above them. Small bodies of water and lava are generated like this.

    The block value in generator entries is used to generate the 'fluid' part of the lakes. Typically this is set to a fluid block, but it doesn't have to be.

    The following values may be added to a generator entry for this generator type:

    Name Required Type Default Description
    use-material No Boolean false Whether the generator takes the set generator materials into account, or ignores them and replaces any block to generate lakes.
    outline-block No Block entry / weighted array of block entries None The block or blocks to surround the 'fluid' part of lakes with.
    gap-block No Block entry / weighted array of block entries Air The block or blocks that blocks above lakes are replaced with to carve out space.
  • The geode generator creates geodes, which are 'blobs' of blocks that are surrounded by a layer of blocks called the crust, and can optionally contain a core of blocks called the filler.

    Geodes are similar to lakes, except they are completely filled with blocks instead of carving out space.

    The following values may be added to a generator entry for this generator type:

    Name Required Type Default Description
    crust No Block entry / weighted array of block entries Stone What blocks the crust of geodes are made of.
    hollow No Boolean false Whether to leave out space in the center of geodes, so that a filler can be generated. This does not mean that the center of geodes will be set to air blocks. Instead, whatever blocks that were there before generating the geode will stay, unless a filler is specified.
    filler No Block entry / weighted array of block entries None What blocks the filler of geodes are made of. hollow must be set to true for this to work correctly.
  • The spike generator creates spikes that point upwards. Spikes extend a few blocks into the surface they are generated on. Packed ice spikes in the ice plains spikes biome are generated like this.

    The following values may be added to a generator entry for this generator type:

    Name Required Type Default Description
    min-height No Number (integer) 7 The minimum height of spikes, in blocks.
    height-variance No Number (integer) 4 The maximum amount of blocks that may be randomly added to the minimum height of spikes.
    size-variance No Number (integer) 2 The maximum amount of blocks that may be randomly added to the radius of spikes at the bottom.
    position-variance No Number (integer) 3 A random offset along the Y axis when determining the position of spikes.
    large-spikes No Boolean true Whether spikes may sometimes be generated as 'large' spikes, which are significantly taller.
    large-spike-chance No Number (integer) 60 The chance of a generated spike to be a large spike. One in [value] spikes will be generated as a large spike.
    min-large-spike-height-gain No Number (integer) 10 The minimum amount of extra layers that large spikes have over regular spikes.
    large-spike-height-variance No Number (integer) 30 How many blocks may be added randomly to the minimum height gain of large spikes.
    large-spike-filler-size No Number (integer) 1 The radius of the extra layers of blocks that are added to large spikes, in blocks.
  • The stalagmite generator creates spikes that point upwards (stalagmites). Unlike the spikes created by the spike generator, which have a mostly uniform width, these spikes are wider at the bottom and thinner at the top.

    The following values may be added to a generator entry for this generator type:

    Name Required Type Default Description
    gen-body No Block entry / array of block entries Air What materials the body of stalagmites can generate in. Not quite the same as the generator material, as that only determines where the base may generate.
    min-height No Number (integer) 7 The minimum height of stalagmites in blocks.
    height-variance No Number (integer) 4 How many blocks may be added randomly to the minimum height of stalagmites.
    gen-size No Number (integer) 0 The minimum width of stalagmites at their base, in blocks. If set to 0, height-mod will be used to calculate the base width.
    height-mod No Number (integer) 5 If genSize is set to 0, the height of stalagmites is divided by this value to get their base width in blocks.
    size-variance No Number (integer) 2 How much may be added randomly to the minimum width of stalagmites at their base, in blocks.
    smooth No Boolean false Whether stalagmites have a smooth curve in their shape from bottom to top. If false, stalagmites will be much more narrow and pointy.
    fat No Boolean true If true, sets stalagmites to be thicker, usually leaving a larger footprint. The stalagmites still respect their set base width, though, which could result in parts being clipped away at the bottom. Used to make stalagmites less narrow higher up.
  • The stalactite generator is nearly identical to the stalagmite generator, except spikes created by this generator point downwards instead of upwards.


Other formats

This section describes other kinds of formats that are used throughout the JSON files.

Weighted array

This format describes an array with items to randomly choose from.

Weighted arrays may contain any kind of item. However, objects in a weighted array may contain the value weight, which specifies how likely the item is to be picked compared to other items in the array. The default weight of each item is 100.

Block entry

This format describes a certain type of block.

A block entry can be specified either as an object or as a string. If specified as an object, said object can contain the following values.

Name Required Type Default Description
name Yes String N/A The internal name (ID) of the block, like minecraft:stone for stone, and ThermalFoundation:Ore for Thermal Foundation ore blocks. If the block is added by Minecraft itself, the minecraft: prefix is not required.
properties No Object with string values (Default block states of the specified block) The block states of the block. This value and metadata cannot both be specified.
metadata No Number (integer) 0 The metadata value of the block. A value of -1 means the block entry represents the block with any metadata. This value and properties cannot both be specified.

If specified as a string, the value name seen above can be used directly. The other values will be set to their defaults.

Biome entry

This format describes a specific biome, or a way to match biomes by certain properties.

A biome entry can be specified either as an object or as a string. If specified as an object, said object can contain the following values.

Name Required Type Default Description
type Yes String N/A How the biome entry matches biomes. Possible values are "name", "id", "temperature" and "dictionary".
entry Yes String / array of strings N/A The value used to match biomes. Differs depending on the value type:
  • name: The full names of one or more biomes, as seen in the F3 debug screen.
  • id: The internally registered names of one or more biomes.
  • temperature: One or more temperature categories that biomes can be in. Possible temperature categories are COLD, MEDIUM, WARM and OCEAN.
  • dictionary: One or more Forge biome tags that biomes can be associated with. A list of possible Forge biome tags can be found here.
whitelist No Boolean true If false, the biome entry specifies an exception to the blacklist or whitelist it is in.
rarity No Number (integer) -1 If greater than 1, a random chance is added to determining whether a biome matches the entry. One in [rarity] attempts to match a matching biome will go through. This can be used to make a feature generate more rarely in certain biomes.

If specified as a string, the entry specifies a single biome by its full name.

Forge mod entry

This format describes a Minecraft Forge mod, optionally with a certain version.

Forge mod entries are objects that can contain the following values.

Name Required Type Default Description
id Yes String N/A The internal mod ID that the mod registers itself with.
version No String (Any version) The version of the mod. May be a specific version, or a Maven-compatible version range.
exclude No Boolean false If true, the file that this entry is declared in will only load if the specified mod is not installed.

This section lists some links that can be useful when setting up world generation with CoFH World.

CoFH World
World Generator Configuration

© Copyright 2017 Team CoFH. Powered by GitHub Pages, Jekyll, UIkit.
Last updated: 2017-09-19 18:32:35 +0000