Sodium Documentation

To register options, you must implement the net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint interface. You can register this entrypoint using metadata (Fabric) or annotations (NeoForge).

Fabric Registration

Add the entrypoint to your fabric.mod.json under the sodium:config_api_user key.

{
    "entrypoints": {
        "sodium:config_api_user": [
            "com.example.examplemod.ExampleModConfigBuilder"
        ]
    }
}

NeoForge Registration

Use the @ConfigEntryPointForge("your_mod_id") annotation on your implementation class. The annotation requires your mod ID to correctly associate the config with your mod when using ConfigBuilder.registerOwnModOptions().

import net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint;
import net.caffeinemc.mods.sodium.api.config.ConfigEntryPointForge;

@ConfigEntryPointForge("examplemod")
public class ExampleConfigUser implements ConfigEntryPoint {
    // Implementation of registerConfigLate
}

Implement registerConfigLate(ConfigBuilder builder) to define your mod's settings pages. The API uses a declarative builder pattern to create pages, groups, and options.

Key Concepts:

• Pages: Top-level containers for a mod's settings. Can have an ID, name, version, theme color, and an icon.
• Groups: Collections of options within a page.
• Options: Individual settings (Boolean, Integer slider, Enum, or External Screen).

Important Note on Data Storage: The Sodium Config API is a presentation API only. It does not handle saving or loading files. You must provide a storageHandler (a Runnable to flush changes) and use setBinding to connect the UI to your own configuration storage logic.

package com.example.examplemod;

import net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint;
import net.caffeinemc.mods.sodium.api.config.structure.ConfigBuilder;
import net.minecraft.network.chat.Component;
import net.minecraft.resources.Identifier;

public class ExampleConfigUser implements ConfigEntryPoint {
    private final OptionStorage storage = new OptionStorage();
    private final Runnable handler = this.storage::flush;
    
    @Override
    public void registerConfigLate(ConfigBuilder builder) {
        builder.registerOwnModOptions()
                .setIcon(Identifier.parse("examplemod:textures/gui/icon.png"))
                .addPage(builder.createOptionPage()
                        .setName(Component.literal("Example Page"))
                        .addOptionGroup(builder.createOptionGroup()
                                .setName(Component.literal("Example Group"))
                                .addOption(builder.createBooleanOption(Identifier.parse("examplemod:example_option"))
                                        .setName(Component.literal("Example Option"))
                                        .setTooltip(Component.literal("Example tooltip"))
                                        .setStorageHandler(this.handler)
                                        .setBinding(this.storage::setExampleOption, this.storage::getExampleOption)
                                        .setDefaultValue(true)
                                )
                        )
                );
    }
}

class OptionStorage {
    private boolean exampleOption = true;
    public boolean getExampleOption() { return this.exampleOption; }
    public void setExampleOption(boolean value) { this.exampleOption = value; }
    public void flush() { /* Save to file here */ }
}

The OptionBuilder provides methods to define the behavior, appearance, and side effects of a configuration option:

• Storage: OptionBuilder.setStorageHandler allows you to flush changes to the config file once after all bindings are updated, rather than on every single change.
• UI/UX:
  • OptionBuilder.setTooltip(Function): Sets a tooltip, which can be a function that generates text based on the current value (useful for long enum descriptions).
  • OptionBuilder.setImpact(Impact): Specifies performance impact (e.g., low, high, or "varies").
  • OptionBuilder.setEnabled(boolean): Disables the option (shows as strikethrough and non-interactive).
• Values & Constraints:
  • OptionBuilder.setDefaultValue(T) or OptionBuilder.setDefaultProvider(Provider): Sets the fallback value if constraints are not met.
  • OptionBuilder.setBinding(Binding): Configures the binding used to load the initial value and handle updates/resets.
• Side Effects:
  • OptionBuilder.setFlags(Set<OptionFlag>): Controls what is reset when the option is applied (e.g., reloading chunks or resource packs).
  • OptionBuilder.setApplyHook(Consumer<ConfigState>): Runs a hook after the option has been saved if its value changed.

Use ConfigBuilder.registerOwnModOptions to register options for the mod that owns the entrypoint (or the mod ID specified in @ConfigEntryPointForge). This returns a ModOptionsBuilder to configure the mod's identity and appearance in the video settings page list.

Key Configuration Options:

• Identity: Set the mod's ID, name, version, or a version formatter.
• Color Themes: Use ModOptionsBuilder.setColorTheme to set a custom color. You can provide three (A)RGB colors or a single base color (lighter and darker colors are derived automatically).
• Icons:
  • ModOptionsBuilder.setIcon(Identifier): Sets an icon that is tinted with the theme color and rendered as a square.
  • ModOptionsBuilder.setNonTintedIcon(Identifier): Sets an icon that is not tinted.
• External Pages: Use ConfigBuilder.createExternalPage(String name, Consumer<Screen> screenSwitcher) to create a link that switches to a custom Screen when clicked.