Options

Options are variables used to control how a config file loads. They work like this:

1. An option is defined in the config file with a name and a set of possible values.
2. The value of the option is loaded from an option file.
3. The option value is used later in the config file to change what distributions are loaded or their settings.

Options are useful because they allow a single config file to produce many different configurations. For example, the global config might contain both ore Veins and Clouds and use an option to decide which is generated. Each world can then have its own value for that option depending on whether the player wants veins or clouds in that world. This gives the player some freedom without having to set up separate configs for each world. With a few well-chosen options, the player might not have to open the config file at all.

Options are defined using the <OptionChoice> and <OptionNumeric> elements. See Option Types for details.

Option values are available in expressions by using the option name like a variable. Choice options can be referenced directly by the <IfChoice> conditional element.

In debugging mode the */cogOption* command can be used to temporarily change an option value.

## Option Files

CustomOreGen Option files are named *CustomOreGen\_Options.txt*. One will be created for each new world in the world save folder. This file is written in *name*=*value* form and lines that begin with a '#' are comments. The file can be modified by the player if necessary (changes will take effect when the world is reloaded or the */cogLoadConfig* command is used). A single dimension in a saved world can be given its own options file by placing the file in the dimension subfolder. This is done automatically for dimensions that have their own configs. A global options file can be created by placing the file in the */config* folder. This will set the default option values for new worlds.

 **Dimension Config** | [world folder]*/*[dimension folder]*/* | Created automatically when the dimension is first loaded for dimensions that have their own config file.
Can also be created manually if needed.

For each dimension, COG loads any options files it finds in order from least-specific to most-specific starting at the level of the config file.

 Dimension-specific Config | Dimension Options only

Option files do not need to have a value for every option defined in the config. Any that are left out simply use the value from the previously loaded file, or from the default encoded into the option definition if they don't appear in any file at all.

### Example

```
#Custom Ore Gen @VERSION@ Config Options

#Tue Jan 30 08:29:37 CET 2018
deferredPopulationRange=32.0
debugMode=true

```

## In-Game Options Menu

CustomOreGen provides an options menu during world creation. The options and values shown are from the Global config file. The player can adjust the values before creating the world, and the results will be used to create the world options file. If the world already has its own config file or options file (because the player created them manually before creating the world) then the options menu has no effect.

The menu can be opened by clicking the **Custom Ore Generation ...** button in the world creation menu. Mousing over the option names or values will bring up a tooltip description.

### Display Groups

Options can be organized into Display Groups, which appear as tabs at the top of the menu. The <OptionDisplayGroup> element defines a display group, and has the following attributes:

<OptionDisplayGroup>
 displayState | hidden
* *hidden* groups are not visible
 description | *nothing* | A short description of the group. Used as tool-tip text in the Options menu.

Example:

```
<OptionDisplayGroup name='groupGeneral' displayName='General'>
  <DisplayState>shown</DisplayState>
  <Description>  Options affecting all ore distributions. </Description>
</OptionDisplayGroup>

```

## Option Types

### Choice Options

A Choice option is a string chosen from a set of possible values. It is represented in the in-game Options menu as a button that cycles through the values. The <OptionChoice> element defines a choice option, and has the following attributes:

<OptionChoice>
 displayState | hidden
* *hidden* options are not visible
* *shown* options are visible
 description | *nothing* | A short description of the option. Used as tool-tip text in the Options menu.

<OptionChoice> elements must contain one or more <Choice> elements, which list the possible values for the option. A Choice element has the following attributes:

<Choice>
 description | *nothing* | A short description of the value. Used as tool-tip text in the Options menu.

Example:

```
<OptionChoice name='debugMode' default='false'>
   <DisplayState>shown_dynamic</DisplayState>
   <DisplayGroup>groupGeneral</DisplayGroup>
   <DisplayName>Debugging Mode</DisplayName>
   <Choice value='true' displayValue='On'/>
   <Choice value='false' displayValue='Off'/>
</OptionChoice>

```

### Numeric Options

A numeric option is a floating-point value between some minimum and maximum. It is represented in the in-game Options menu as a slider bar. The <OptionNumeric> element defines a numeric option and has following attributes:

Example:

```
<OptionNumeric name='deferredPopulationRange' default='32'>
   <DisplayState>shown</DisplayState>
   <DisplayGroup>groupGeneral</DisplayGroup>
   <DisplayName>Deferred Chunk Gen. Range</DisplayName>
   <Min>0</Min>
   <Max>128</Max>
   <DisplayIncrement>16</DisplayIncrement>
</OptionNumeric>

```

## Special Options

Options generally have meaning only within the config file. There are three options, however, that get special treatment from CustomOreGen:

 vanillaOreGen