Options

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

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.

Location Description
Global Options config/ Create manually if needed.
World Options [world folder]/ Created automatically when the world is created.
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.

Location of Config File Option Files Loaded
Global Config Global Options => World Options => Dimension Options
World-specific Config World Options => Dimension Options
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

#CustomOreGen [1.4.2]v1 Config Options
#Tue Nov 06 06:02:49 EST 2012
deferredPopulationRange=32.0
debugMode=true


In-Game Options Menu

Options tab in the world creation 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>
Attribute Default Value Description
name [Required] The group name. Group names are not case sensitive. No other group or option may have the same name. It is recommended (but not required) that group names be a single word with no whitespace.
displayState hidden Whether or not the group is visible.
  • hidden groups are not visible
  • shown groups are visible
displayName group name The name to be displayed in the Options menu.
displayGroup none The parent display group in the options menu. This group will only be visible when its parent group is selected.
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>
Attribute Default Value Description
name [Required] The option name. Option names are not case sensitive. No other option or display group may have the same name. It is recommended (but not required) that option names be a single word with no whitespace.
default first value The default option value. This only applies when a world is first created; after that the option value is loaded from the world's option file.
displayState hidden Whether or not the option is visible in the Options menu.
  • hidden options are not visible
  • shown options are visible
  • shown_dymanic options are visible, and changing them will update other options that depend on the new value
displayName option name The name to be displayed in the Options menu.
displayGroup none The option display group in the options menu. This option will only be visible when its group (or an ancestor of the group in the case of nested groups) is selected.
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>
Attribute Default Value Description
value [Required] The option value. Option values are not case sensitive. It is recommended (but not required) that option values be a single word with no whitespace.
displayValue value The value text to be displayed in the in-game Options menu.
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:

<OptionNumeric>
Attribute Default Value Description
name [Required] The option name. Option names are not case sensitive. No other option or display group may have the same name. It is recommended (but not required) that option names be a single word with no whitespace.
min 0 The minimum possible value (inclusive) for the option.
max 0 The maximum possible value (inclusive) for the option.
default 0 The default option value. This only applies when a world is first created; after that the option value is loaded from the world's option file.
displayState hidden Whether or not the option is visible in the Options menu.
  • hidden options are not visible
  • shown options are visible
  • shown_dymanic options are visible, and changing them will update other options that depend on the new value
displayName option name The name to be displayed in the Options menu.
displayGroup none The option display group in the options menu. This option will only be visible when its group (or an ancestor of the group in the case of nested groups) is selected.
description nothing A short description of the option. Used as tool-tip text in the Options menu.
displayMin min In the Options menu the "true" value in the range [min-max] is shown as a "display" value in the range [displayMin-displayMax].
displayMax max In the Options menu the "true" value in the range [min-max] is shown as a "display" value in the range [displayMin-displayMax].
displayIncrement (displayMax-displayMin)
/100
The size of one slider increment in the Options menu. The option value will be rounded such that the "display" value is some even multiple of this increment.


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:

Option Name Special Meaning
debugMode Enables/disables debugging mode
deferredPopulationRange Controls how much nearby terrain must be generated before COG will add or remove blocks from a chunk.
vanillaOreGen Enables/disables vanilla minecraft ore generation.