Cloth Config API Wiki

Cloth Config API is a technical mod and developer library that serves as a dependency for hundreds of other Minecraft mods. Its primary purpose is to provide a unified, aesthetically pleasing configuration screen that allows players to modify mod settings directly from within the game's main menu or the ModMenu interface, rather than manually editing .json, .toml, or .conf files in a text editor.

While Cloth Config is primarily client-sided (as it handles the Graphical User Interface), it includes robust backend systems for data serialization and synchronization. It is widely considered the industry standard for configuration screens due to its support for complex data types, smooth scrolling, and deep integration with the Fabric and Forge ecosystems.

Cloth Config has evolved through multiple major versions to support different Minecraft releases. For Minecraft, the mod typically utilizes version 11 (Stable).

To use Cloth Config API in a development environment, developers must add the appropriate repositories and dependencies to their build.gradle file.

Fabric Setup

repositories {
 maven { url "https://maven.shedaniel.me/" }
 maven { url "https://maven.terraformersmc.com/releases/" }
}

dependencies {
 modApi("me.shedaniel.cloth:cloth-config-fabric:VERSION") {
 exclude(group: "net.fabricmc.fabric-api")
 }
}

Forge Setup

repositories {
 maven { url "https://maven.shedaniel.me/" }
}

dependencies {
 api(fg.deobf("me.shedaniel.cloth:cloth-config-forge:VERSION"))
}

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 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;

Annotations allow developers to customize how fields are rendered in the Auto Config GUI.

Cloth Config supports a wide variety of interactive elements to handle different data types:

• Boolean Toggle: A simple button that cycles between True and False.
• String Field: A text input box for strings.
• Numeric Fields: Specialized inputs for int, long, float, and double with optional validation.
• Sliders: Used for bounded numbers, allowing users to drag a handle to select a value.
• Enum Selector: A button that cycles through all available values of a Java Enum.
• Color Picker: A visual interface for selecting RGB or ARGB colors, including a preview box.
• Keybinding: Allows players to click and press a key to assign a shortcut.
• Lists: Dynamic lists where users can add, remove, or reorder multiple entries of a specific type (e.g., a list of player names or coordinates).
• Dropdown Menus: A searchable selection menu for large sets of options.

Cloth Config handles the complex task of saving and loading data from the disk. It supports three primary formats:

1. Jankson (JSON5): The default and most flexible format. It supports comments and is more forgiving with syntax than standard JSON.
2. GSON (JSON): Standard JSON format, highly compatible but does not support comments.
3. TOML: A popular configuration format used by Forge, known for its readability.

Partitioning

For large mods, the PartitioningSerializer allows developers to split a single config class into multiple physical files on the disk, organized within a sub-directory. This is useful for modular mods where different features have distinct configuration needs.

On the Fabric platform, Cloth Config is designed to work seamlessly with ModMenu. By implementing the ModMenuApi entry point, developers can ensure that their Cloth Config screen opens when a player clicks the "Configure" button in the ModMenu list.

public class ModMenuIntegration implements ModMenuApi {
 @Override
 public ConfigScreenFactory<?> getModConfigScreenFactory {
 return parent -> AutoConfig.getConfigScreen(ModConfig.class, parent).get;
 }
}

Post-Validation

Developers can implement validatePostLoad within their config class. This method runs immediately after the config is loaded from the disk, allowing the mod to "fix" invalid values (e.g., clamping a number that is out of range) before the game uses them.

Custom GUI Handlers

For highly specialized needs, developers can register GuiProvider and GuiTransformer objects.

• GuiProvider: Maps a specific field type or annotation to a custom GUI component.
• GuiTransformer: Modifies an existing GUI component after it has been generated, such as changing its color or adding extra logic.