Auto Config Updated API Mod Wiki

Auto Config Updated API is a developer-centric library mod designed to streamline the process of creating configuration files and their corresponding in-game menus. Originally a fork of the Auto Config API by sargunv, this "Updated" version is maintained by shedaniel to ensure compatibility with modern Minecraft versions (1.19.2, 1.20.1, and beyond).

Unlike standard mods that add gameplay content, Auto Config Updated API serves as a backend framework. It allows modders to define a simple Java class representing their configuration data and use annotations to automatically generate a professional, user-friendly GUI. It is a mandatory dependency for many popular mods, particularly those within the Shedaniel ecosystem, such as Roughly Enough Items (REI) and Cloth Config.

The mod operates on a "Data-First" philosophy. Instead of manually coding every button and slider in a GUI, developers define the variables they need (booleans, integers, strings, etc.) and the API handles the rest.

Key Features

• Annotation-Driven: Use simple tags like @Config and @ConfigEntry to define behavior.
• Automatic GUI Generation: Seamlessly creates Cloth Config screens without manual layout code.
• Multi-Format Support: Supports Jankson (JSON5), GSON (JSON), and TOML for configuration storage.
• Validation System: Includes hooks to correct or validate user input after the config is loaded.
• Partitioning: Ability to split large configuration files into multiple smaller files automatically.

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 "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"))
}

A configuration class must implement ConfigData and be annotated with @Config. This class acts as the blueprint for both the file on disk and the in-game menu.

Basic Implementation Example

@Config(name = "example_mod")
class MyModConfig implements ConfigData {
 boolean enableFeatureA = true;
 int sliderValue = 50;

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

 static class AdvancedSettings {
 String customName = "Default";
 float multiplier = 1.5f;
 }
}

Supported Data Types

By default, the GUI generator supports the following types:

• Primitives: boolean, int, long, double, float.
• Objects: String, Enum.
• Nested Objects: Using the @CollapsibleObject or @TransitiveObject annotations.

Annotations are the primary way to customize the appearance and behavior of the configuration GUI.

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;

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.

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.

Q: Is this mod required on servers? A: No. Cloth Config and Auto Config are client-side only. They handle GUI screens which do not exist on dedicated servers. However, some mods may use the API to sync server-side settings to the client.

Q: Why does my config not save? A: Ensure you have called the .save method on the ConfigHolder or that you have correctly set a SavingRunnable in your manual builder.

Q: Can I use this for Forge mods? A: Yes, Auto Config Updated API is compatible with both Fabric and Forge/NeoForge, provided the correct version of Cloth Config is installed.