Pages

main/Configuration 3.0

The main configuration file is created the moment the plugin is activated, inside the <bukkit_folder>/plugins/CaveOreVeins folder. You'll notice another folder in there named "world_states". That one holds the state of the processed game areas and should never be touched, as it holds the coordinates of the areas that have already been populated.

The format Bukkit is using to store configuration settings, for itself and for the plugins, is prone to user errors. When making changes to the configuration file, watch out for problems arising from bad formatting, mostly invalid indentation, which will render the entire config invalid. Never use TAB characters, either before or after a line, and keep a consistent number of space characters for the same indentation levels! Before activating your new configuration, always perform a check with the online YAML parser.

Child Configurations

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, trying to find a suitable configuration, given the world and biome of the current area that is about to get processed.

Material Definitions

Before you go ahead and make changes to the settings, first make sure you've got what you need. What type of ores, creature spawners, chest items, are you planning on using? Do you have other plugins and mods installed that add custom ores to the game? All these are defined in the file "definitions.yml". Head over here, for a thorough discussion on how to use it.

Plugin Settings

  • enableUpdateCheck (root config only, default: true):
    Enables update checks and gives the developer statistical information about the plugin version and the CB version in order to concentrate the efforts on maintaining compatibility with the most played versions. When enabled, it will inform you in the server console, on startup, if a new version has been released, and a short description of the new features and bug fixes. Regardless of the value for this setting, the plugin will never attempt to automatically update to a newer version.
  • 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.
    These settings are only accepted in the root configuration file.
    • Warning! Changing these two values will reset the state of the already processed areas, allowing the plugin to repopulate them with ore.
  • logLevel (root config only, default: Info):
    Possible values: Debug, Detailed, Info, Error
    The Info level is good for having a bird's eye view on how the plugin reacts on your server. Error will switch off the informational messages which after a while can become annoying and will just fill your server log file. In this mode, only errors will be shown. Detail will output messages regarding each stage the plugin is going through attempting to execute requests.

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.
  • ceiling (inherited, default for the root config: auto):
    If the config applies to a world where there is an enforced ceiling, set this setting to its location on the Y axis.
    For example, in the Nether, the ceiling is at about 127. Bukkit fails to report the highest block in this particular case, so this setting is mandatory for that world.
    This setting was introduced in 3.2.0.

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.
  • veinOreDensityPercentage: (inherited, default for the root config: 40):
    Ore density, in percentages, inside a vein. 100 is the maximum and means all the blocks on a vein path will be filled with ore. For thick veins this will create an ugly blocky effect, reason why having it at this value is not recommended.
    Applies to all the ores, unless overridden by the individual ore density setting.
  • maxCaveWallsOrePercentage (inherited, default for the root config: 60):
    Maximum number of ore blocks seen on the cave walls. Maximum value is 100 and that allows for the entire cave walls to be decorated with ore.
  • maxVeinArcDeviationPerLength (inherited, default for the root config: 10/60):
    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 60 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.
  • amountPercentage (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 100, which means 100% of all the underground blocks, and should never be used. You're most likely going to work with very low values around 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 long as the area size (computed as areaLengthChunks * 16, which by default is 10*16 = 160 blocks).
  • orePocketMode (inherited, default for the root config: false)
    When true, the ore generator will attempt to create veins unattached to a cave at one end.
    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.
  • veinOreDensityPercentage (inherited, default for the root config: the value of the global setting 'veinOreDensityPercentage')
    Ore density, inside a vein. 100 is the maximum and means all the blocks on a vein path will be filled with ore. For thick veins this will create an ugly blocky effect and the impurities are not allowed to spawn, reasons why having it at this value is not recommended.
    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 60 to 80) and a low value for bigger longer veins (around 40 for a 5 blocks thick vein for example).
  • impurities (inherited combined)
    This section allows you to set what else can appear in an ore vein, apart from the actual material for the ore. Impurities may appear as other ore materials, creature spawners, structures, etc. See the documentation referring to material definitions for more information.
    • frequency (inherited)
      Minimum distance, in blocks, between impurities of the same type.
    • spawnProbabilityPercentage (inherited)
      The chance of the impurity to appear. A value of 100 means the generator will attempt to spawn an instance at every 'frequency' blocks on the vein path. A value of 0 will turn this impurity off, which could be useful in a child configuration.

Advanced Global Settings (Plugin Section)

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

  • syncWorkloadTriggerServerTicks (hidden setting, root config only, default: 10):
    Having a minimum of 1, this setting controls the responsiveness of the plugin in sync stages (snapshotting an area, rendering the output, etc.) and when acknowledging a command. Lowering this value won't do any good, as the Bukkit server would start yelling about not being able to catch up. Increasing it would alleviate potential lag issues you might experience on the client side, giving more time to the game engine to breathe.
  • maxSyncWorkloadMillisecondsPerServerTick (hidden setting, root config only, default: 30):
    Maximum time to spend in sync stages per server tick. This setting will have no effect on async stages. Minecraft's main game loop runs at a fixed rate of 20 ticks per seconds, which means there are a maximum of 50 milliseconds to spend in a server tick before starting to choke.
  • maxAsyncWorkloadMultiplier (hidden setting, 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.
  • enableFastRenderingMode (hidden setting, root config only, default: false):
    Not working when the plugin is running under MCPC+ 1.4.7 and later versions.
    You can set this setting to true to optimize the rendering stage, including the amount of notifications players receive when a nearby area gets updated. As this method is not using the Bukkit API, it's not future proof, but the code will fallback to the normal fail-safe method if an error is encountered whilst processing.
    Fast rendering could prevent lighting computations.

Samples

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