Config files and settings screens
These types give a mod a JSON settings file that players can edit by hand, a settings screen that edits the same values in game, and a player guide copied next to the file. Use them for settings a player or server owner chooses; use data packs for rules that differ per world.
At a glance
Section titled “At a glance”| Type | Summary | Status | Since | Side | Thread |
|---|---|---|---|---|---|
ConfigFile |
A mod’s JSON settings file. | Experimental | 2.0.0 | both | any |
ConfigKey |
One setting of a ConfigSpec. |
Experimental | 2.0.0 | both | any |
ConfigScreens |
Registers a mod’s config screen with the loader’s mod list. | Experimental | 2.0.0 | client | setup |
ConfigSpec |
The keys of one config file, in the order the file lists them. | Experimental | 2.0.0 | both | any |
ConfigValues |
One value for every key of a ConfigSpec. |
Experimental | 2.0.0 | both | any |
PlayerGuide |
A player guide shipped inside a mod’s jar and copied to the config folder on each launch. | Experimental | 1.2.0 | both | setup |
SettingsScreen |
A settings screen: a scrolling list of labeled toggles and number fields, with Done and Cancel. | Experimental | 1.2.0 | client | render |
UnsavedChangesScreen |
Asks whether to save a SettingsScreen’s changes before leaving it. |
Experimental | 1.2.0 | client | render |
Quick start
Section titled “Quick start”In your mod’s common code:
static final ConfigSpec.Builder KEYS = ConfigSpec.builder();static final ConfigKey<Boolean> PATHS = KEYS.bool("paths.enabled", true);static final ConfigFile<ConfigValues> FILE = ConfigFile.of("mymod", "settings.json", KEYS.build(), values -> values);
// In your mod's initializer, then anywhere after it:FILE.load();boolean pathsEnabled = FILE.get().get(PATHS);ConfigFile
Section titled “ConfigFile”ConfigFile: Experimental · Since 2.0.0 · Side: both · Thread: any
ConfigKey: Experimental · Since 2.0.0 · Side: both · Thread: any
ConfigSpec: Experimental · Since 2.0.0 · Side: both · Thread: any
ConfigValues: Experimental · Since 2.0.0 · Side: both · Thread: any
ConfigFile reads a mod’s settings from a JSON file in the config folder into a view the mod
reads them through. Declare the keys in a ConfigSpec, and build the view from its
ConfigValues. The keys and the file are public because the settings screen, in the mod’s
client package, reads them:
public record Settings(boolean pathsEnabled, int checkInterval, float wearRate) { private static final ConfigSpec.Builder KEYS = ConfigSpec.builder(); public static final ConfigKey<Boolean> PATHS = KEYS.bool("paths.enabled", true); public static final ConfigKey<Integer> CHECK_INTERVAL = KEYS.intRange("paths.checkInterval", 40, 10, 400); public static final ConfigKey<Float> WEAR_RATE = KEYS.floatRange("paths.wearRate", 1.0f, 0.1f, 10.0f); static final ConfigSpec SPEC = KEYS.build(); public static final ConfigFile<Settings> FILE = ConfigFile.of("mymod", "settings.json", SPEC, Settings::from);
private static Settings from(ConfigValues values) { return new Settings(values.get(PATHS), values.get(CHECK_INTERVAL), values.get(WEAR_RATE)); }}In your mod’s initializer, ConfigFile#load reads config/mymod/settings.json; code anywhere
then reads the current view with ConfigFile#get:
Settings.FILE.load();int interval = Settings.FILE.get().checkInterval();- A warning names the file, the key, the bad value, and the default used:
Config config/mymod/settings.json: paths.checkInterval = "fast" is not a whole number from 10 to 400; using the default 40. - Missing keys added to the file are named in one INFO line:
Config config/mymod/settings.json: added missing settings with their defaults: paths.wearRate.
ConfigScreens
Section titled “ConfigScreens”Experimental · Since 2.0.0 · Side: client · Thread: setup
In your mod’s client initialization, with settingsScreen from the
SettingsScreen example:
ConfigScreens.register("mymod", parent -> settingsScreen(parent));- On Fabric, Mod Menu reads the screen the first time it looks up config screens, after every mod’s client initialization, so a registration from client initialization is never too late. Without Mod Menu, the call does nothing a player can see.
- The mod lists no Mod Menu dependency: Stope suggests Mod Menu for every mod built on it.
SettingsScreen
Section titled “SettingsScreen”Experimental · Since 1.2.0 · Side: client · Thread: render
Build the screen in client code with SettingsScreen#builder, then add rows in the order they
appear, with SettingsScreen.Builder#section for a heading. Finish with the optional
SettingsScreen.Builder#remoteNote, SettingsScreen.Builder#onSave, and
SettingsScreen.Builder#thenOnHostedServer, then SettingsScreen.Builder#build. With the
Settings record from the ConfigFile example, each row names the setting it
edits:
static Screen settingsScreen(@Nullable Screen parent) { return SettingsScreen.builder(parent, "mymod.config.", Settings.FILE) .section("paths") .toggle(Settings.PATHS) .intField(Settings.CHECK_INTERVAL) .decimalField(Settings.WEAR_RATE) .remoteNote("remote") .build();}- The lang file names the rows above
mymod.config.paths.enabled,mymod.config.paths.checkInterval, andmymod.config.paths.wearRate. - A screen for something other than a settings file uses
SettingsScreen#builderwithout a file, and rows that take a starting value and a callback. SettingsScreen#setFieldText,SettingsScreen#setToggle,SettingsScreen#hasUnsavedChanges,SettingsScreen#canSave,SettingsScreen#save, andSettingsScreen#cancelact as a player would, for automated client checks.- Escape is
SettingsScreen#keyPressedwithInputConstants.KEY_ESCAPE.
UnsavedChangesScreen
Section titled “UnsavedChangesScreen”Experimental · Since 1.2.0 · Side: client · Thread: render
The settings screen opens it when the player presses Escape with unsaved changes, including
text typed into a number field that is not valid yet. In an automated client check on the
render thread, with screen the open SettingsScreen:
screen.setToggle("paths.enabled", false);screen.keyPressed(InputConstants.KEY_ESCAPE, 0, 0);if (Minecraft.getInstance().screen instanceof UnsavedChangesScreen prompt) { prompt.keepEditing();}- Save acts as Done, and is off while a field is invalid.
- Discard acts as Cancel.
- Keep Editing returns to the settings screen with every field’s text and red marks as they were.
- Escape on this screen means Keep Editing.
- Its strings are Stope’s own translation keys,
stope.settings.unsaved.*, so a mod needs no lang entries for it.
PlayerGuide
Section titled “PlayerGuide”Experimental · Since 1.2.0 · Side: both · Thread: setup
Ship the guide in the jar, then install it during initialization. MyMod is any class in the
mod’s jar, and the name and version come from the mod’s metadata:
tasks.processResources { from("docs/RULES.md") { into("mymod") }}// Both are present while the mod's own code runs; the fallbacks only keep the first line filled.String name = PlatformInfo.modName("mymod").orElse("mymod");String version = PlatformInfo.modVersion("mymod").orElse("unknown");Path guide = ConfigFile.folder("mymod").resolve("RULES.md");PlayerGuide.install(MyMod.class, "/mymod/RULES.md", guide, name, version);See also
Section titled “See also”- Saved data and reloaders: rule files from a config folder.
- Networking: sending a server’s settings to its clients.
- Add a config file and settings screen: a guide that builds both step by step.
- Send data from server to client: a guide that sends settings step by step.