Lite Config: The Essential Config Library for Minecraft Mods

Lite Config simplifies JSON5/TOML config files for Minecraft mods on Fabric and NeoForge, with validation, sync, and versioning.

Lite Config

If you have ever built a Minecraft mod, you know that configuration files can quickly become a chore. Between parsing, validating, handling corrupt files, and syncing values between server and client, a surprising amount of development time goes into what should be a simple feature. Lite Config changes that. This powerful yet lightweight library for Fabric and NeoForge handles the entire configuration data layer, letting you focus on the fun parts of modding.

Why You Need Lite Config for Minecraft

Lite Config for Minecraft is not just another config library; it is a comprehensive solution that streamlines the entire process. Instead of writing boilerplate code for file I/O, you simply annotate a Java class with @Config, hand it to a builder, and receive a ready-to-use ConfigHolder. This holder manages everything: file path resolution, reading and writing, corrupt-file recovery, atomic writes, and lifecycle events.

For modders, this means less time debugging file formats and more time creating engaging gameplay. For players, it means configs that are reliable, readable, and safe to edit. The library supports both JSON5 and TOML formats, giving you and your users flexibility in how settings are presented.

Core Features of Lite Config

The feature set of Lite Config is designed to cover every practical need for modern Minecraft modding. Here is a breakdown of what you get out of the box:

Robust Configuration Data Layer

  • File Management: Lite Config handles default values, file path resolution, and atomic writes to prevent corruption.
  • Corruption Recovery: If a file is malformed, the library gracefully recovers, falling back to defaults rather than crashing the game.
  • Format Support: Choose between JSON5 for its readability and comments, or TOML for its strict structure.

Safe State Management

  • Validated Snapshots: Access deep copies of your config state to avoid concurrency issues.
  • Runtime Updates: Apply changes to the config while the game is running without restarting.
  • Custom State Cloning: Define exactly how your complex objects are copied for maximum control.

Advanced Synchronization and Updates

  • Opt-in Sync: Mark a config or a specific field as sync = true to automatically keep server and client values in lockstep.
  • Restart Guards: Prevent runtime changes to fields that require a game restart, and defer synchronized changes until it is safe.
  • Custom Update API: The update and updateAndSave methods return an UpdateResult with acceptance status and validation violations.

Validation and Metadata

  • Declared Constraints: Use annotations like @Range, @Pattern, and @Length to enforce rules on load and update.
  • Config Metadata: Query every field's path, type, default, comment, and translation key at runtime—perfect for generating in-game help or settings screens.
  • Lifecycle Events: Hook into load, save, and update events, or use config-level hooks for normalization and validation.

Versioning and Migrations

One of the standout features of Lite Config is its built-in versioning system. You can stamp a revision number into your config file. When you release a new mod version with changed settings, you can write migration functions that upgrade older files step by step. This means your players will never lose their carefully tuned settings due to a mod update. The @Migration annotation makes this process incredibly straightforward, allowing you to rename fields or set new defaults based on the old data.

Getting Started: How to Install

Ready to try it? The library is published on Maven Central under the group com.gmalvestimenti.minecraft, with separate artifacts for each loader: liteconfig-fabric and liteconfig-neoforge. You can find the latest versions for Minecraft 1.21 and 1.21.11 builds. For the most convenient setup, many players and developers use the foxygame.net launcher, which offers a one-click install for mods that depend on Lite Config, ensuring you always have the correct version for your Minecraft build. Its integrated add-on catalog and auto-update features take the guesswork out of dependency management, letting you get straight to playing or testing your mods.

Basic Setup for Fabric

To use Lite Config in your Fabric project, add the Maven Central repository and the dependency to your build.gradle. You will also need to declare a dependency in your fabric.mod.json so the loader refuses to start without it.

Basic Setup for NeoForge

For NeoForge, the process is similar. Add the dependency to your build.gradle and declare it in your META-INF/neoforge.mods.toml file. The library's entrypoints handle all the packet registration and synchronization logic for you.

A Quickstart Example

Here is how simple it is to get started. First, declare your config class with defaults and a public no-argument constructor:

@Config(name = "mymod")
public final class MyModConfig {
    public boolean showHints = true;
    public int hudScale = 2;
}

Then, create the holder once during mod initialization:

public static final ConfigHolder<MyModConfig> CONFIG =
    LiteConfig.holder(MyModConfig.class)
        .modId("mymod")
        .create();

That is it. The first time your mod runs, it creates config/mymod.json5 with the default values. You can read the config with CONFIG.data() and update it with CONFIG.updateAndSave(config -> config.hudScale = 3). The library handles the rest, including validation and writing the file atomically.

Beyond the Basics

Lite Config also supports asynchronous and read-only holders. For configs that are only read by the mod and never changed by the player, a readOnly().create() holder is perfect. For heavy operations, you can use the asynchronous methods backed by a shared config worker to keep the game thread responsive. The library also provides fine-grained failure policies, so you can decide whether a read or write failure should fall back to defaults or throw a strict exception.

Conclusion

Lite Config is a game-changer for Minecraft mod development. It is a robust, well-documented, and thoughtfully designed library that handles the messy details of configuration management. Whether you are a seasoned modder or just starting out, the time you save by using Lite Config is invaluable. Its support for modern Minecraft versions and both Fabric and NeoForge makes it a future-proof choice. To see the full power of the library, including custom codecs for complex types and the complete metadata API, check out the official wiki. Once you try it, you will wonder how you ever managed configs without it. You can download Lite Config from Maven Central and start simplifying your mod's configuration layer today.

Author: KlamrFox

Related Articles