Dial

A lightweight config library for Minecraft mods. Declare your options in a few lines and Dial saves them and builds the settings screen for you.

Why Dial?

• You never write serialization code or build a screen by hand.
• The same code runs on every supported version and loader, so you write your config once and keep it as you port.
• It supports everything from Beta 1.7.3 up to the latest releases.
• An optional Kotlin module adds a builder DSL and property delegates.
• Dial configs can show up in OneConfig.

Supported versions

For players

Install Dial next to any mod that needs it.

For developers

Java

public final class MyMod {
    public static final Config CONFIG = Dial.config("mymod", "My Mod");

    public static final BooleanOption ENABLED = CONFIG.toggle("enabled", true)
        .description("Turn the mod on or off.");
    public static final EnumOption<Corner> CORNER = CONFIG.cycle("corner", Corner.TOP_LEFT)
        .description("Which corner of the screen to draw in.");
    public static final SliderOption OPACITY = CONFIG.slider("opacity", 40, 0, 100, 5).suffix("%")
        .description("Background opacity.");
    public static final TextOption FORMAT = CONFIG.text("format", "{fps} FPS").maxLength(64)
        .description("The text to show.");
}

Read a value with ENABLED.get(), change it with set(...), and open the settings screen with Dial.open(CONFIG). Use onChange(...) to react when the player edits an option.

Bigger mods can group options into categories. Each category gets its own button on the settings screen and opens a page of its own, and categories can nest:

public static final Category ITEMS = CONFIG.category("items").description("How held items look.");
public static final BooleanOption BLOCK_HITTING = ITEMS.toggle("block_hitting", true);
public static final BooleanOption ALWAYS_SWING = ITEMS.category("swing").toggle("always_swing", false);

Categories only change the screen. Every option still lives in the same config file, so option ids must be unique across the whole config.

Kotlin

object MyMod {
    val config = dial("mymod", "My Mod")

    val enabled by config.toggle("enabled", true)
        .description("Turn the mod on or off.")
    val corner by config.cycle("corner", Corner.TOP_LEFT)
        .description("Which corner of the screen to draw in.")
    val opacity by config.slider("opacity", 40.0, 0.0..100.0, 5.0).suffix("%")
        .description("Background opacity.")
    val format by config.text("format", "{fps} FPS").maxLength(64)
        .description("The text to show.")
}

A fully working FPS HUD example, lives in example/.

License

Dial is licensed under Apache-2.0. You can use, modify, and distribute it in any project, commercial ones included, without paying royalties.