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.
Declare the settings
Section titled “Declare the settings”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
Section titled “Load the file”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.
Build the settings screen
Section titled “Build the settings screen”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.
Name the rows
Section titled “Name the rows”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:
{ "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."}Register the screen
Section titled “Register the screen”In your mod’s client initialization, register the screen with the loader’s mod list, as the
ConfigScreens example
does with settingsScreen.
Reload the file without a restart
Section titled “Reload the file without a restart”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.
See also
Section titled “See also”- Config files and settings screens: the settings file, the screen, its unsaved-changes prompt, and player guides.
- Lifecycle events: the command registration event.
- Worldgen and loot: switches that read a setting.