TOML Config

An annotation-driven configuration library for Minecraft 1.12.2, utilizing ASM transformations and the NightConfig framework for automated data management.

Technical Overview

TOMLConfig automates the lifecycle of configuration files by injecting initialization logic directly into the class bytecode. This approach removes the necessity for manual load() or save() calls within mod entry points.

Key Features

• Automated Initialization: Uses an ASM CoreMod transformer to inject initialization hooks into the static initializer (<clinit>) of classes annotated with @TOMLConfig.
• Field Mapping: Automatically converts Java camelCase field names to TOML snake_case keys. Custom keys can be defined via annotations.
• Type Support: Native handling of primitives (and their wrappers), String, UUID, Enum, Array, and Collection.
• Validation DSL: Supports a custom boolean expression language for value constraints (ranges, intervals, and whitelists).
• Sync & Maintenance: Automatically generates comments and @Allowed headers in the TOML file based on code metadata.
• Smart Metadata Resolution: Automatically populates the [mod_info] header with the mod's display name and version via Forge's Loader. It features a lifecycle-aware fallback that hot-updates information during postInit if metadata was unavailable during early class loading.

Dependencies

This library requires the NightConfigTOMLLib wrapper to function.

• Repository: NightConfigTOMLLib on GitHub

Implementation Example

Java Configuration Class

Define a class with static fields and categories. Initialization occurs automatically upon class loading.

package com.yourmod.config;

import com.qsteam.toml_config.api.ConfigCategory;
import com.qsteam.toml_config.api.ConfigValue;
import com.qsteam.toml_config.api.TOMLConfig;
import java.util.UUID;

@TOMLConfig(modId = "yourmodid", name = "general_settings")
public class YourModConfig {

    @ConfigCategory(description = "Functional parameters for mod features")
    public static final FeaturesCategory FEATURES = new FeaturesCategory();

    public static class FeaturesCategory {
        
        @ConfigValue(comment = "Toggle for debug logging")
        public boolean enableGlobalDebug = false;

        @ConfigValue(key = "WelcomeMsg", comment = "WelcomeMsg -> welcome_msg\nAutomatic conversion to snake_case")
        public String serverWelcomeMessage = "Welcome to the Server!";

        @ConfigValue(
            range = "[1..100] & ![40..60]",
            comment = "Value must be between 1-100, excluding 40-60"
        )
        public int restrictedRange = 25;

        @ConfigValue(comment = "Current operational state")
        public OperationMode currentMode = OperationMode.BALANCED;
    
        @ConfigValue
        public UUID uuid = UUID.randomUUID();

        @ConfigCategory(description = "Nested Categories supports")
        public static final NestedCategory NESTED_CATEGORY = new NestedCategory();
    }
    
    public static class NestedCategory {
        @ConfigValue
        public boolean enable = true;
    }

    public enum OperationMode {
        ECO, BALANCED, OVERCLOCKED
    }
}

Resulting TOML Output

The library generates a formatted file (in path .minecraft/config/general_settings.toml) with metadata headers:

#Generated by TOML Config.
[mod_info]
    id = "yourmodid"
    name = "Your Mod Name"
    version = "mod.version.like.0.1-beta"

#Functional parameters for mod features
[features]
    #Toggle for debug logging
    #@Allowed: boolean{true,false}
    enable_global_debug = false
    #WelcomeMsg -> welcome_msg
    #Automatic conversion to snake_case
    welcome_msg = "Welcome to the Server!"
    #Value must be between 1-100, excluding 40-60
    #@Allowed: [1..100] & ![40..60]
    restricted_range = 25
    #Current operational state
    #@Allowed: OperationMode{ECO,BALANCED,OVERCLOCKED}
    current_mode = "BALANCED"
    uuid = "adb003ff-8f24-4cd2-8afe-1f3f7772e959"
    
    #Nested Categories supports
    [features.nested_category]
        #@Allowed: boolean{true,false}
        enable = true

Management

In-Game

Currently, via commands, with GUI support planned for future releases

Configurations can be reloaded from the disk at runtime using the following command: /toml_config reload
This updates all active configuration fields without requiring a client or server restart.

Roadmap

• GUI Integration: A graphical configuration editor (compatible with vanilla Minecraft settings) is currently under development for future releases.