Cloth Config API — Guide

Version Support

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

Developer Setup

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 " }
 maven { url " }
}

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

Forge Setup

repositories {
 maven { url " }
}

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

Annotations Reference

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

GUI Entry Types

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.

Serialization & Storage

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.

ModMenu Integration

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

Mechanics & Advanced Customization

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.