Cloth Config

https://shedaniel.gitbook.io/cloth-config
Admin
Cloth Config is a library for creating configuration screens for Minecraft mods, supporting both...
Tokens:3,489
Snippets:62
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Query documentation via HTTP GET

Source: https://shedaniel.gitbook.io/cloth-config/llms.txt

Perform an HTTP GET request to the documentation index to retrieve answers based on a specific question and optional end goal.

```http
GET https://shedaniel.gitbook.io/cloth-config/master.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Initialize a ConfigBuilder

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/creating-a-config-screen.md

Create a new configuration screen instance by setting the parent screen and a translatable title.

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

--------------------------------

### Initialize ConfigGuiRegistry

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/custom-gui-handlers.md

Retrieve the registry instance for a specific configuration. This must be executed on the client side.

```java
ConfigGuiRegistry registry = AutoConfig.getGuiRegistry(CONFIG_NAME);
```

--------------------------------

### Initialize ConfigEntryBuilder

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/creating-a-config-option.md

Create a new instance of ConfigEntryBuilder from the main builder.

```java
[...]
ConfigEntryBuilder entryBuilder = builder.entryBuilder();
```

--------------------------------

### Display the configuration screen

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/building-the-config-screen.md

Opens the built screen for the player using the Minecraft client instance.

```java
[...]
MinecraftClient.getInstance().openScreen(screen);
```

--------------------------------

### Implement ModMenuApi Entrypoint

Source: https://shedaniel.gitbook.io/cloth-config/advanced/modmenu-integration.md

Define a class that implements ModMenuApi to provide the configuration screen factory.

```java
public class ExampleModMenuIntegration implements ModMenuApi {
}
```

```java
public class ExampleModMenuIntegration implements ModMenuApi {
    [...]
    @Override
    public ConfigScreenFactory<?> getModConfigScreenFactory() {
        return parent -> {
            // Return the screen here with the one you created from Cloth Config Builder
        };
    }
}
```

--------------------------------

### Build the configuration screen

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/building-the-config-screen.md

Finalizes the configuration screen construction using the builder instance.

```java
[...]
Screen screen = builder.build();
```

--------------------------------

### Implement ModMenuApi for Config Screen

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/generating-a-cloth-config-screen.md

Register this entrypoint in your fabric.mod.json to enable the configuration screen in ModMenu.

```java
@Environment(EnvType.CLIENT)
class ModMenuIntegration implements ModMenuApi {

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

--------------------------------

### Register GuiProvider

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/custom-gui-handlers.md

Register providers to map fields to GUI entries based on annotations, predicates, or types. Custom providers take precedence over built-in ones.

```java
registry.registerAnnotationProvider(...); // apply based on the presence of an annotation
registry.registerPredicateProvider(...); // apply based on a certain Predicate<Field>
registry.registerTypeProvider(...); // apply to a certain type
```

--------------------------------

### Retrieve the configuration instance

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/reading-the-config.md

Call this method after registration to access the configuration object.

```java
ModConfig config = AutoConfig.getConfigHolder(ModConfig.class).getConfig();
```

--------------------------------

### Register Entrypoint in fabric.mod.json

Source: https://shedaniel.gitbook.io/cloth-config/advanced/modmenu-integration.md

Add the fully qualified path of your ModMenu integration class to the modmenu entrypoints section in fabric.mod.json.

```json
"entrypoints": {
    "modmenu": [
        "full.path.to.ExampleModMenuIntegration"
    ]
}
```

--------------------------------

### Registering a Config Serializer

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/registering-the-config.md

Choose one of the three built-in serializers to register your configuration class. Registration should occur before the config is accessed, typically in the mod's init function.

```java
// Only choose one of these!
AutoConfig.register(ModConfig.class, Toml4jConfigSerializer::new);
AutoConfig.register(ModConfig.class, GsonConfigSerializer::new);
AutoConfig.register(ModConfig.class, JanksonConfigSerializer::new);
```

--------------------------------

### Define Partitioned Config Classes

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/partitioning-the-config.md

The top-level class inherits from GlobalData, while sub-configs implement ConfigData and use @Config annotations.

```java
@Config(name = "modid")
class ModConfig extends PartitioningSerializer.GlobalData {
    @ConfigEntry.Category("module_a")
    @ConfigEntry.Gui.TransitiveObject
    ModuleAConfig moduleA = new ModuleAConfig();
    
    @ConfigEntry.Category("module_b")
    @ConfigEntry.Gui.TransitiveObject
    ModuleBConfig moduleB = new ModuleBConfig();
}

@Config(name = "module_a")
class ModuleAConfig implements ConfigData {
    /* your config fields here */
}

@Config(name = "module_b")
class ModuleBConfig implements ConfigData {
    /* your config fields here */
}
```

--------------------------------

### Define a Configuration Class

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/creating-a-config-class.md

Implement the ConfigData interface and use the @Config annotation to define a configuration class. Use @ConfigEntry.Gui annotations to customize field behavior in the generated GUI.

```java
@Config(name = "modid")
class ModConfig implements ConfigData {
    boolean toggleA = true;
    boolean toggleB = false;
    
    @ConfigEntry.Gui.CollapsibleObject
    InnerStuff stuff = new InnerStuff();
    
    @ConfigEntry.Gui.Excluded
    InnerStuff invisibleStuff = new InnerStuff();
    
    static class InnerStuff {
        int a = 0;
        int b = 1;
    }
}
```

--------------------------------

### Configure build.gradle for Cloth Config

Source: https://shedaniel.gitbook.io/cloth-config/setup-cloth-config/setup-with-forge.md

Add the Shedaniel Maven repository and the Cloth Config dependency to your project's build.gradle file.

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

dependencies {
    [...]
    api(fg.deobf("me.shedaniel.cloth:cloth-config-forge:ABC"))
}
```

--------------------------------

### Create a Config Category

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/creating-a-config-category.md

Use the getOrCreateCategory method on the builder to initialize a new category with a translatable text title.

```java
ConfigCategory general = builder.getOrCreateCategory(new TranslatableText("category.examplemod.general"));
```

--------------------------------

### Register Partitioned Config

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/partitioning-the-config.md

Register the top-level config class using the PartitioningSerializer wrapper.

```java
AutoConfig.register(
    ModConfig.class,
    PartitioningSerializer.wrap(JanksonConfigSerializer::new)
);
```

--------------------------------

### Configure build.gradle for Cloth Config

Source: https://shedaniel.gitbook.io/cloth-config/setup-cloth-config/cloth-config-fabric.md

Add the required Maven repository and mod dependency to your project's build.gradle file. Replace ABC with the specific version of Cloth Config needed.

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

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

--------------------------------

### Add a String Text Field Option

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/creating-a-config-option.md

Add a string field to the configuration category, including default values, tooltips, and save consumers.

```java
[...]
general.addEntry(entryBuilder.startStrField(new TranslatableText("option.examplemod.optionA"), currentValue)
        .setDefaultValue("This is the default value") // Recommended: Used when user click "Reset"
        .setTooltip(new TranslatableText("This option is awesome!")) // Optional: Shown when the user hover over this option
        .setSaveConsumer(newValue -> currentValue = newValue) // Recommended: Called when user save the config
        .build()); // Builds the option entry for cloth config
```

--------------------------------

### Add ModMenu Dependency in Gradle

Source: https://shedaniel.gitbook.io/cloth-config/advanced/modmenu-integration.md

Include the ModMenu dependency in your build.gradle file. Replace ABC with the specific version required.

```java
dependencies {
    [...]
    modApi "com.terraformersmc:modmenu:ABC"
}
```

--------------------------------

### Register GuiTransformer

Source: https://shedaniel.gitbook.io/cloth-config/auto-config/custom-gui-handlers.md

Register transformers to modify generated GUI entries based on annotations or predicates. Transformers are applied in the order they are registered.

```java
registry.registerAnnotationTransformer(...); // apply based on the presence of an annotation
registry.registerPredicateTransformer(...); // apply based on a certain Predicate<Field>
```

--------------------------------

### Define saving behavior with setSavingRunnable

Source: https://shedaniel.gitbook.io/cloth-config/using-cloth-config/saving-the-config.md

Use this method to trigger serialization of configuration data after all variables have been updated.

```java
builder.setSavingRunnable(() -> {
    // Serialise the config into the config file. This will be called last after all variables are updated.
});
```
Tokens:
Raw