Example Project

This is a small example project showing how to use SSCL in your mod classes.

It covers a basic config, list values, reading values, changing values, reacting to changes, and using multiple config files.

ExampleMod.java

package com.example.mymod;

import net.fabricmc.api.ModInitializer;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class ExampleMod implements ModInitializer {
	public static final String MOD_ID = "mymod";
	public static final Logger LOGGER =
			LoggerFactory.getLogger(MOD_ID);

	@Override
	public void onInitialize() {
		ExampleModConfig.initialize();

		LOGGER.info("MyMod initialized.");
	}
}

ExampleModConfig.java

package com.example.mymod;

import smilenotalive.sscl.SSCL;
import smilenotalive.sscl.config.BooleanValue;
import smilenotalive.sscl.config.Config;
import smilenotalive.sscl.config.ConfigCategory;
import smilenotalive.sscl.config.ConfigSide;
import smilenotalive.sscl.config.DoubleValue;
import smilenotalive.sscl.config.IntValue;
import smilenotalive.sscl.config.ListValue;

import java.util.List;

public final class ExampleModConfig {
	public static final Config CONFIG = SSCL.create(
			ExampleMod.MOD_ID,
			"MyMod/config.toml",
			ConfigSide.COMMON
	);

	public static final ConfigCategory GENERAL = CONFIG
			.category("general")
			.comment("General mod settings.");

	public static final BooleanValue ENABLED = GENERAL
			.bool("enabled", true)
			.comment("Whether the mod is enabled.")
			.tooltip("Turns the mod on or off.");

	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.");

	public static final DoubleValue SCALE = GENERAL
			.doubleValue("scale", 1.0)
			.min(0.5)
			.max(2.0)
			.decimals(2)
			.comment("Interface scale.")
			.tooltip("Controls the size of the interface.");

	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.");

	public static void initialize() {
	}

	private ExampleModConfig() {
	}
}

Using the Values

The values can be accessed anywhere in the mod:

if (ExampleModConfig.ENABLED.get()) {
	int distance = ExampleModConfig.DISTANCE.get();
	double scale = ExampleModConfig.SCALE.get();
	List<String> names = ExampleModConfig.NAMES.get();
}

Changing Values

Values can be changed at runtime:

ExampleModConfig.ENABLED.set(false);
ExampleModConfig.DISTANCE.set(16);
ExampleModConfig.SCALE.set(1.25);

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

Changes are held in memory until the config is saved.

ExampleModConfig.CONFIG.save();

Reacting to Changes

A mod can register a listener to react when a config value actually changes.

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

The listener receives both the old and new values.

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, the listener is not called.

Change listeners also work with list values:

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

SSCL only reports the change. It does not perform networking or synchronization automatically. The mod decides what to do when a value changes.

Multiple Configs

A mod can use multiple independent config files.

For example:

public static final Config CLIENT_CONFIG = SSCL.create(
		ExampleMod.MOD_ID,
		"MyMod/client.toml",
		ConfigSide.CLIENT
);

public static final Config SERVER_CONFIG = SSCL.create(
		ExampleMod.MOD_ID,
		"MyMod/server.toml",
		ConfigSide.SERVER
);

This creates:

config/
└── MyMod/
	├── client.toml
	└── server.toml

Each config can have its own categories and values.

When a mod has multiple configs, SSCL displays them as separate tabs in Mod Menu:

Client | Server

A mod with only one config does not display the tab bar.

Resulting TOML

The basic example produces:

[general]

# General mod settings.

# Whether the mod is enabled.
enabled = true

# Maximum working distance.
# Range: 1 - 32
distance = 8

# Interface scale.
# Range: 0.5 - 2.0
scale = 1.0

# Names used by the mod.
names = ["Steve", "Alex"]

The file is located at:

config/MyMod/config.toml