Entry Types

Simple Config provides a wide range of entry types, but most importantly, allows you to combine them with composite entry types, like lists/maps/beans/data-classes. These composite entries will be presented in the Advanced Entry Types section.

It is also possible to create Custom Entry Types, ranging from basic serializable types to full-fledged entry types where you can design your own UI, albeit those require you to compile against the mod rather than the API, and you could propose them as a pull request instead.

Basic Entry Types

• Boolean
• String
• Enum Options
• Arbitrary Options
• Numeric Entries
• Range
• Color
• Serializable Types
  • NBT Entries
  • Pattern (Java RegExp)
  • Resource Location
  • Item/Block/Fluid
  • Key Bindings
• GUI entries
  • Text entries
  • Button entries

Boolean

Boolean entries are the most basic type of option. They can have two values, true and false. There are 3 ways to create a simple boolean entry:

• bool(defaultValue) which displays as true/false
• yesNo(defaultValue) which displays instead as Yes/No
• onOff(defaultValue) which displays instead as On/Off
• enable(defaultValue) which displays instead as Enable/Disable

The only difference between these factory methods is the displayed text in menus/commands. In fact, you can use your own text if you want, by calling bool(...).text(...) which accepts either a translation key, to which ".true" and ".false" will be appended, or a custom BooleanDisplayer object.

String

String entries accept arbitrary text.

• string(defaultValue)

It's possible to restrict the length of the text with minLength and maxLength.

String entries can also provide suggestions by using suggest, or be restricted to the suggestions by using restrict. This produces a combo box widget in the menu.

Enum Options

Enum entries are like boolean entries, but instead of just two options they may have an arbitrary amount of possible values. To define an enum entry, you can use

• option(defaultValue) where the defaultValue must be an enum value.

It's a common pattern creating enum classes specifically for certain config options. This is done even by Minecraft itself (look for the GraphicsStatus or CloudStatus classes for instance).

By default, enum values display with their name. To change this, you may either implement the TranslatedEnum interface in your enum class, or use the automatically mapped translation keys for your enum class, which are

• <modid>.config.enum.<enum_class_name>.<enum_value_name> for the enum value names.
• <modid>.config.enum.<enum_class_name>.<enum_value_name>:help for the tooltip of each value (optional, may include \n newlines)

It is recommended you use the automatically mapped translation keys instead of implementing the TranslatedEnum for simplicity.

Dragging MClick or Alt + LClick will let players easily glance and pick an option.

Entries with too many options (depending on a player setting) will be rendered as combo boxes instead.

Arbitrary Options

The option factory method also accepts arbitrary non-enum types, as long as you provide a list of allowed values. In general, you should create custom enum classes for your options where possible. The only encouraged use of arbitrary option entries is when you need to provide a dynamic list of allowed values (passing a list supplier rather than a list), and this is discouraged as well (as it can become very annoying for players, unless the dynamic nature of the allowed values is justified).

• option(defaultValue, options)

You'll need to provide a way to serialize config values to strings using either withSerializer or withCodec.

Numeric Entries

There are numeric options for all primitive number types in Simple Config. To create them use one of the many overloads of the number factory method:

• number(defaultValue) which creates an unbound numeric entry of the same number type as the defaultValue
• number(defaultValue, max) which creates a bound numeric entry between 0 and max, of the same type as the arguments
• number(defaultValue, min, max) which creates a bound numeric value between min and max, of the same type as the arguments

The range of numeric entries can be modified with the min, max and range methods. You can also display them as sliders in the menu by using the slider method, which can also accept a translation key to display as label of the slider, formatted with the value.

It's possible to have a smaller range for the slider control than the actual range of the entry, as players can decide to manually input values by text in slider entries. This can be used to suggest a recommended range via the sliderRange method, while still allowing advanced players to go beyond those limits. Sliders can also have a non-linear value mapping (using sliderMap), which can be useful for sensitivity/scale/volume settings.

Alternative Numeric Entry Factories

Besides the number factory methods, there are a few other built-in factory methods that provide some common numeric entry types, namely:

• percent(defaultValue) which is bound between 0 and 100
• fraction(defaultValue) which is a slider bound between 0 and 1 (only for float/double types)
• volume(defaultValue) which is like a fraction but displays a custom volume label in the slider, formatted as a percentage

Range

Simple Config provides its own range classes (IntRange, FloatRange, ...), which express the exclusivity of their bounds. In general, you could instead uses a pair entry, which is far more flexible (see Advanced Entry Types).

• range(defaultValue)
• range(min, max)

It's preferred you use ranges instead of having two separate entries (for min and max), as using two separate entries forces a validity dependency between entries (min shouldn't be greater than max), which in general you should avoid.

Color

Uses the java.awt.Color class. Provides a color picker in the menu:

• color(defaultValue)

The alpha method may be used to allow semitransparent colors.

Clicking the color preview in the entry widget will open a color picker.

Serializable Entry Types

There are many entry types that are defined on the basis that they can be easily de/serialized from/into text. Players edit their text representation either in text fields or combo boxes. Depending on the type, some entries may even provide syntax highlighting/basic writing assistance.

In addition to the entries described below, you can make your own serializing adapter for any given type to be displayed in its own entry type (see Custom Entry Types).

NBT Entries

There are two types of NBT entries in the Simple Config API:

• tag(defaultValue) which accepts any Tag value
• compoundTag(defaultValue) which only accepts CompoundTag values

Pattern (Java RegExp)

Create a pattern entry with the pattern factory methods. You may specify RegExp flags that will be used to compile player input.

• pattern(defaultValue) where defaultValue can be either a string or a Pattern object, whose flags will be used
• pattern(defaultValue, flags)

Resource Location

There is a generic resource location entry type, as well as 3 specific for item/block/fluid names, which provide autocompletion for known IDs:

• resource(defaultValue) for a generic resource location entry
• itemName(defaultValue) for item names, not necessarily existing, but provides autocompletion
• blockName(defaultValue) for block names, likewise
• fluidBlock(defaultValue) for fluid names, likewise

If you want to instead require selected items/blocks/fluids to exist, you should use the item/block/fluid entry types instead.

Item/Block/Fluid

Similar to the itemName/blockName/fluidName entries above, but restricted to existing values, and using their actual type, i.e., Item/Block/Fluid, rather than their IDs:

• item(defaultValue)
• block(defaultValue)
• fluid(defaultValue)

These entries can be restricted to some groups of values. Only in server configs, these restrictions may be done using item/block/fluid tags, as tags are world-dependant.

Key Bindings

Simple Config has its own Key Bind system, inspired on MaLiLib's one. For more information on how to make these key bindings functional, read the documentation of ExtendedKeyBindProvider and ExtendedKeyBind.

• key(defaultValue)

Clicking the settings icon besides the hotkey will open the extended keybind settings popup.

This system is still a work in progress. You may be interested in using Forge keybinds instead. The main use for key entries is when you compose them with other entries, for instance, a map entry from keys to other entries (see Advanced Entry Types).

GUI Entries

Simple Config defines a few entry types which don't actually generate an entry in the config file. They merely create widgets in the config menu.

Text entries

Text entries display a text in the config menu. You can use this to explain something that wouldn't fit in a help tooltip, or for introduction messages. They do not have a factory method, as they are created by using the text method of the config/category/group builder.

Button entries

A button entry displays a button in the menu, which can run an arbitrary action.

• button(runnable) which creates a simple button
• button(entry, consumer) which creates a button with an arbitrary entry as argument

The button may have an adjacent entry it'll use as argument for its action.

You may use these kind of entries to perform edit actions on the menu, by using the setForGUI methods of SimpleConfig objects, if you're so dedicated.

---

Continue Reading

• Advanced Entry Types
• Custom Entry Types