TabbyLib Wiki

Setup

repositories {
    maven { url = "https://avie.cc/maven" }
}

dependencies {
    // Fabric (on 1.21.1: modImplementation)
    implementation "me.avie29.tabbylib:tabbylib:1.0.0+26.3"

    // NeoForge
    implementation "me.avie29.tabbylib:tabbylib-neoforge:1.0.0+26.3"

    // Forge (on 1.20.1: implementation fg.deobf("me.avie29.tabbylib:tabbylib-forge:1.0.0+1.20.1"))
    implementation "me.avie29.tabbylib:tabbylib-forge:1.0.0+26.3"
}

// fabric.mod.json
"depends": {
    "tabbylib": ">=1.0.0"
}

# neoforge.mods.toml (NeoForge) / mods.toml (Forge: mandatory=true instead of type)
[[dependencies.my_mod]]
modId = "tabbylib"
type = "required"
versionRange = "[1.0.0,)"
ordering = "AFTER"
side = "CLIENT"

Your first config

public final class MyConfig {
    public static final BooleanOption SHOW_HUD = BooleanOption.builder("showHud", true).build();
    public static final IntOption SIZE = IntOption.builder("size", 10).slider(1, 50, 1).build();
    public static final ColorOption COLOR = ColorOption.builder("color", 0xFFFFFFFF)
        .alpha()
        .dependsOn(SHOW_HUD)
        .build();

    private static TabbyConfig config;

    // Call this in your client initializer (Fabric) / mod constructor (NeoForge, Forge)
    public static void init() {
        config = TabbyConfig.builder("my-mod")
            .category("general", category -> category
                .add(SHOW_HUD)
                .group("look", group -> group.add(SIZE, COLOR)))
            .build();
    }

    public static TabbyConfig get() {
        return config;
    }
}

if (MyConfig.SHOW_HUD.get()) {
    drawHud(MyConfig.SIZE.get(), MyConfig.COLOR.get());
}

MyConfig.SHOW_HUD.set(false);
MyConfig.get().save();

Option types

BooleanOption.builder("glow", false)
    .dependsOn(SHOW_HUD)                        // greyed out while SHOW_HUD is off
    .enabledWhen(() -> SIZE.getPending() > 5)   // or any other condition
    .visibleWhen(() -> MODE.getPending() == Mode.ADVANCED)  // hidden instead of greyed out
    .requiresRestart()                          // shows a hint and a message after saving
    .onChange(value -> reloadRenderer())        // runs after the value was saved
    .binding(() -> Settings.glow, value -> Settings.glow = value)  // use an existing field
    .name(Component.literal("Glow"))            // instead of the translation key
    .tooltip(Component.literal("Makes it shine"))
    .hidden()                                   // saved, but not shown in the screen
    .build();

Categories, groups, texts and buttons

TabbyConfig.builder("my-mod")
    .category("general", category -> category
        .label(Component.translatable("config.my-mod.general.intro"))
        .add(SHOW_HUD, SIZE)
        .group("colors", group -> group
            .description(Component.literal("Everything about colors"))
            .collapsed()                        // closed when the screen opens
            .add(COLOR, BACKGROUND)))
    .category("advanced", category -> category
        .add(DEBUG)
        .add(ActionEntry.of(
            Component.literal("Cache"),
            Component.literal("Clear"),
            () -> MyMod.clearCache())))
    .build();

Translations

{
  "config.my-mod.showHud": "Show HUD",
  "config.my-mod.showHud.tooltip": "Shows or hides the whole HUD.",
  "config.my-mod.mode.simple": "Simple",
  "config.my-mod.mode.advanced": "Advanced",
  "config.my-mod.category.general": "General",
  "config.my-mod.group.colors": "Colors"
}

HUD elements

public static final HudPositionOption POSITION = HudPositionOption.builder("position",
    HudPosition.of(HudPosition.CENTER, HudPosition.END, 0, -50),   // bottom center, 50 px above the bottom
    MyHud::preview).build();

// Drawing the HUD
if (!TabbyLibApi.isHudEditorOpen()) {   // the editor draws its own preview
    HudPosition position = MyConfig.POSITION.get();
    int x = position.x(screenWidth, width);
    int y = position.y(screenHeight, height);
    draw(graphics, x, y);
}

// Preview for the editor (uses the unsaved values)
public static HudPreview preview() {
    return new HudPreview() {
        public int width() { return currentWidth(); }
        public int height() { return currentHeight(); }
        public void render(GuiGraphicsExtractor graphics, int x, int y) { draw(graphics, x, y); }
    };
}

// Open the editor directly, e.g. from a command
TabbyLibApi.openHudEditor(MyConfig.POSITION);

Advanced

Opening the config screen

TabbyLibApi.openScreen("my-mod");                 // e.g. from your own command
Screen screen = TabbyLibApi.createScreen(parent, "my-mod");

// Mod Menu (Fabric)
public ConfigScreenFactory<?> getModConfigScreenFactory() {
    return parent -> TabbyLibApi.createScreen(parent, "my-mod");
}

File name, display and saving

TabbyConfig.builder("my-mod")
    .fileName("mymod")                          // keeps an existing config/mymod.json
    .name(Component.literal("My Mod"))          // instead of the name from the mod metadata
    .icon(Identifier.fromNamespaceAndPath("my-mod", "textures/gui/icon.png"))
    .onSave(() -> MyMod.reload())               // runs after the file was written
    ...

Migrating old config files

.migration(json -> {
    if (!json.has("oldName")) {
        return false;
    }
    json.add("newName", json.remove("oldName"));
    return true;
})

Available versions