Using Mod Configs

Balm provides an easy-to-use configuration system that hooks into native mod loader's configs where available and supports different Config GUI mods.

To use Balm's configuration system, you need to:

1. Create your configuration class with fields for your categories and options
2. Register it with Balm in your mod's initializer

Defining Configurations

The annotation-based approach uses annotations on regular Java fields to define configuration properties.

@Config(value = "yourmodid", type = "common")
public class MyAnnotationConfig {
    @Comment("Enables the special feature")
    public boolean enableFeature = true;

    @Comment("Maximum number of items")
    public int maxItems = 100;

    @Comment("Message shown to players")
    public String welcomeMessage = "Welcome to my mod!";

    @Comment("Advanced configuration options")
    public AdvancedCategory advanced = new AdvancedCategory();

    public static class AdvancedCategory {
        @Comment("Multiplier for movement speed")
        @Synced // This will sync to clients
        public float speedMultiplier = 1.0f;

        @NestedType(String.class) // Important to specify on Lists and Sets
        @Comment("List of allowed items")
        public List<String> allowedItems = Arrays.asList("minecraft:diamond", "minecraft:gold_ingot");
    }
}

Registering Configurations

Register your configuration class in your mod's initialization code:

// in your static initializer method:
Balm.config().registerConfig(MyAnnotationConfig.class);

// or as part of a BalmModule:
@Override
public void registerConfig(BalmConfig config) {
    config.registerConfig(MyAnnotationConfig.class);
}

Accessing properties

You can retrieve the current configuration with all fields set to their configured values. This config may differ from the local config, as it includes values that were synced from the server.

// Get the active config object
MyReflectionConfig config = Balm.config().getActiveConfig(MyReflectionConfig.class);

// Access properties
boolean featureEnabled = config.enableFeature;
int max = config.maxItems;
float speed = config.advanced.speedMultiplier;

Updating properties

To update a property, you should use the updateLocalConfig() method and update the field values of the given config object.

Balm.config().updateLocalConfig(MyAnnotationConfig.class, config -> {
    config.maxItems = 200;
    config.advanced.speedMultiplier = 1.5f;
});

Network Synchronization

Properties marked as @Synced will be synced from server to clients when they join.

These changes are temporary and only apply to the active config, not the local config.

Loader-specific Differences

On Forge and NeoForge, local configs are managed by the mod loader and Balm acts as an access and network synchronization layer.

On Fabric, Balm manages local configs itself using a subset of the TOML format. The resulting TOML files are identical in both format and naming. However, Fabric uses the StringRepresentable of an enum for values while Neo/Forge use the enum's name (ignore-case).

Supported Config Screens

Balm automatically integrates with Mod Menu on Fabric to provide support for the following configuration screen mods:

• Cloth Config
• Configured

Since configs are managed through the default config system in NeoForge and Forge, any configuration screen mod that supports Neo/Forge's config system should work out of the box.

Supported Property Types

Balm supports the following property types:

• boolean
• int
• long
• float
• double
• String
• ResourceLocation (maps to namespace:path strings)
• any enum implementing StringRepresentable (maps to enum's getSerializedName())
• List<any of the above>
• Set<any of the above>

If you need property types beyond these, or lists of complex objects, there's a good chance your use case would be better solved through a data pack or custom JSON files.