API Reference

This document lists the main APIs and annotations of Tritium Configuration for easy reference.

Core Classes

TritiumConfig

• static TritiumConfig register(String modId, Class\<\?> configClass)
  • Register configuration and perform default validation, file creation, file watching.
• static TritiumConfig getConfig(String modId)
  • Get registered configuration handle.
• static Map\<String, TritiumConfig\> getAllConfigs()
  • Get snapshot of all registered configurations.
• <T\> T get()
  • Return current configuration object instance (if field is instance field, can read via it).
• void reload()
  • Reload from disk and apply to memory (will re-validate).
• void save()
  • Write current memory configuration back to disk (generates comments and sections).
• TritiumConfig filename(String name)
  • Customize filename (without extension), default modId + "_config".
• boolean isClientEnvironment() | String getModId() | Class\<\?> getConfigClass()

Notes and Limitations:

• Supported types: boolean/int/long/double/String/enum/List\<String\>.
• Unsupported types will log warning and revert to default value.
• Client-only fields/sections are ignored on server side.

TritiumAutoConfig (Auto UI)

• Constructor: new TritiumAutoConfig(TritiumConfig config)
• Screen createConfigScreen(Screen parent)
  • Build Cloth Config v15 configuration screen.
  • Text keys:
    • Title: config.{modid}.title
    • Category: config.{modid}.category.{section}
    • Entry: config.{modid}.{section}.{path} and ... .tooltip

Field to widget mapping:

• boolean → Toggle
• int/long/double → Numeric input (supports @Range)
• String → Text input
• enum → Enum dropdown
• List\<String\> → String list editor

Helper Classes (Usually No Need to Use Directly)

ConfigParser

• Parses toml-style files to key-value mapping, provides:
• Supplier\<Boolean\> getBoolean(String key, boolean def)
  • Supplier\<Integer\> getInt(String key, int def)
  • Supplier\<Long\> getLong(String key, long def)
  • Supplier\<Double\> getDouble(String key, double def)
  • Supplier\<String\> getString(String key, String def)
  • Supplier\<Enum\> getEnum(String key, Enum def)
  • Supplier\<List\<String\>\> getStringList(String key, List\<String\> def)

ConfigValue<T>

• Wraps Supplier\<T\> with cached value object:
  • Constructor: new ConfigValue\<\>(supplier) (default 3000ms cache)
  • T get(): Return cached value (auto-refresh on expiry)
  • void refresh(): Force cache refresh
  • T getRaw(): Direct read underlying Supplier
  • long getCacheAge(): Milliseconds since last refresh

ConfigFileWatcher

• Periodically checks config file lastModified, triggers callback if changed (default every 2s).

ConfigValidator

• Traverse configuration object for:
  • @Range numeric range validation
  • @Validation string rule validation (minLength:n, maxLength:n, regex:pattern)
  • Recursive validation of nested sections
  • Call public void validateConfig() if exists

ConfigMigration

• Execute multi-step migration based on @ConfigVersion(n) and file config_version.
• Custom migration: declare static method in configuration class public static void migrateFromV{n}(Map<String,String> values).
  • In method can move/rename/convert values by key name.
• Default example migrations (built-in):
  • v1→v2: rendering.enableCulling → rendering.entityCulling.enableCulling etc.
  • v2→v3: old.setting → new.setting

Annotation Reference

@SubCategory

• Target: FIELD, Retention: RUNTIME
• Attributes:
  • String value(): Display name
  • String tooltip() default "": Optional hint
• Purpose: Treat object field as subcategory, recursively expand inner fields.

@ClientOnly

• Target: FIELD/TYPE, Retention: RUNTIME
• Purpose: Read/generate only on client, ignored on server side.

@Range

• Target: FIELD, Retention: RUNTIME
• Attributes: double min(), double max(), String message()
• Purpose: Limit numeric field value range.

@Validation

• Target: FIELD, Retention: RUNTIME
• Attributes: String value() (rules: minLength:n, maxLength:n, regex:pattern)
• Purpose: Extra format validation for string fields.

@ConfigVersion

• Target: TYPE, Retention: RUNTIME
• Attributes: int value(), String migration() default ""
• Purpose: Declare current config version for migration flow.

Conventions and Best Practices

• Recommend using "functional modules" as top-level Section, place detailed settings in subcategories; avoid excessive nesting.
• For external use, static fields are most straightforward; if needing multiple config instances, change to instance fields and obtain via get().
• When changing key names, always provide migration method and upgrade @ConfigVersion to ensure smooth upgrade of old configs.
• Provide complete localization and tooltip for UI to improve usability.