BetterConfig

BetterConfig

A powerful command-based configuration management library that works equally well on both Minecraft servers and clients.

Quick Start

To begin, create a new class that will contain all your settings. Let's call it Configs. Make sure the class is declared as public! Then add a field for the configuration entry - it should not be final. Place the @Config annotation above the field. The initial field value will be used as the default value. You can add a comment using the comment attribute.

public class Configs {
    @Config(comment = "This is an example!")
    public static String exampleString = "default";
}

Now register your Configs class:

• For Fabric: add registration to your mod's onInitialize(Client) method. Replace <mod id> with your mod's identifier. Sometimes you can omit generics and use just <>.
  • On clients:

    new ModConfigBuilder<FabricClientCommandSource, CommandBuildContext>(<mod id>, Configs.class).build();

  • On servers:

    new ModConfigBuilder<CommandSourceStack, CommandBuildContext>(<mod id>, Configs.class).build();

• For Paper: register the Configs class in your plugin's onEnable method. Replace <plugin name> with your plugin's name.

  new ModConfigBuilder<>(<plugin name>, Configs.class).build();

Done! Now you can access exampleString via Configs.exampleString. You can modify the value using configuration commands.

Commands for Modifying Settings

• Fabric: commands differ for client and server. Replace <mod id> with your mod's identifier.
  • On clients: /cconfig <mod id> exampleString set <string>
  • On servers: /config <mod id> exampleString set <string>
• Paper servers: /config <plugin name> exampleString set <string>. Replace <plugin name> with your plugin's name.

Advanced Features

The library supports using Collection and Map as variable types. For such configurations, add, put, and remove operations are available. Additionally, you can create custom serializers to work with any data types. To do this, simply register the serializer when creating the configuration.

For example, to work with the Block type:

new ModConfigBuilder<>(<mod id>, Configs.class)
    .registerTypeHierarchy(Block.class, new BlockAdapter(), BlockArgumentType::block)
    .build();

where BlockAdapter extends TypeAdapter<Block>, and BlockArgumentType implements ArgumentType<Block>.

Behavior Customization

You can completely change the logic for updating configuration values by creating your own methods. Simply add one or more attributes: setter, adder, putter, or remover to the @Config annotation.

Example with custom addition to Map:

@Config(putter = @Config.Putter("none"), adder = @Config.Adder("customMapAdder"))
public static Map<String, String> exampleMapAdder = new HashMap<>(Map.of("a", "A", "b", "B"));
public static void customMapAdder(String string) {
    exampleMapAdder.put(string.toLowerCase(Locale.ROOT), string.toUpperCase(Locale.ROOT));
}

The value "none" for putter indicates that the standard putter will not be available. Now you can add values to the Map using the command /(c)config <mod id> exampleMapAdder add <string>.

Update method parameters can also be customized:

@Config(adder = @Config.Adder(value = "customTypeAdder", type = int.class))
public static Collection<String> exampleCustomType = new ArrayList<>(List.of("%", "@"));
public static void customTypeAdder(int codepoint) {
    exampleCustomType.add(Character.toString(codepoint));
}

For putters, separate type attributes for key and value are available.

Installation

Replace ${betterconfig_version} with the artifact version.

You can choose between the author's own maven repository and GitHub Packages repository.

Own Repository

repositories {
    maven {
        url 'https://maven.xpple.dev/maven2'
    }
}

GitHub Packages

repositories {
    maven {
        url 'https://maven.pkg.github.com/xpple/BetterConfig'
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
        }
    }
}

Add the dependency:

dependencies {
    // Fabric
    include modImplementation('dev.xpple:betterconfig-fabric:${betterconfig_version}')
    // Paper (also add the JAR to the plugins folder)
    compileOnly 'dev.xpple:betterconfig-paper:${betterconfig_version}'
}