Config Value Common APIs

All SSCL config values extend ConfigValue.

Because of that, every value shares the same basic API.

The available value types are:

• BooleanValue
• IntValue
• DoubleValue
• StringValue
• EnumValue
• ListValue

get()

Returns the current value.

boolean enabled = ENABLED.get();
int distance = DISTANCE.get();
double scale = SCALE.get();
String name = NAME.get();
List<String> names = NAMES.get();

SSCL loads the config automatically when the value is first accessed.

For ListValue, the returned list should be treated as read-only. Use set() to replace the list.

set()

Changes the current value.

ENABLED.set(false);
DISTANCE.set(16);
SCALE.set(1.5);
NAME.set("Alex");
NAMES.set(List.of("Steve", "Alex"));

The value is validated before it is changed.

For numeric values, configured limits are checked.

For lists, every element must match the list's declared element type.

getDefault()

Returns the default value defined when the value was created.

boolean enabled = ENABLED.getDefault();
int distance = DISTANCE.getDefault();
List<String> names = NAMES.getDefault();

Changing the current value does not change its default.

resetToDefault()

Resets the current value back to its default.

DISTANCE.resetToDefault();
NAMES.resetToDefault();

comment()

Adds a comment to the generated TOML file.

DISTANCE.comment("Maximum working distance.");

The comment is written above the value:

# Maximum working distance.
distance = 8

tooltip()

Adds a tooltip to the value's Mod Menu control.

DISTANCE.tooltip("Controls how far the mod can reach.");

Tooltips are shown when hovering over the value in the SSCL config screen.

onChange()

Registers a listener that is called when the value actually changes.

CONFIG_VALUE.onChange((oldValue, newValue) -> {
	// Handle the change
});

The listener receives both the previous value and the new value.

For example:

ExampleModConfig.ENABLED.onChange((oldValue, newValue) -> {
	ExampleMod.LOGGER.info(
			"Enabled changed: {} -> {}",
			oldValue,
			newValue
	);
});

The listener is only called when the value changes. Setting the same value again does not trigger it.

ExampleModConfig.ENABLED.set(true);

If the value is already true, this does not trigger the listener.

onChange() also works with ListValue.

ExampleModConfig.NAMES.onChange((oldValue, newValue) -> {
	// React to the list changing
});

For list values, the old and new lists are provided as independent read-only values.

Important Behavior

The change listeners:

• run when set() changes the value
• also run when resetToDefault() changes the value
• do not run when the value is initially loaded from TOML
• do not watch for changes made directly to the TOML file
• do not perform any networking automatically

SSCL only reports the change. The mod decides what to do with it.

For example, a mod can use the listener to refresh its own state:

ExampleModConfig.ENABLED.onChange((oldValue, newValue) -> {
	refreshFeatureState(newValue);
});

Numeric APIs

IntValue and DoubleValue provide additional numeric APIs.

min()

Sets the minimum allowed value.

DISTANCE.min(1);

max()

Sets the maximum allowed value.

DISTANCE.max(32);

hasRange()

Returns true when both an explicit minimum and maximum have been configured.

if (DISTANCE.hasRange()) {
	// ...
}

A value with both bounds is displayed as a slider in Mod Menu.

A value with only one bound, or no bounds, uses an edit box instead.

decimals()

DoubleValue supports configurable decimal precision.

SCALE.decimals(2);

The value must be between 1 and 3.

The setting controls how the value is displayed and how precisely its Mod Menu slider moves.

It does not change the actual stored precision of the double.

Range Comments

Numeric values automatically add a range comment to the TOML file when a minimum or maximum is configured.

For example:

DISTANCE
	.min(1)
	.max(32)

produces:

# Range: 1 - 32
distance = 8

A minimum without a maximum produces:

# Minimum: 1
distance = 8

A maximum without a minimum produces:

# Maximum: 32
distance = 8

rangeComment()

Automatic range comments can be disabled for an individual numeric value.

DISTANCE.rangeComment(false);

The numeric validation and slider behavior are unchanged.

ListValue

ListValue uses the same common API.

For example:

ListValue<String> NAMES = GENERAL
		.stringList("names", List.of("Steve", "Alex"))
		.comment("Names used by the mod.")
		.tooltip("Names available to the feature.");

The list can then be read or replaced with:

List<String> names = NAMES.get();

NAMES.set(List.of("Steve", "Alex", "Herobrine"));

ListValue also provides:

NAMES.getDefault();
NAMES.resetToDefault();
NAMES.elementType();

List values do not support numeric range APIs such as min(), max(), decimals(), or rangeComment().

Fluent API

SSCL methods return the value they belong to where appropriate, so configuration definitions can be chained.

public static final IntValue DISTANCE = GENERAL
		.intValue("distance", 8)
		.min(1)
		.max(32)
		.comment("Maximum working distance.")
		.tooltip("Controls how far the mod can reach.");

The same style works for list values:

public static final ListValue<String> NAMES = GENERAL
		.stringList("names", List.of("Steve", "Alex"))
		.comment("Names used by the mod.")
		.tooltip("Names available to the feature.");

A change listener can also be added as part of the fluent API:

public static final BooleanValue ENABLED = GENERAL
		.bool("enabled", true)
		.comment("Whether the mod is enabled.")
		.tooltip("Turns the mod on or off.")
		.onChange((oldValue, newValue) -> {
			LOGGER.info(
					"Enabled changed: {} -> {}",
					oldValue,
					newValue
			);
		});

The listener receives the old and new values whenever the setting actually changes.