Wiki 9Minecraft Auto Config Updated API Mod Wiki
Auto Config Updated API Mod Wiki › Guide

Auto Config Updated API Mod — Guide

Developer Setup

To implement Auto Config Updated API in a development environment, the following Maven repositories and dependencies must be added to the 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 are the primary way to customize the appearance and behavior of the configuration GUI.

Annotation Target Description
@Config Class Defines the config file name (excluding extension).
@Config.Gui.Background Class Sets the background texture for the config screen.
@ConfigEntry.Category Field Moves the field into a specific top-level tab/category.
@ConfigEntry.BoundedDiscrete Field Renders an int/long as a slider with min/max bounds.
@ConfigEntry.Gui.Excluded Field Prevents the field from appearing in the GUI.
@ConfigEntry.Gui.Tooltip Field Adds a hoverable tooltip (defined in lang files).
@ConfigEntry.Gui.CollapsibleObject Field Places nested object fields inside a collapsible sub-menu.
@ConfigEntry.Gui.TransitiveObject Field Flattens a nested object, showing its fields at the current level.
@ConfigEntry.Gui.PrefixText Field Injects a static text label above the entry.
@Comment (Jankson) Field Adds a direct comment to the config file and a tooltip in-game.

Serialization & Storage

Auto Config supports multiple serialization libraries. Developers must choose one during the registration process.

Built-in Serializers

  1. JanksonConfigSerializer: Supports JSON5, allowing for comments within the config file.
  2. GsonConfigSerializer: Standard JSON format, highly compatible and lightweight.
  3. Toml4jConfigSerializer: Uses the TOML format, which is the standard for Forge mod configurations.

Registration Code

// Registering with Jankson (Recommended for comments)
AutoConfig.register(MyModConfig.class, JanksonConfigSerializer::new);

// Accessing the config instance
MyModConfig config = AutoConfig.getConfigHolder(MyModConfig.class).getConfig;

Advanced Features

Post-Validation

To ensure data integrity, developers can implement validatePostLoad. This method is called immediately after the config is loaded from the disk, allowing for value clamping or dependency checks.

@Override
public void validatePostLoad throws ValidationException {
 if (sliderValue < 0) sliderValue = 0;
 if (sliderValue > 100) throw new ValidationException("Value out of range!");
}

Partitioning

The PartitioningSerializer allows a single master config class to be split into multiple physical files. This is useful for large mods with distinct modules.

  • The master class must extend PartitioningSerializer.GlobalData.
  • Sub-configs must implement ConfigData and be annotated with @Config.

Integration

ModMenu (Fabric)

To make the config screen accessible via the ModMenu list, an entrypoint must be added to the fabric.mod.json and a factory class implemented.

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

Cloth Config API

Auto Config is a wrapper for Cloth Config. While Auto Config handles the data and automation, Cloth Config provides the actual rendering engine. For highly specific GUI needs, developers can bypass Auto Config and use the ConfigBuilder provided by Cloth Config directly.