Config File

Page last edited 1,650 days 22 hours ago
From COG Docs
Jump to: navigation, search

The CustomOreGen config file is named CustomOreGen_Config.xml. It is written in XML and contains every detail of COG's ore generation. XML has a bit of a learning curve, so the basics are given here. To make the file easier to read and understand, use a text editor with syntax highlighting like Notepad++.

For quick navigation, the main features of the config file are Options, Conditions, and Distributions (Veins, Cloud, StandardGen, and Substitute). All of these make use of Expressions.



XML Basics

The config file is written in XML, a markup language with similar syntax to the HTML used in webpages. A full tutorial on XML is way outside the scope of this page, but the basics are simple enough. An XML document is broken up into elements, each of which can contain text or other elements. This creates a tree-like structure. Each element starts and ends with the element name in angle brackets:

 <SomeElement>  This is the stuff inside the element </SomeElement>

If an element doesn't have anything inside it (which is pretty common), the start and end tags can be combined:

 <SomeElement />

An element with another element inside it might look like this:

 <ParentElement>  <ChildElement /> </ParentElement>

White space doesn't matter, so these elements can be rearranged as needed:

 <ParentElement>
   <ChildElement />
 </ParentElement>

XML comments begin with "<!--" and end with "-->":

 <!-- this is a comment - any program that reads this will ignore it -->

In addition to their contents, elements can have attributes, listed as name/value pairs in the opening tag:

 <SomeElement someAttribute='someValue' />

CustomOreGen uses attributes very extensively.

Everything in XML is CASE SENSITIVE. Be very careful with capitalization.


Special XML features in COG

CustomOreGen has a specially written parser that includes some powerful features not found in standard xml.

Annotations

<Description> and <Comment> elements can be placed anywhere in the config file. "Description" may also be used as an attribute for any element. Collectively these can be used to attach text annotations to anything in the config file. Some Descriptions are kept and used internally, but most annotations are simply discarded after being read. Even so, the contents of these annotations still need to be simple text or valid XML.

Child Elements as Attributes

Attributes are interchangeable with child elements of the same name. For example, these two elements would be considered identical by the COG parser:

 <Foo bar='biz' />
 <Foo> <Bar> biz </Bar> </Foo>

The second <Foo> element doesn't technically have a "bar" attribute, but the COG parser considers the contents of the <Bar> element to be equivalent. This is possible because the COG config file has been carefully designed to avoid overlap between attribute names and "real" element names.

Expressions

Attributes may be set with expressions. The expression is evaluated and the result is used as the attribute value. For example, the "bar" attribute here is assigned the result of 6 times 7, i.e. 42:

 <Foo bar=':= 6 * 7' />
 <Foo> <Bar>:= 6 * 7 </Bar> </Foo>

Conditions

Any part of the COG config file may be wrapped in a conditional element. Depending on the result of the condition, the contents of the conditional element will either be parsed as normal or discarded. For example, this Veins distribution will only be generated if the Redpower mod is installed:

 <IfModInstalled name='mod_RedPowerWorld'>
    <Veins name='rpCopperVeins' block='rpores:5'/>
 </IfModInstalled>

Sections

The <ConfigSection> element can be used to group together related elements. These sections are purely aesthetic; all child elements and attributes of the section are considered to be children of its parent element. For example, these two elements would be considered identical by the COG parser:

 <Foo bar='biz'> <Bat/> </Foo>
 <Foo> <ConfigSection bar='biz'> <Bat/> </ConfigSection> </Foo>

The "bar" attribute and "Bat" child element in the second line are read by the COG parser as being the children of the <Foo> element.

Imports

Configuration data from other XML files can be included using a import element. This allows a configuration fragment such as distributions for a single mod to be packaged and distributed as its own file and then imported into the main config.


The COG Config File

The CustomOreGen config file is named CustomOreGen_Config.xml. A copy of the "standard" config is created in the /config folder when the mod is first installed. This is the global config file. A saved world can be given its own config by placing the file in the world save folder (i.e. saves/New World). A single dimension in a saved world can be given its own config by placing the file in the dimension subfolder (i.e. saves/New World/DIM-1 for the New World Nether).

Location Description
Global Config config/ The default config for new worlds. Created automatically when COG first loads.
World Config [world folder]/ Overrides global config for a single world. Create manually if needed.

Since the Overworld does not have its own dimension folder this could also be called the "Overworld Config".

Dimension Config [world folder]/[dimension folder]/ Overrides global or world config for a single dimension. Create manually if needed.

In-game, COG loads the most specific configuration it can find for each dimension.

The root element of the config file must be a <Config> element. Everything else in the file (except xml comments) must be contained inside this element.

Within the root element distributions, options, and mystcraft symbols may be defined. These top-level elements are processed in the order in which they appear, so Options must be defined before any conditional elements or distributions that depend on them. Other than that there is no limit to the number or order of definitions in the config file.


Example

Here is an example config file containing one option and two distributions:

<Config> 

  <!-- Generate Iron ore in veins around height 32 -->
  <Veins name='IronVeins' block='oreIron'>
    <Setting name='MotherlodeHeight' avg='32' range='16'/>
  </Veins>

  <!-- The player can set the value of this option independently in each world -->
  <OptionChoice name='debugDist'>
    <Choice value='true'/>
    <Choice value='false'/>
  </OptionChoice>
  
  <!-- If "debugDist" is true, generate red wool in veins around height 150 -->
  <IfChoice name='debugDist' value='true'> 
    <Veins name='TestVeins' block='cloth:14'>
      <Setting name='MotherlodeHeight' avg='150' range='16'/>
      <Replaces block='air'/>
    </Veins>
  </IfChoice> 
   
</Config>