Validation types

Wrap a field to bound it, restrict it, or give it a better widget.

Validation is what stops a hand-edited file from crashing the game. Every read, write and update is checked; a bad value is corrected rather than thrown on. Fields you do not wrap still get implicit type validation, so a string where an int belongs is caught.

Wrapping a field does three things: it bounds what the value can be, it picks the widget the player sees, and it makes the setting usable inside other validation such as collections and pairs.

The catalogue

Type	Wraps	Notes
`ValidatedBoolean`	Boolean	Mostly useful as an input to other validation, or as a condition.
`ValidatedInt`, `ValidatedLong`, `ValidatedShort`, `ValidatedByte`, `ValidatedFloat`, `ValidatedDouble`	Numbers	Six subclasses of `ValidatedNumber`. Each keeps its own type and takes a min and max, defaulting to the type's full range.
`ValidatedEnum`	Any enum	Enums in a config are validated automatically; the explicit type is for building other validation.
`ValidatedChoice`	A set with one active choice	Lists and sets convert with `toChoices()`.
`ValidatedChoiceList`	A set of toggles	Feature-flag style. Poll it with `List#contains`. Added in 0.6.0.
`ValidatedList`, `ValidatedSet`, `ValidatedMap`	Collections	Implement their own collection type, so you can use them directly without `.get()`.
`ValidatedColor`	ARGB colour	Gives the player a colour picker. Supplies components, an int, or a hex string.
`ValidatedIdentifier`	Identifier	Restrict by registry, tag or explicit list, with suggestions as the player types.
`ValidatedTagKey`	TagKey	Any registry's tags, with in-GUI suggestions.
`ValidatedRegistryType`	A registered object	Hands you the object rather than an identifier you have to look up.
`ValidatedIngredient`	Ingredient	From a single item, a list, or a tag. Builds the real Ingredient lazily.
`ValidatedKeybind`	A key combination	A keybind framework built on context handling. Added in 0.6.5.
`ValidatedExpression`	A math expression	Backed by the built-in math engine, with character variables.
`ValidatedAny`	An arbitrary object	Builds a mini-config around a POJO. Objects implementing `Walkable` are wrapped automatically.
`ValidatedPair`	Two settings as one	Shows both widgets side by side. Stored as a `ValidatedPair.Tuple`. Added in 0.6.0.
`ValidatedTriState`	TRUE / FALSE / DEFAULT	Added in 0.6.5.
`ValidatedCondition`	Another setting	Gates a value behind conditions checked on `get()`.

Numbers

A validated number takes a default, a maximum and a minimum, in that order. It also chooses the widget the player gets.

// default 5.0, allowed 0.0 to 10.0, slider widget
var speed = ValidatedDouble(5.0, 10.0, 0.0)

// a text box with up and down buttons instead of a slider
var count = ValidatedInt(6, 10, 1, ValidatedNumber.WidgetType.TEXTBOX_WITH_BUTTONS)

The argument order is default, max, min. Reading it as a range and passing (min, max) is an easy mistake to make.

Collections

Any ValidatedField can be converted into a collection of itself, so the element validation is reused for every entry. The result implements the real collection interface.

// a list of ints, each bounded 0 to 100
var levels = ValidatedInt(2, 100, 0).toList(1, 5, 10)

// a map whose keys come from a tag and whose values are bounded
var weights = ValidatedIdentifierMap(
    mapOf(),
    ValidatedIdentifier.ofTag(ItemTags.AXES),
    ValidatedDouble(1.0, 1.0, 0.0)
)

Identifiers and tags

ValidatedIdentifier is the type players notice most, because it suggests and tab-completes. Build it from a registry, a tag, or a fixed list.

// anything in the item registry
var item = ValidatedIdentifier.ofRegistry(Registries.ITEM)

// only things in a tag
var axe = ValidatedIdentifier.ofTag(ItemTags.AXES)

// an explicit shortlist
var fuel = ValidatedIdentifier.ofList(
    Identifier.parse("coal"),
    listOf(Identifier.parse("coal"), Identifier.parse("charcoal"))
)

Objects and pairs

ValidatedAny wraps a plain object and validates everything inside it as if it were its own small config, annotations included. ValidatedPair joins two settings into one unit, which suits a min and max range, or a toggle paired with the thing it toggles.

// two bounded ints presented as one labelled range
var range = ValidatedInt(1, 10, 0)
    .pairWith(ValidatedInt(1, 10, 0))
    .withLabels("Min".lit(), "Max".lit())

Need more depth on this topic? The wiki has a longer article. Read it on moddedmc.wiki.