Documentation

Here, we document the features added to the original mod. For the rest of the documentation, please see the original wiki.

Changes to configuration management

The original mod never overwrote an existing config file. This requires user intervention for pushing updates to the standard configuration. Most mods merge new configuration options into old configs. This creates a mess and would be too complicated for our rich XML-based config files. Thus, we will now overwrite default configs, while still allowing for user customization. If the player has never modified the COG config, reading further is optional.

Directory structure

All config files will now live under CustomOreGen. Here is the precise layout:

CustomOreGen/
CustomOreGen/CustomOreGen_Config_Default.xml
CustomOreGen/modules
CustomOreGen/modules/default
CustomOreGen/modules/default/MinecraftOres.xml
CustomOreGen/modules/default/Forestry.xml
CustomOreGen/modules/default/...
CustomOreGen/modules/custom
CustomOreGen/modules/custom/[MyOres.xml]

The CustomOreGen_Config_Default.xml file will be replaced every time the mod loads. Before modifying it, copy it to CustomOreGen_Config.xml. Much like before, there is a separate directory for standard and custom modules. However, the standard directory, modules/default is now repopulated every time the mod loads. The modules/custom directory is never touched; users may place any extra configurations there without worries. To override a default config, it is necessary to change the import directives in CustomOreGen_Config.xml, which of course should be marked as custom.

Upgrade instructions

If the player has never modified the COG config, no action is required.

If the player has added an extra config…

The files in CustomOreGen Extra Modules should be moved to CustomOreGen/modules/custom.

If the player has modified CustomOreGen_Config.xml…

The player should copy it to CustomOreGen/CustomOreGen_Config.xml and merge updates from CustomOreGen/CustomOreGen_Config_Default.xml. Note that changing the base config in this way essentially opts out of config automatic updates. New standard configurations will not be loaded until the new defaults have been merged.

If the player has modified a standard config…

These files should be copied to CustomOreGen/modules/custom and the import directives in CustomOreGen/CustomOreGen_Config.xml should be modified accordingly, i.e., drop the import of the default module configs.

Height Clamping

All distributions have gained absolute minHeight and maxHeight attributes, just as <Substitute> has had for a while. These attributes allow for asymmetric (truncated) height distributions.

Height Scaling

While chunks have a constant surface area of 16x16, the height of a chunk can vary dramatically. It is often desirable to have ore distributions spread throughout a chunk, depending on the height. One might also want to scale the frequency by height, so that the ore density remains roughly constant.

The scaleTo attribute

The scaleTo attribute addresses this issue by enabling the scaling of a setting according to a specific notion of the local height. The math is simply value*scale/base where base is currently fixed to 64. The value of scaleTo is a string naming the scale, and there are currently four height scales:

• Base: the default, essentially the identity transformation
• Sealevel: the global sealevel for the world (this is the same as Base for the Overworld)
• Biome: the average of the biome min/max height
• Surface: the current surface height (depends on ATG, currently broken)

The following settings support scaleTo: DistributionFrequency, Frequency, Height, OreDensity, CloudHeight, CloudThickness, MotherlodeFrequency, MotherlodeHeight, and BranchHeightLimit.

This example will multiply the height value of 50 by the average height of the current biome, divided by 64, which might allow an ore to generate up into the hills.

<Setting name='CloudHeight' avg='50' scaleTo='biome'/>

The “HeightOffset” setting

Sometimes it is desirable to have an unscaled offset added to the scaled height. This would allow, for example, an ore to always generate 3 blocks under the surface. The “HeightOffset” setting addresses this need.

Example of generating 3-5 blocks under the surface:

<Setting name='CloudHeight' avg='64' scaleTo='surface'/>
<Setting name='HeightOffset' avg='3' range='1'/>

Substitute surface relative height

The <Substitute> distribution has gained surface-relative height support through its minSurfRelHeight and maxSurfRelHeight attributes:

<Substitute name='Dummy' minSurfRelHeight='-2' maxSurfRelHeight='0'/>

The above would replace the top three blocks in all matching chunks. Note that the definition of surface is the highest block of material grass, ground, clay, sand (includes gravel), rock or ice.

Biome Selection

Biome Types

The <BiomeType> element supports the same attributes as <Biome>, and its behavior is identical, except that the name attribute matches Forge biome dictionary terms, instead of biome IDs/names. By selecting biomes via dictionary terms, a distribution will be automatically compatible with custom biome mods.

We place a coal cloud in any Jungle biome:

<Cloud name="CoalCloud" block="oreCoal">
  <BiomeType name="jungle"/>
</Cloud>

Biome Sets

The <BiomeSet> element enables sharing of biome selections across distributions. The name attribute indicates the name, and the inherits attribute refers to the parent biome set by name, and has analogous semantics to inherits on distribution elements. It is through the inherits attribute that a distribution refers to an externally defined biome set. The weight attribute has a multiplicative effect on the weights of the contained biome descriptors. Valid children of <BiomeSet> include: <Biome>, <BiomeType> and other <BiomeSet> elements.

Assume we want to select only continental, non-mountainous biomes. We could list the types of biomes to include, as below:

<BiomeSet name="continental">
  <BiomeType name="forest"/>
  <BiomeType name="plains"/>
  <BiomeType name="desert"/>
  <BiomeType name="swamp"/>
  <BiomeType name="jungle"/>
  <BiomeType name="frozen"/>
  <BiomeType name="beach"/>
  <Biome name="river"/>
</BiomeSet>

Note that river is not a biome dictionary term, it is simply the name of the river biome. The water type would include ocean. It is unfortunate that there is no type distinguishing oceans from rivers. Also, the frozen ocean is included by the frozen type, but if we leave it off, we lose Ice Plains and Ice Mountains (why do these not use the plains and mountains terms?).

So we need to exclude those.

<BiomeSet name='ocean'>
  <BiomeType name='water'/>
  <Biome name='river' weight='-1'/>
</BiomeSet>
<BiomeSet name="continental">
  <Biome name='.*'/>
  <BiomeSet inherits='ocean' weight='-1'/>
  <BiomeType name='mountain' weight='-1'/>
</BiomeSet>

Finally, a distribution might refer to a biome set like this:

<Cloud name="CoalCloud" block="oreCoal">
  <BiomeSet inherits="continental"/>
</Cloud>

Climate Selection

The <Biome> descriptor also has support for restricting by climate:

• minTemperature / maxTemperature attributes bounding the temperature,
• minRainfall / maxRainfall attributes bounding the rainfall.

To select a tropical (jungle?) biome, without relying on the sometimes ambiguous dictionary terms, we could select by the climate. Here, we restrict to tropical jungles:

<BiomeType name='jungle' minTemperature='1.2' minRainfail='0.9'/>

Here, we select any tropical biome:

<Biome name='.*' minTemperature='1.2' minRainfail='0.9'/>