Skip to content

Add a config file and settings screen

This guide gives a mod a settings file in the config folder that players can edit by hand, a settings screen that edits the same file in game, and a command that reloads the file without a restart.

Add Settings, the record from the ConfigFile example, to your mod’s common code. It declares the keys paths.enabled, paths.checkInterval, and paths.wearRate, each with its default and range, in config/mymod/settings.json, and the record the mod reads them through. Its keys and Settings.FILE are public, because the settings screen reads them from the mod’s client package.

Load the file once in your mod’s initializer, as the ConfigFile section shows; code anywhere after that reads the current values from Settings.FILE. What a load does with a missing file, a missing key, or a bad value is in ConfigFile#load’s Javadoc, and the messages it logs are on that section.

In your mod’s client code, add settingsScreen, the method from the SettingsScreen example. It builds a screen with one row per setting; the rows edit a working copy of the values, and Done saves the copy to the file.

The screen’s title, heading, rows, tooltips, and remote note are translation keys under the mymod.config. prefix; SettingsScreen’s Javadoc names each one. The reload command below answers with commands.mymod.reload. Add them all to the mod’s lang file, assets/mymod/lang/en_us.json:

Name the settings screen's rows and the reload message
{
"mymod.config.title": "My Mod Settings",
"mymod.config.paths": "Paths",
"mymod.config.paths.enabled": "Wear paths",
"mymod.config.paths.enabled.tooltip": "Grass that players cross often turns into a dirt path.",
"mymod.config.paths.checkInterval": "Check interval",
"mymod.config.paths.checkInterval.tooltip": "Ticks between wear checks, from 10 to 400.",
"mymod.config.paths.wearRate": "Wear rate",
"mymod.config.paths.wearRate.tooltip": "How fast paths wear, from 0.1 to 10.",
"mymod.config.remote": "These settings apply only to worlds you host.",
"commands.mymod.reload": "Reloaded My Mod's settings."
}

In your mod’s client initialization, register the screen with the loader’s mod list, as the ConfigScreens example does with settingsScreen.

A server owner who edits the file by hand can load it again with a command. In your mod’s common initializer, register the /mymod reload command from the CommandRegistrationCallback example. It needs permission level 2, loads Settings.FILE again, and answers with the commands.mymod.reload message.

To tell connected clients about the new values, send them, as Send data from server to client does.