main/Configuration 2.1

[This page refers to an older version of this plugin!]

Configuration

When making changes to the configuration file, watch out for problems arising from bad formatting such as not keeping the same indentation. Before activating your new configuration, always perform a check with a YAML parser (e.g. the online YAML parser, Notepad Plus Plus, etc.).
The plugin can cope with optional child configuration files, which can be linked in a hierarchical manner. This is useful for having configuration files per world and/or biomes that just override some settings defined in the parent config. From this perspective, the settings can fall in one of the following categories:

root config only: It can only appear at the root level. If present in a child config, it will either error or is going to be ignored.
not inherited: Can appear in a child configuration, but its value in a parent config will not get inherited by a child config.
inherited: The setting present in the parent configuration file can be completely overriden in a child configuration file.
inherited combined: Usually refers to entire configuration sections. Any setting in a parent configuration section will be inherited and combined with any values present in the same section of a child configuration. If there is a way to turn a parent setting off, this is documented on a case by case basis.

For a child configuration, the Plugin section must include at least one of the following: worldConstraints, worldExclusions, biomeConstraints or biomeExclusions. When processing an area, the plugin will attempt to go as deep as possible on the first accessible path, given the world and biome of the current area that is about to get processed.

Global Settings

childConfigurations (not inherited, default: []):
Allows for overrides to be applied to the settings defined in the current configuration file by chaining child configuration files in a hierarchical manner. See the samples at the end of this document for examples.
This setting is valid for both the root and child configurations.
Example: childConfigurations: [world_overrides.yml]

worldConstraints (not inherited, default for the root config: []):
Constrains the auto or manual mode to the worlds which names are listed here.
This setting is valid for both the root and child configurations.
Example: worldConstrains: [My World, And here is another one]

worldExclusions (not inherited, default for the root config: []):
Worlds to be ignored in auto or manual mode.
This setting is valid for both the root and child configurations.
Example: worldConstrains: [My World, And here is another one]

biomeExclusions (not inherited, default for the root config: [HELL, SKY]): Biomes to be excluded in auto or manual mode.
This setting is valid for both the root and child configurations.
The plugin is not supported in 'The Nether' or 'The End'. so the default restrictions are required. In addition, you can add other values such as: SWAMPLAND, FOREST, TAIGA, DESERT, PLAINS, HELL, SKY, OCEAN, RIVER, EXTREME_HILLS, FROZEN_OCEAN, FROZEN_RIVER, ICE_PLAINS, ICE_MOUNTAINS, MUSHROOM_ISLAND, MUSHROOM_SHORE, BEACH, DESERT_HILLS, FOREST_HILLS, TAIGA_HILLS, SMALL_MOUNTAINS, JUNGLE, JUNGLE_HILLS;

biomeConstraints (not inherited, default for the root config: []): Constrains the auto or manual mode for the biomes listed here.
The same values as the ones for the biomeExclusions are accepted here.
This setting is valid for both the root and child configurations.

areaLengthChunks/areaWidthChunks (root config only, default: 10) :
The size of an 'area', in chunks, used for analysis and ore population (a value of 10 means 160x160 in world coordinates). Large areas provide better player experience, but this is limited by the computational power of your rig, so tune it to find a balanced value. You can achieve this by watching the time required to process an area and figuring out what delay is acceptable. Remember, generally a player won't start digging to look for ore as soon as he or she reached a new area.
Warning! Changing these two values will reset the state of the already processed areas, allowing them to be repopulated with ore.
These two settings are only accepted in the root configuration file.

Advanced Global Settings

Don't change these values unless you really need to.

maxSyncWorkloadMillisecondsPerServerTick (root config only, default: 30):
Maximum time to spend in sync stages per server tick. This setting will have no effect on async stages.

maxAsyncWorkloadMultiplier (root config only, default: 0.8):
Multiplier for the number of threads that are being used for the async stages. The multiplier is applied to the number of CPU cores minus one.

logLevel (root config only, default: Info):
Possible values: Debug, Detailed, Info, Error

Definitions (root config only)

You can reference any standard material throughout the configuration files. A list can be found in the org.bukkit.Material code file.
But you'll have to let the plugin know about all the non-standard items and materials you're going to then reference later in the config. The name you're giving to these materials makes no sense outside the scope of this plugin.
There are a couple of scenarios where you'll want to add a new definition:

Extend an existing item or material by providing metadata information in the data block. You can find out more about the subject, including what the values mean, on this page.

    JACK_O_LANTERN_SOUTH:
        referencedMaterialName: JACK_O_LANTERN
        typeData: 0
    JACK_O_LANTERN_NORTH:
        referencedMaterialName: JACK_O_LANTERN
        typeData: 2

Define a custom material, required by other plugins.
Example for SimpleOres:

   MYTHRIL_ORE:
       typeId: 194

Sometimes you'll also have to define the metadata for your custom material as well. Provide this value only if the other plugins require it. If the metadata is just being used by those plugins to store some state rather than differentiate between different types of materials, then by all means don't include it here.

   OPAL_ORE:
       typeId: 194
       typeData: 12

This section must be present only in the root configuration file. Values cannot be added or superseeded in child configs.

Cave Finder Settings

caveMaterials (inherited combined):
Materials and items a cave is made of and their associated value. Sum up the values of the blocks making out a cave and you have the final 'value' of a cave. The analysis stage deals with the most valuable caves first. The valuation of caves is however far less important than defining the materials that make out a cave, so don't spend too much time thinking about associating them with a value.

        WATER: 0.05
        AIR: 1.00
        MOB_SPAWNER: 500.0
        CHEST: 1000.0

Warning! Do not add STATIONARY_WATER as a cave material as that will cause oceans to be taken into account, ultimately ripping your server apart. I'm kidding :) Just don't do it, alright?
If this section is present in a child configuration file, the final result is a combination of this section and the one present in the parent. Individual materials can be turned off in a child configuration by setting the material's value to 0.0.

maximumCaveBlocksCount (inherited, default for the root config: 5000):
Threshold for the maximum number of blocks per cave. Caves will be logically split by the algorithm after reaching this value.

caveMinimumValue (inherited, default for the root config: 10.0):
Minimum total value for a cave to be considered.

Ore Spawner Settings

autoMode (inherited, default for the root config: true):
If auto-mode is turned on, the plugin will automatically process new/unprocessed areas as soon as they are discovered by players.

replaceableMaterials (inherited, default for the root config: [STONE, DIRT, GRAVEL, MOSSY_COBBLESTONE]):
Materials that can be replaced by ore. They also represent the walls of the caves.
Individual materials cannot be added or removed in a child configuration file (you'll have to set the entire list).

existingOreCleanupMaterial (inherited, default for the root config: STONE):
Material used to clean up the existing ores found in an area. A cleanup stage always occurs before population.

veinOreDensity: (inherited, default for the root config: 0.4):
Ore density, inside a vein. 1.0 means all the blocks on a vein path will be filled with ore. This will create the blocky veins we've seen in version 1.0.
Applies to all the ores, unless overridden by the individual ore setting.

maxCaveWallsOreDensity (inherited, default for the root config: 0.6):
Maximum distribution of ore on the cave walls. Maximum value is 1.0 and that represents 100%.

maxVeinArcDeviationPerLength (inherited, default for the root config: 10/50):
Used in the vein path generation, after the two endpoints have been found. Represents the maximum amplitude of an ore vein, or deviation from the path, per vein length, both values being in blocks. As an example, with the default setting, for a path of 100 blocks in length, the maximum deviation from the computed path will be 20 blocks.
Since the inclusion of noise in version 2.0, another meaning was assigned to the second value. Now it also controls the frequency of the noise, or in other words, larger values for this parameter translates into less noise on the path and thus straighter veins.

Ore Distribution (inherited combined)

Each ore has its own section. Ores are identified by their name, referenced from the definition section of the config, if present. If not defined in there, it will be assumed the name reflects a standard ore material.
You can override any individual setting in here in a child configuration file, assuming the parent contains the other settings for a particular material. The generation of a particular ore can be turned off by setting its 'percentage' to 0.0. which means it will just get cleaned off from the area.

minLevel/maxLevel (inherited)
The ore will get spawned within the minimum and the maximum height level. Bedrock is at 0.

percentage (inherited)
The percentage of ore blocks to be spawned within an area out of the total underground blocks. The plugin will attempt to reach this value but this doesn't mean it will actually succeed. Assign a decent value to this parameter, to give a chance for other ores to be spawned as well, otherwise they'd start to cannibalize themselves. The maximum value is 1.0 (100%) and should never be used. You're most likely going to work with very low values around 0.001 (0.1%). Start from the default configuration file and slightly change the value.
A value of 0.0 will turn this ore off, meaning it will still get cleaned but none will get spawned.
Sometimes CraftBukkit will save the config file expressing this value in a scientific notation (xE-y = x / 10^y), for very low values, but you don't have to use that notation.

veinThickness (inherited)
The thickness of the veins, in blocks, for this type of ore. A value of 0 turns this ore off in the generation stage. 5 produces rather thick veins.

maxVeinLength (inherited)
The maximum length of the vein, in blocks. For pockets of ore, you may want to keep this value low (around 2 or 4), whilst for long veins, you may go as high as the area size.

allowedToSpawnUnattachedVeins (inherited, default for the root config: false)
When true, the ore generator will attempt to create veins unattached to a cave at one end, in case the desired percentage could not be reached through standard cave to cave vein links.
You can use this setting to spawn pockets of ore on the cave walls, in which case you'd keep the maxVeinLength to a low value (around 4).

veinOreDensity (inherited, default for the root config: the value of the global setting 'veinOreDensity')
Ore density, inside a vein. 1.0 means all the blocks on a vein path will be filled with ore. This will create the blocky veins we've seen in version 1.0.
If not present, the global setting will be used. It makes sense to have this value closer to maximum for pockets of ore and slim veins (around 0.6 to 0.8) and a low value for bigger longer veins (around 0.4 for a 5 blocks thick vein for example).

allowedToSpawnStructures(inherited, default for the root config: false)
When true, the ore generator will attempt to generate another cave (vein hub) at one end of the vein, in case the desired percentage could not be reached through standard cave to cave vein links.
If you set this value to true, ensure the maxVeinLength is big enough to cope with the generation of such a structure, as the algorithm ensures it doesn't clash with other underground elements. See newCaveStructureLayout and newCaveMinClearance for details about setting up such a structure.

Advanced New Cave Settings

New cave structures will be created when one of the ore veins could not hit the desired distribution and its allowedToSpawnStructures setting has a value of true.

newCaveMinClearance (inherited, default for the root config: 20):
The minimum clearance for a new cave to be generated, in blocks, in relation to the other underground elements already present.

newCaveStructureLayout (inherited combined)
Through this setting you can define the layout of the new cave. The elements defined here will be applied in the order of their appearance, and they are allowed to overlap.
As this section combines the values from a child config file and its parent, if you wish to turn an element off, you'll have to assign it an empty value(e.g.: JACK_O_LANTERN_SOUTH: [])
Let's see how cave generation works now. Assume your cave has a central point, having the coordinates of (0,0,0). The cave must have a valid shell in order to be taken into account by the ore generation algorithm. Hence we start with a material from the ones set up in replaceableMaterials:

       STONE:
            - from [-5, -4, -5] to [ 5,  3,  5]

The from and to represent the two opposite vertices of a rectangular cuboid that will be filled with stone. The coordinates are relative to our imaginary center point at (0,0,0).
It is mandatory for the cave to be formed at least from one of the elements defined in caveMaterials. So we're gonna start to carve some air:

        AIR:
            - from [-4, -2, -4] to [ 4,  2,  4]

We're happy with that. Let's pave the floor with some mossy cobblestone:

        MOSSY_COBBLESTONE:
            - from [-4, -3, -4] to [ 4, -3,  4]

Got our floor, next let's add some scary jack-o-lanterns in the corners. We cannot have duplicates in the config, so this is how we group them up:

        JACK_O_LANTERN_SOUTH:
            - at [ -4, -2,  -4]
            - at [ 4, -2,  -4]
        JACK_O_LANTERN_NORTH:
            - at [ -4, -2,  4]
            - at [ 4, -2,  4]

You notice that instead of from and to I used at, which corresponds to a single relative location. The two materials are derivations from the standard, as they require the data field to be set up in order to appear facing different directions. An example of how to achieve this can be found in the Definitions section.
We got our structure. One annoying limitation at the moment is that you cannot place chests or mob spawners, or other entities. Even if you have defined them in the Definitions section, the plugin cannot spawn them properly in the world.

Samples

For your reference, the fully commented default configuration file can be found here.
A sample of chaining configuration files can be found here.

Cave Ore Veins

Bukkit Plugins

Pages

Table of Contents