Skip to content

Configs

Typed configs saved as TOML (or JSON5), with server sync, hot reload, presets and migrations. Players edit them in game through Glazed Menu or Configured (see Editing in game). Packages: net.ixdarklord.coolcatcore.api.config (with annotation, type, format) and api.config.client for opening the screens.

Scopes

ConfigScope Where it lives Synced
CLIENT Client only Never
COMMON Both sides, each with its own values No
SERVER The server's file Yes: sent on join and whenever it changes
WORLD Per world, in <world>/serverconfig (seeded from defaultconfigs) Yes
STARTUP Read before registration; fixed until restart Compared on join (see Startup configs)

Files are named config/<modid>-<scope>.toml by default.

Builder style

Build the values as static fields; push/pop make groups:

public final class MyServerConfig {
    private static final ConfigBuilder BUILDER = Config.builder(MyMod.MOD_ID, ConfigScope.SERVER)
            .comment("Server settings").version(2)
            .migration(1, root -> { /* edit the old JsonObject in place */ });

    public static final ConfigValue<Boolean> PVP = BUILDER.bool("pvp", true)
            .comment("Whether players can hurt each other.").build();

    static { BUILDER.push("players", "Per-player limits"); }
    public static final ConfigValue<Integer> MAX_HOMES = BUILDER.intValue("maxHomes", 3)
            .range(0, 64).slider().aliases("homeLimit").build();
    public static final ConfigValue<List<Identifier>> BANNED = BUILDER.list("bannedItems",
            ConfigTypes.identifier(Registries.ITEM), List.of(Identifier.withDefaultNamespace("tnt"))).maxSize(32).build();
    static { BUILDER.pop(); }

    static { BUILDER.preset("strict", preset -> preset.set(PVP, false).set(MAX_HOMES, 1)); }

    public static final Config CONFIG = BUILDER.build();   // registers and loads it

    public static void init() {}   // call from onConstructMod() to load the class
}

Read a value anywhere with MyServerConfig.MAX_HOMES.get(). Change it with set(...), then CONFIG.save(). Server values that change are synced to every player right away.

Entry types: - bool - intValue, longValue, floatValue, doubleValue (with range, min, max, slider) - string (with maxLength, notEmpty, pattern) - enumValue - color (0xRRGGBB) and colorWithAlpha (0xAARRGGBB) - identifier (optionally checked against a registry) - list (with size, minSize, maxSize) and stringList - value(key, ConfigType, default) and codec(key, Codec, default) for anything else

Every entry also accepts: - Display: comment, translation, hidden. - Restarts: requiresGameRestart, requiresWorldRestart. - Sync: serverOnly, localOnly, useServerValue. - Old key names: aliases. - Validation: validator. - Dependencies: enabledWhen(otherBooleanValue) greys the entry out in the editor while the other value is off. - Change callbacks: listener.

Annotation style

public static final ConfigObject<ClientSettings> CLIENT = ConfigObject.register(MyMod.MOD_ID, ConfigScope.CLIENT, new ClientSettings());

@ConfigEntry.Comment("Client settings")
public static final class ClientSettings {
    @ConfigEntry.Comment("Draws the overlay.")
    public boolean showHud = true;

    @ConfigEntry.Range(min = 0, max = 256) @ConfigEntry.Slider @ConfigEntry.EnabledWhen("showHud")
    public int particles = 32;

    @ConfigEntry.Color(alpha = true)
    public int tint = 0x80FF8800;
}

// Read: CLIENT.get().showHud

Annotations (in ConfigEntry): - Naming and docs: @Comment, @Key, @Aliases, @Translation. - Numbers: @Range, @Slider. - Colors: @Color. - Text and lists: @MaxLength, @Pattern, @Size. - Restarts: @RequiresRestart. - Sync: @ServerOnly, @LocalOnly, @UseServerValue. - Editor: @Hidden, @EnabledWhen.

Editing in game

Core loads, saves, syncs and hot reloads configs, and gives every mod with configs a command that opens them. It has config screens of its own, and Glazed Menu, a separate client-side mod, replaces them with its own when it's installed (1.2.2 or newer, since CoolCatLib 9.0.0).

Installed What players get
Glazed Menu Searchable editor screens with sliders, a color picker, undo/redo, presets and reset buttons, in your mod's theme. They open from its mod list, from /glazedmenu [mod] [config/category], or from your code.
Configured (MrCrayfish) Configured's own screens, from the NeoForge mod list and from Mod Menu on Fabric. Booleans, numbers, enums and text get its widgets; colors, ids and lists are edited as text. Synced configs are edited on the server by players allowed to.
Neither CoolCatLib's own screens: a card for each config, then the config's screen with its categories, search, sliders, a color picker, undo/redo, presets and reset buttons, in your mod's theme. They open from Mod Menu, NeoForge's mod list and the config command.

With both installed, Glazed Menu's screens show the configs.

Since

CoolCatLib's own screens are back on 26.x in 8.0.0, the same as on 1.21.1 and 1.20.1, where they always were. Before it, 26.x had no editor without Glazed Menu.

The config command

Every mod with CoolCatLib configs gets config under its own commands, with nothing to register:

Command Who What it does
/<command> config Anyone Opens the mod's config screens.
/<command> config <config> Anyone Opens one of them: /folios config client.
/<command> config reload [config] Operators Reads the mod's config files again after they were edited by hand, without restarting: the server's configs on the server, the player's client configs on their own game.
/coolcatlib config [mod] [config], /coolcatlib config reload [mod] [config] The same The same for any mod, including mods without commands of their own.

Anyone can open the screens; what they may change is still up to each config's editPermission. On a server without CoolCatLib, /coolcatlib config runs on the player's own game. Values are no longer read or changed from the chat (the old get, set, reset and preset subcommands are gone since 9.0.0): that is done in the screens.

From code

Open the screens from code through ConfigScreens: with Glazed Menu installed it opens Glazed Menu's screens, and without it CoolCatLib's own. It returns null only where there are no screens at all (on a dedicated server, say), so check before you use the result:

Screen screen = ConfigScreens.create(parent, MyMod.MOD_ID);         // the mod's configs, or null
if (screen != null) {
    Minecraft.getInstance().setScreen(screen);
} else {
    ConfigScreens.tellUnavailable(MyConfig.CONFIG);                  // tells the player how to change it without screens
}

ConfigScreens.open(MyMod.MOD_ID);                                   // over the current screen; nothing without screens
ConfigScreens.openCategory(MyMod.MOD_ID, "client/rendering");       // one group, as a popup
boolean hasScreens = ConfigScreens.isAvailable();

Names and tooltips are translated as config.<modid>.<config>.<path> (and .tooltip). Enums can implement EnumType.Displayable to give each constant a display name.

Themes

Give your mod's screens in Glazed Menu their own look from ClientModConstructor#onConstructMod():

ConfigTheme.setForMod(MyMod.MOD_ID, ConfigTheme.builder()
        .colors(ConfigColorScheme.tinted(0xFFA77BFF))
        .background(MyMod.id("textures/gui/config_background.png"))
        .build());

ConfigTheme.Builder settings: - Colors: colors, lightColors, accent. - Pictures: icon, background, mode (COVER, STRETCH, TILE), tiled. - Opacity: backgroundOpacity, textureOpacity, backgroundInWorld. - popupSprite: a nine-slice sprite for category popups. - effects: animated effects by id. They are registered with ConfigEffects.register(id, effect) (net.ixdarklord.coolcatcore.api.config.client).

Players switch CoolCatLib's own screens between dark and light; the choice is saved in config/coolcatlib-style.json.

Startup configs

A STARTUP config is read before content is registered, so it can decide which items or recipes exist. When a client joins, its values are compared with the server's: - REQUIRE_MATCH, the default: a client that doesn't match is stopped before it enters the world, and offered the server's values for its next start. - useServerValue() entries (StartupSync.USE_SERVER) take the server's value instead. - localOnly() entries are never compared.

Reference

Type Description
Config builder(modId, scope), get(id), all(), forMod(modId); save(), reload(), resetAll(), find(path), values(), presets(), applyPreset(...), addListener(...); isLoaded(), isRemote(), isRestartPending(), filePath().
ConfigBuilder name, fileName, format(ConfigFormats.TOML / JSON5), comment, version, migration, editPermission, hotReload, theme, background, effects, push, pop, group, the entry methods above, preset, build().
ConfigValue<T> get(), set(T), getStored(), getDefault(), reset(), isDefault(), validate(T), isActive(), isRestartPending(), addListener((old, new) -> ...).
ConfigGroup, ConfigNode The tree: children(), child(key), values(), key(), path(), displayName().
ConfigScope, StartupSync, RestartRequirement The enums described above.
ConfigPreset Named value sets: builder.preset(name, preset -> preset.set(value, x)).
ConfigEvents LOADED, RELOADED, UNLOADING, VALUE_CHANGED, SAVED, CHANGED, SYNCED (client).
ConfigTheme, ConfigColorScheme The look of the mod's screens in Glazed Menu: ConfigColorScheme.DARK, LIGHT, tinted(accent), tintedLight(accent), or a builder over every color.
annotation.ConfigObject, annotation.ConfigEntry The annotation style.
type.ConfigTypes BOOLEAN, INT, LONG, FLOAT, DOUBLE, STRING, COLOR, COLOR_ALPHA, IDENTIFIER; intRange, doubleRange, string(maxLength), pattern, enumOf, identifier(registry), listOf, codec.
type.EnumType.Displayable Implement on an enum to name its constants in the editor.
format.ConfigFormats TOML (default), JSON5.
client.ConfigScreens The bridge to Glazed Menu's screens (each returns null or does nothing without it): isAvailable(), create(parent, modId), create(parent, config), createModList(parent), categoryPopup(parent, config, path[, theme]), open(modId), openCategory(modId, path), colorPicker(...), hasConfigs(modId); unavailableMessage(config), tellUnavailable(config).
client.ConfigEffects, client.ConfigEffect Animated screen backgrounds and widget effects (on 26.x they were in Canvas's api.client.gui.theme before 9.0.0).
Glazed Menu: net.ixdarklord.glazedmenu.api.editor.ConfigEditors, ValueEditor, EditSlot Custom editor widgets for your own config types (moved from Core's api.config.client in 26.1.2-2).