Tritium Configuration Overview

Tritium Configuration is a cross-platform (Fabric/Forge/NeoForge/Quilt) general-purpose configuration system that provides your mod with:

• Simple declarative configuration classes + annotations (grouping/range/validation/client-only)
• Auto-generated localizable configuration UI (based on Cloth Config v15)
• TOML-style flattened configuration files with hot reload support
• Configuration versioning, migration, and runtime validation

Supported data types: boolean, int, long, double, String, enums, List\<String\>.

Quick Start

1) Define Configuration Class

Use annotations to describe structure and constraints (can use static or instance fields; example below uses static fields):

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: custom overall validation
  public void validateConfig() {
    if (!general.enabled && general.maxEntities > 0) {
      throw new IllegalArgumentException("maxEntities must be 0 when disabled");
    }
  }
}

2) Register Configuration

Register during mod initialization (recommended early in main entry):

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: change filename (default your_mod_config)

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

3) Read Configuration in Code

Since the example uses static fields, you can reference them directly (instance fields can be obtained via TritiumConfig.getConfig(MOD_ID).get()):

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

4) Open Configuration UI (Optional)

Use the auto UI builder to generate a Cloth Config interface:

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

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

All UI titles/entries support localization (see "i18n Key Conventions" below).

5) Configuration File Location and Format

Default path: config/<modId>/<filename>.toml (e.g., config/your_mod/my_config.toml).

File uses "section + key-value" format, strings require quotes, lists use [...], example:

# your_mod Configuration
# Generated by TritiumConfig
# Environment: client
# Client-only sections will not be generated on server side

[general]
## Enabled
enabled = true

## Max Entities
maxEntities = 64

## Mode
mode = "SIMPLE"

#-------------------------
# Client
#-------------------------

## whitelist
whitelist = ["minecraft:player", "minecraft:villager"]

File changes are automatically detected and hot-reloaded without restarting the game.

---

Annotations and i18n

• @SubCategory("Display Name"): Group field as a subcategory, can be nested multiple levels; optional tooltip.
• @ClientOnly: Client-only (these items won't be generated/read on server side).
• @Range(min, max): Range constraint for int/long/double (out-of-range will log warning and revert to default).
• @Validation("rule"): String validation, supports minLength:n, maxLength:n, regex:pattern.
• @ConfigVersion(n): Declare configuration version for migration (see next section).

i18n key naming conventions (for auto UI and tooltip text):

• Title: config.{modid}.title
• Category: config.{modid}.category.{section} (e.g., general)
• Entry: config.{modid}.{section}.{path} and ... .tooltip
  • Top-level entries typically config.{modid}.{section}.{field}
  • Subcategory entries: config.{modid}.{section}.{sub.path} (dot-separated path)

---

Configuration Version Migration and Validation

When configuration structure changes, increase the @ConfigVersion value first, then add a static migration method for the old version:

// Migrate from v1
public static void migrateFromV1(java.util.Map<String, String> values) {
  String oldKey = "general.oldSetting";
  String newKey = "general.newSetting";
  if (values.containsKey(oldKey) && !values.containsKey(newKey)) {
    values.put(newKey, values.remove(oldKey));
  }
}

Additionally, you can declare a parameterless instance method public void validateConfig() in the configuration class for more complex overall validation.

Runtime and Platform

• Auto hot reload: Uses ConfigFileWatcher internally to poll file changes and call reload().
• UI: TritiumAutoConfig generates based on Cloth Config v15, works on both Fabric/NeoForge (platform integration see loader-specific factory classes).
• Thread safety: Save/reload processes synchronize internal state; avoid concurrent writes to custom files during save operations.