Skip to content

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.

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

In your mod’s common code:

Add a settings file with one setting
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: 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:

Declare a settings file and the record that reads it
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:

Load the settings and read one
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.

Experimental · Since 2.0.0 · Side: client · Thread: setup

In your mod’s client initialization, with settingsScreen from the SettingsScreen example:

Register a mod's settings screen
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.

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:

Build a settings screen that saves the settings file
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, and mymod.config.paths.wearRate.
  • A screen for something other than a settings file uses SettingsScreen#builder without a file, and rows that take a starting value and a callback.
  • SettingsScreen#setFieldText, SettingsScreen#setToggle, SettingsScreen#hasUnsavedChanges, SettingsScreen#canSave, SettingsScreen#save, and SettingsScreen#cancel act as a player would, for automated client checks.
  • Escape is SettingsScreen#keyPressed with InputConstants.KEY_ESCAPE.

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:

Press Escape with a change, then keep editing
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.

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:

build.gradle.kts
tasks.processResources {
from("docs/RULES.md") {
into("mymod")
}
}
Install a player guide in the config folder
// 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);