Cloth Config API — Configuration

Manual Configuration (ConfigBuilder)

The ConfigBuilder is the manual way to construct a configuration screen. It offers maximum control over the layout and behavior of the GUI.

1. Creation: Call ConfigBuilder.create to initialize a new builder. You must set a parent screen (the screen shown when the user exits the config) and a title.
2. Categories: Use getOrCreateCategory to group related options. If only one category exists, the category tab will be hidden to save space.
3. Entries: Use the ConfigEntryBuilder to create specific options like text fields, toggles, or sliders.
4. Saving: Define a SavingRunnable that executes when the user clicks the "Save" button to write the values to your config file.

ConfigBuilder builder = ConfigBuilder.create
.setParentScreen(parent)
.setTitle(new TranslatableText("title.examplemod.config"));

ConfigCategory general = builder.getOrCreateCategory(new TranslatableText("category.examplemod.general"));
ConfigEntryBuilder entryBuilder = builder.entryBuilder;

general.addEntry(entryBuilder.startStrField(new TranslatableText("option.examplemod.name"), currentValue)
.setDefaultValue("Default")
.setSaveConsumer(newValue -> currentValue = newValue)
.build);

Screen screen = builder.build;
MinecraftClient.getInstance.setScreen(screen);

Auto Config (Annotation-Based)

Auto Config is a high-level wrapper included with Cloth Config that generates the entire GUI automatically based on a Java class annotated with specific tags. This is the recommended method for most mods.

Creating the Config Class

Your config class must implement ConfigData. Fields in this class represent the options that will appear in the GUI.

@Config(name = "modid")
class ModConfig implements ConfigData {
 boolean enableFeature = true;
 int range = 10;

 @ConfigEntry.Gui.CollapsibleObject
 AdvancedSettings advanced = new AdvancedSettings;

 static class AdvancedSettings {
 float multiplier = 1.5f;
 }
}

Registering and Reading

Register the config during your mod's initialization. You can choose between Jankson (JSON5), GSON (JSON), or TOML serializers.

// Registration
AutoConfig.register(ModConfig.class, GsonConfigSerializer::new);

// Reading values
ModConfig config = AutoConfig.getConfigHolder(ModConfig.class).getConfig;