Custom World Generation

CoFH Core includes a powerful customizable world generator. Using this feature, users or modpack authors can specify their own ores, plants, boulders, spikes, lakes, dungeons and more to generate in their worlds.

Note: A good understanding of the JSON markup language is recommended. A description of the JSON syntax can be found here.

Table of contents

File structure

Custom world generation is specified using JSON files in the folder [minecraft instance]\config\cofh\world.

By default, this folder contains one or two files: Vanilla.json and possibly ThermalFoundation-Ores.json. The latter is only added when Thermal Foundation is present.

These files can be freely edited to change the default types of world generation. It is also possible to add new files to be read by CoFH Core. This is not required when adding more world generation types, but can improve human readability. Furthermore, new folders that contain more files can be added in the 'world' folder, as it is read recursively.

Any errors that are found in the files will be logged while the game starts. Be sure to check the log if generation is not working as intended.

Note 1: Editing Vanilla.json will only have effect if the option B:ReplaceVanillaGeneration is enabled in CoFH Core's main configuration file.
Note 2: When adding a new file to the folder, make sure that the file has the .json extension.

Format

This section explains the format that CoFH Core reads custom world generation files in.

Every world generation file contains a root Object, which in turn contains values that describe the actual world generation types themselves. These values are also Objects, and will from now on be called entries.

As an example of the format, see the default Vanilla.json file.
It can be seen here that the template value is the first value to be set on every entry. This is because the template is the most important value in an entry, and determines some of the other values that can or need to be set.

The template value describes how the generation of groups of blocks is distributed. A generator, which actually generates the blocks, can also be defined here.
The template also specifies what other values are needed in an entry.

The value of template can be either an Object or a String value.

If specified as an Object, said Object can contain the following values.

Name Required Type Default Description
type Yes String N/A The type of template to use. Possible template types can be found under 'Template types'.
generator No String Template specific The type of generator to use. Possible generator types can be found under 'Generator types'.

Generator types may require additional values to be set. These values must be set in the template object as well.

If specified as a String, the type value seen above can be used directly.

After the template has been set, it is time to configure the other values in the entry. Some values can or need to be added to every entry, and some values only can or need to be added for specific template types.

Common values

These values can be added to every entry regardless of template type.

Name Required Type Default Description
enabled No Boolean true Whether the entry is active. If false, the entry will not be read.
retrogen No Boolean false Whether previously generated chunks can be generated in. To work, the B:RetroactiveOreGeneration option must be enabled in CoFH Core's main configuration file. Also note that in order to retroactively generate the same entry again, the entry's name must be changed.
block Yes Block entry / Array of block entries N/A The block type(s) to generate.
material No Block entry / Array of block entries Template specific The block type(s) that may be replaced with blocks generated using the entry.
clusterSize Generator specific Number (integer) 0 Determines how large groups of blocks are. See 'Generator types' for how different generator types interpret this value.
numClusters Yes Number (integer) N/A How many attempts to generate blocks are done in a single chunk.
chunkChance No Number (integer) 1 Used to determine the chance of a chunk being generated into. One in [chunkChance] chunks will be generated into.
biomeRestriction No String null Whether the entry is restricted to (not) be used in certain biomes. Can be either blacklist or whitelist. Anything else or null will be interpreted as 'no restrictions'. Further specifications are done in the value "biomes".
biomes No Array of biome entries null To which biomes the biomeRestriction value applies.
dimensionRestriction No String null Whether the entry is restricted to (not) be used in certain dimensions. Can be either blacklist or whitelist. Anything else or null will be interpreted as 'no restrictions'. Further specifications are done in the value "dimensions".
dimensions No Array of numbers (integers) null To which dimensions the dimensionRestriction value applies. The numbers represent dimension IDs. The vanilla dimension IDs are as follows: 0 for the Overworld, -1 for the Nether and 1 for the End. Dimension IDs of mods can usually be found in mod configuration files.

Template types

This section describes all the different template types that CoFH Core provides. Templates determine the distribution of groups of blocks.
Click on the name of a template type to see information about it.

  • The uniform template generates groups of blocks with an even height distribution between a minimum and a maximum height.
    This template is most commonly used for generating ores.

    • By default, this template uses the cluster generator.
    • The default material for this template is Stone blocks.

    Other than the common values, this template needs the following values to be added to an entry:

    Name Required Type Default Description
    minHeight Yes Number (integer) N/A The minimum Y level at which can be generated.
    maxHeight Yes Number (integer) N/A The maximum Y level at which can be generated. Must be higher than "minHeight".

  • The normal template is mostly the same as the uniform template. The only difference is the height distribution. Instead of an uniform distribution between a minimum and a maximum height, it has a normal distribution, meaning it is more likely to generate near the mean height than it is to generate near the set height limits.
    Minecraft generates Lapis Lazuli Ore with this kind of height distribution.

    Note: This template could be mistaken to be the 'normal' or standard template for generating ores. This is not the case, as the name refers to normal distribution. The most commonly used template for ores is uniform.

    • By default, this template uses the cluster generator.
    • The default material for this template is Stone blocks.

    Other than the common values, this template needs the following values to be added to an entry:

    Name Required Type Default Description
    meanHeight Yes Number (integer) N/A The mean Y level at which can be generated.
    maxVariance Yes Number (integer) N/A How much the Y level being generated on may differ from the mean height at most.

  • The surface template is mostly the same as the uniform template, except this template generates groups of blocks into or near the surface (wherever the sky is directly visible).
    Examples of surface generation are the Gravel Ores from Tinkers' Construct.

    • By default, this template uses the cluster generator.
    • The default materials for this template are Stone, Grass, Dirt, Gravel, Sand, Snow, Water and Air blocks. The Air material lets blocks be generated on top of the surface, while all other materials let blocks be generated into the surface.

    Other than the common values, this template can have the following value added to an entry:

    Name Required Type Default Description
    followTerrain No Boolean false Whether generation may replace 'soft' blocks like plants, foliage or fluids. If true, 'soft' blocks may not be replaced.

  • The decoration extends upon the surface template, and uses the same entries as the ones the surface template uses. Used for generating scattered groups of blocks (like plants) on surfaces.

    • By default, this template uses the decoration generator. It is meant to only be used with that generator type.
    • The default material for this template is Air blocks.

    A quirk of maintaining compatibility with an old format for custom world generation files requires that an empty material array is specified when using this template and the corresponding generator: "material": []

  • The underfluid template blocks into terrain that is directly below fluid blocks of certain types of fluids.

    Using underwater is also possible for the template type. This is a shortcut to using underfluid with the genFluid value left at its default.

    • By default, this template uses the cluster generator.
    • If the underwater template is used, this template uses the plate generator by default instead.
    • The default materials for this template are Grass and Dirt blocks.

    Other than the common values, this template can have the following value added to an entry:

    Name Required Type Default Description
    genFluid No String / Array of Strings Water (or similar) Below which fluid types groups of blocks can be generated. The Strings are the internal names of fluids. Note that the default value is not water. Rather, when this value is not specified, the entry will generate blocks below any blocks with the 'water' material.

  • The cave template generates groups of blocks along underground surfaces. Typically this only works below sea level. If sea level is below Y level 20, however, it will work on any height instead.

    • By default, this template uses the cluster generator.
    • The default material for this template is Stone blocks.

    Other than the common values, this template needs the following value to be added to an entry:

    Name Required Type Default Description
    ceiling Yes Boolean N/A Whether the entry generates blocks on ceilings or floors. This is, for example, to prevent stalactites from generating on floors. If true, the entry generates blocks on ceilings, and if false, the entry generates blocks on floors.

  • The fractal template generates groups of blocks together in larger clusters, also called 'veins' in its options. Essentially, the 'veins' define general areas for groups of blocks to generate in.
    This template is can be used to generate enormous veins of ore, or other kinds of blocks.

    • By default, this template uses the large-vein generator.
    • The default material for this template is Stone blocks.

    Other than the common values, this template needs the following values to be added to an entry:

    Name Required Type Default Description
    minHeight Yes Number (integer) N/A The minimum Y level at which can be generated.
    veinHeight Yes Number (integer) N/A The vertical diameter of veins, measured in blocks along the Y axis.
    veinDiameter Yes Number (integer) N/A The horizontal diameter of veins, measured in blocks along the X and Z axes.
    verticalDensity Yes Number (integer) N/A How far apart different groups of blocks are along the Y axis in veins. Higher numbers mean that different groups are closer together, making veins contain more blocks in total. This value isn't measured in blocks. One will have to experiment with this value to obtain a desired result.
    horizontalDensity Yes Number (integer) N/A Ditto, except along the X and Z axes, instead of along the Y axis.

Generator types

This section describes all the different generator types that CoFH Core provides. A generator actually generates groups of blocks after a template determined a location for it.
Click on the name of a generator type to see information about it.

  • The cluster generator creates 'blobs' of blocks. This template is most commonly used for generating basic ore veins.
    Minecraft generates ores and dirt/gravel pockets like this.

    • The clusterSize value in entries determines how large the blobs are. However, it is hard to determine how exactly it affects the amount of blocks generated. It is capped at 32, and will be interpreted as 32 if it has a higher number.
      For reference, have a look in the default Vanilla.json file to see examples of clusterSize values, and what the results of those entries are.

  • The sparse-cluster generator is mostly the same as the cluster generator, with one notable exception. When using very small clusterSize values in entries (about 4 or less), clusters will only have a certain chance to actually generate, instead of generating a single block or so every time. At 3, 1 in 3 clusters will actually generate. At 2 it is 1 in 6 clusters, and at 1 it is 1 in 12 clusters.

  • The large-vein generator can be used to create veins that have a (much) larger clusterSize than the cluster generator can handle.

    • The clusterSize value in entries determines roughly how large veins are. Unlike cluster, there is no cap specified here. Use with caution.

    This generator can have the following value added to the template object:

    Name Type Default Description
    sparse Boolean true Used to determine the shape and density of veins. If true, veins will be smaller and more spread out, and will look somewhat like neurons. The clusterSize value in entries then determines roughly how many blocks a single vein contains. If false, veins will be much larger and more dense, somewhat closer to how the cluster generator works. It is also hard to predict how the clusterSize value affects the resulting amount of blocks in this case, but it seems to be tied exponentially.

  • The decoration generator creates groups of blocks scattered around on surfaces.
    Minecraft generates Tall Grass, Flower and Cactus blocks like this, and also Fire blocks in the Nether.

    • Meant to only be used with the decorator template.
    • The clusterSize value in entries determines how many blocks a single group may contain at most.

    A quirk of maintaining compatibility with an old format for custom world generation files requires that an empty material array is specified when using this generator and the corresponding template: "material": []

    This generator can have the following values added to the template object:

    Name Type Default Description
    genSurface Block entry / Array of block entries Grass Block The surface or surfaces to generate on top of.
    genSky Boolean true Whether to only generate on blocks that have a direct line of sight to the sky.
    checkStay Boolean true Specifies whether to only generate blocks if they can be sustained by the blocks they are generated on top of. For example, sugar canes cannot be sustained by blocks that are not directly next to water.
    stackHeight Number (integer) 1 How many times to stack a single generated block upwards. Used for things like cacti or sugar canes.
    xVariance Number (integer) 8 How spread out a group of blocks may be, in blocks along the X axis.
    yVariance Number (integer) 4 Ditto, except along the Y axis.
    zVariance Number (integer) 8 Ditto, except along the Z axis.

  • The small-tree generator creates simple trees, with a column of blocks that act as a trunk, and a group of blocks that act as leaves.
    Minecraft generates small Oak and Birch trees like this.

    • The block value in entries determines what kind of blocks the trunk of trees consists of.
    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    genMaterial Block entry / Array of block entries N/A, or Air if invalid What materials trees can generate in. Not quite the same as the material value in entries, as that value determines where the trees' bases may generate.
    leaves Block entry / Array of block entries N/A What blocks the leaves of trees are made of.
    minHeight Number (integer) 5 The minimum height of trees, in blocks.
    heightVariance Number (integer) 3 How much may be added randomly the the minimum height of trees, in blocks.
    treeChecks Boolean true Whether to verify that trees can properly 'grow' in the locations determined by the template used.
    relaxedGrowth Boolean false Whether trees can have blocks adjacent to their trunk at the bottom-most layer. For example, this could let trees generate one block deep in water.
    waterLoving Boolean false Whether to allow trees to generate in water, up to the leaves.
    leafVariance Boolean true Whether or not blocks can be missing from the corners of the leaves. This gives the leaves a more rounded look.

  • The plate generator creates cylinders with a configurable height.
    Minecraft generates underwater 'splotches' of Sand blocks like this.

    • The clusterSize value determines the radius of the cylinders.

    This generator can have the following values added to the template object:

    Name Type Default Description
    sizeVariance Number (integer) 2 How much a particular plate's radius may differ from the radius set by clusterSize (see above).
    height Number (integer) 1 Used to determine the height of the plates in blocks. This value is used as some kind of radius around a layer of blocks that is always present. For example, using 1 here will result in a plate of 3 blocks high: the middle layer, 1 layer above and 1 layer below.
    slim Boolean false This will make the plates be 1 layer of blocks less tall at the top. Usually plates have an odd height due to how they are generated (see height), so this lets plates generate with even heights.

  • The boulder generator creates sphere-like groups of blocks. Large boulders may look like parts of them are chipped off; however, that's just the way they are generated.
    Minecraft generates the cobblestone boulders in Mega Taiga biomes like this.

    • The clusterSize value in entries determines the radius of boulders, in blocks.
    • Other than the numClusters value in entries, this generator has a count value of its. This is because the generator can, in turn, generate multiple boulders in a small group.

    This generator can have the following values added to the template object:

    Name Type Default Description
    sizeVariance Number (integer) 2 How much a particular boulder's radius may differ from the radius set by clusterSize (see above).
    count Number (integer) 3 How many boulders a single group can contain.
    hollow Boolean false Whether boulders have a room filled with Air blocks inside. This can be used to replicate the Abyssal Stone geodes from Railcraft.
    hollowSize Number (floating-point) 0.1665 Relatively how large the hollow part of boulders is on the inside, if they are set to be hollow. Can be any value between 0.0 (exclusive) and 1.0 (exclusive).
    hollowVar Number (floating-point) 0.0 Relatively how much the hollowSize value may differ per boulder.
    The resulting value is calculated as: hollowSize * (1 - [random 0.0-1.0] * hollowVar).

  • The lake generator creates ponds of (usually) fluid blocks, carving out space if needed in the process.
    Minecraft generates this kind of 'lakes' using water or lava, both on the surface and underground.

    • The block value in entries determines what kind of blocks the 'fluid' part of the lake consists of.
    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    useMaterial Boolean false Whether the generator takes the material value in entries into account, or ignores it and uses any block as a material.
    outlineBlock Block entry / Array of block entries null The block or blocks to surround the 'fluid' part of lakes with.
    outlineWithStone Boolean false A shortcut to set the outlineBlock value to Stone.
    gapBlock Block entry / Array of block entries Air The block or blocks that are used to 'carve' out space above lakes.

  • The geode generator creates 'blobs' of blocks that are surrounded by a layer of blocks called the crust, and can optionally be hollowed out and then filled with a group of blocks called the filler. Geodes procuded by this generator can be seen as fully-encased lakes that don't carve out any space.

    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    crust Block entry / Array of block entries Stone What blocks the crust of geodes are made of.
    hollow 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. Instead, whatever blocks that were there before the generation will stay, unless a filler is specified.
    filler Block entry / Array of block entries null What blocks the filler of geodes are made of. If specified, hollow must be true for this to work correctly.

  • The spike generator creates simple upward-pointing spikes. Large spikes may also be generated, which are the same as normal spikes, except with a tall column of blocks as filler added in somewhere. The spikes also have some kind of 'roots' below them that extends a few blocks into the surface they are generated on.
    This kind of generation is used by Minecraft to generate the spikes in the Ice Plains Spikes biome.

    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    minHeight Number (integer) 7 The minimum height of spikes, in blocks.
    heightVariance Number (integer) 4 How much may be added randomly to the minimum height of spikes, in blocks.
    sizeVariance Number (integer) 2 How much may be added randomly to the radius of spikes at the bottom, in blocks.
    positionVariance Number (integer) 4 A random offset along the Y axis when determining the position of spikes.
    largeSpikes Boolean true Whether large spikes may generate along with regular spikes.
    largeSpikeChance Number (integer) 60 How rare large spikes are, if they are enabled. One in [value] spikes generated will be a large spike.
    minLargeSpikeHeightGain Number (integer) 10 How much taller large spikes are than regular spikes at minimum, in blocks.
    largeSpikeHeightVariance Number (integer) 30 How much may be added randomly to the minimum height gain of large spikes, in blocks.
    largeSpikeFillerSize Number (integer) 1 The radius of the extra layers that large spikes have, in blocks.

  • The stalagmite generator creates upward-pointing spikes. Unlike the spikes created by the spike generator that usually have a mostly uniform width, these spikes are usually much wider at the bottom and much thinner at the top.

    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    genBody Block entry / Array of block entries Air What materials the body of stalagmites can generate in. Not quite the same as the material value in entries, as that value determines where the base may generate.
    minHeight Number (integer) 7 The minimum height of stalagmites, in blocks.
    heightVariance Number (integer) 4 How much may be added randomly to the minimum height of stalagmites, in blocks.
    genSize Number (integer) 0 The minimum width of stalagmites at their base, in blocks. If set to 0, the heightMod value will be used to calculate the base width.
    heightMod Number (integer) 5 If genSize is set to 0, the height of stalagmites is divided by this value to get the base width of the spike in blocks.
    sizeVariance Number (integer) 2 How much may be added randomly to the minimum width of stalagmites at their base, in blocks.
    smooth 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 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 almost exactly the same as the stalagmite generator, with the key difference that the spikes created by this generator point downwards instead of upwards.

  • The dungeon generator creates chambers with a Monster Spawner in them. They can be set to generate near open areas, so that they have openings in the walls for monsters to wander out of. They can also have one or more loot chests in them. Dungeons have no ceilings of their own; those are made of whatever block is above them, if any.

    • The block value in entries specifies what blocks the walls of the chambers are made of.
    • This generator does not use the clusterSize value in entries.

    This generator can have the following values added to the template object:

    Name Type Default Description
    spawnEntity Entity entry / Array of entity entries Pig What kind of entities are spawned by the Monster Spawner in dungeons.
    spawnerFloor Block entry / Array of block entries block value in entries What blocks the floor of dungeons are made of.
    lootTable String / Array of weighted String entries dungeonChest Which loot tables the chests in dungeons can use. A list of the default loot tables can be found here. Some mods may also add their own loot tables. If those are intended to be used, the source code of the mods will have to be read to find the names.
    maxChests Number (integer) 2 The maximum amount of loot chests per dungeon.
    chestAttempts Number (integer) 3 The amount of times to attempt to place each loot chest in a dungeon before giving up on placing one. Can be any value between 1 (inclusive) and 5 (inclusive).
    minHoles Number (integer) 1 The minimum amount of holes that a single dungeon must have in it. A hole is defined as an opening in the wall of a dungeon at the floor level, that is at least two blocks high. This option can be used to make dungeons generate in caves or near other open spaces.
    maxHoles Number (integer) 5 The maximum amount of holes that a single dungeon can have in it.
    minHeight Number (integer) 3 The minimum height of the dungeons, in blocks.
    maxHeight Number (integer) 3 The maximum height of the dungeons, in blocks.
    minWidthX Number (integer) 2 The minimum width of the dungeons along the X axis, in blocks.
    maxWidthX Number (integer) 3 The maximum width of the dungeons along the X axis, in blocks.
    minWidthZ Number (integer) 2 The minimum width of the dungeons along the Z axis, in blocks.
    maxWidthZ Number (integer) 3 The maximum width of the dungeons along the Z axis, in blocks.

Other formats

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

Weighted String entry

This format describes a String with an associated weight, for use in randomization. Weighted String entries only useful in Arrays that can be randomly picked from.

A weighted String entry can be either an Object or a String value.

If specified as an Object, said Object can contain the following values.

Name Required Type Default Description
name Yes String N/A The String itself.
weight No Number (integer) 100 Used to determine the chance of the entry being picked from the Array it's in.

If specified as a String, the name value seen above can be used directly. The weight value will be set to its default.

Block entry

This format describes a certain type of block.

A block entry can be either an Object or a String value.

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. For example, minecraft:stone translates to Stone, and ThermalFoundation:Ore translates to the ore block from Thermal Foundation. If the block is from Minecraft itself, the minecraft: prefix is not required.
metadata No Number (integer) 0 The metadata of the block. Most of the time, the metadata of a block is equal to the damage value of its item form.
weight No Number (integer) 100 Used to determine the chance of the entry being picked from an Array it's in.

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

Biome entry

This format describes a biome or a set of biomes that have something in common.

A biome entry can be either an Object or a String value.

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, temperature and dictionary.
entry Yes Number (integer) 0 Used to match biomes. Differs depending on the type of the entry.
  • If type is set to name, this value can be either a single biome name String or an Array of them. Biomes are matched by their exact name, so partial names do not work. Biome names can be found ingame using the F3 debug screen.
  • If type is set to temperature, this value can be either a single temperature category String or an Array of them. Possible temperature categories are OCEAN, COLD, MEDIUM and WARM.
  • If type is set to dictionary, this value can be either a single Forge biome tag String or an Array here. A list of possible Forge biome tags can be found here.
whitelist No Boolean true If set to false, the biome entry will counteract the blacklist or whitelist it is part of.
rarity No Number (integer) 1 Adds a random chance to determining whether a biome matches the entry. One in [value] attempts to match a matching biome will go through. This can be used to make some kind of generation rarer in certain biomes.

If specified as a String, the entry will be treated as a biome name to match biomes with. Biomes are matched by their exact name, so partial names do not work. Biome names can be found ingame using the F3 debug screen.

Entity entry

This format describes an entity and its properties.

An entity entry can be either an Object or a String value.

If specified as an Object, said Object can contain the following values.

Name Required Type Default Description
entity Only if spawnerTag is unspecified String N/A The internal name of the entity, like Creeper or PigZombie. Ignored if spawnerTag is specified.
spawnerTag No String (Object) N/A A much more specific way of defining an entity. Can contain values as defined here. Must be specified as a serialized Object: a String that represents an Object.
weight No Number (integer) 100 Used to determine the chance of the entry being picked from an Array it's in.

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

Useful resources

This section lists resources that can be useful when setting up world generation with CoFH Core.

Mods

© Copyright 2017 Team CoFH. Powered by GitHub Pages, Jekyll, UIkit.
Last updated: 2017-09-24 08:15:07 +0000