Getting Started

This guide will walk you through integrating Tritium Configuration into your mod from scratch and completing localization and UI integration.

1. Add Dependency

Make sure your project includes Cloth Config v15 and this library (works on both Fabric/NeoForge platforms).

Check Integration as Dependency to learn how to add dependencies.

2. Define Configuration Class

Use annotations to describe structure, grouping, and constraints (can use static or instance fields; static fields are recommended for beginners):

package your.mod;

import me.zcraft.tc.annotation.*;

@ConfigVersion(1)
public class MyConfig {
  @SubCategory("General")
  public static General general = new General();

  @ClientOnly
  @SubCategory("Client")
  public static Client client = new Client();

  public static class General {
    public boolean enabled = true;

    @Range(min = 1, max = 256)
    public int maxEntities = 64;

    public Mode mode = Mode.SIMPLE;
    public enum Mode { SIMPLE, VANILLA }
  }

  @ClientOnly
  public static class Client {
    public java.util.List\<String\> whitelist = java.util.Arrays.asList(
      "minecraft:player", "minecraft:villager"
    );
  }

  // Optional: overall validation
  public void validateConfig() {
    if (!general.enabled && general.maxEntities > 0) {
      throw new IllegalArgumentException("maxEntities must be 0 when disabled");
    }
  }
}

3. Register and Initialize

Register the configuration early in mod initialization (optionally customize filename):

import me.zcraft.tc.config.TritiumConfig;

public class YourModInit {
  public static final String MOD_ID = "your_mod";

  public static final TritiumConfig CONFIG = TritiumConfig
    .register(MOD_ID, MyConfig.class)
    .filename("my_config"); // Optional: default is your_mod_config

  public static void onInitialize() {
    // Other initialization logic
  }
}

After registration:

• Default configuration file is generated (if not exists)
• One validation pass is performed
• File watcher (hot reload) is started

4. Read Values in Code

• When using static fields: reference directly
• When using instance fields: obtain instance via TritiumConfig.getConfig(MOD_ID).get()

boolean enabled = MyConfig.general.enabled;
int max = MyConfig.general.maxEntities;
java.util.List\<String\> whitelist = MyConfig.client.whitelist;

5. Open Configuration UI (Optional)

Auto-generated UI is based on Cloth Config v15:

import me.zcraft.tc.config.TritiumAutoConfig;
import net.minecraft.client.gui.screens.Screen;

Screen screen = new TritiumAutoConfig(CONFIG).createConfigScreen(parent);

UI title, categories, entry names, and tooltip text are all localizable (see "Internationalization" section).

6. Configuration File Location and Hot Reload

• Default path: config/<modId>/<filename>.toml
• File changes are auto-detected within 2 seconds and trigger reload(), no game restart needed

7. Build and Publishing Recommendations

• Provide complete localization keys and tooltips for better usability
• Plan grouping hierarchy well (avoid excessive nesting)
• For first version, set @ConfigVersion to 1, upgrade version and provide migration for future structure changes