File Format (JSON5 and TOML)

The format is declared on the config class, not on the builder, because it determines what the file on disk looks like — including the extension:

@Config(name = "mymod")                             // → config/mymod.json5  (default)
@Config(name = "mymod", format = ConfigFormat.TOML) // → config/mymod.toml

Both formats are first-class. The same class, the same annotations, and the same holder API work identically either way; only the on-disk representation changes.

JSON5 (ConfigFormat.JSON) writes files with the .json5 extension. The format is a superset of JSON that supports comments, tolerates trailing commas, and accepts unquoted keys — so a player can hand-edit the file and Lite Config will still read it back. Saving regenerates comments declared by @Config and @Entry; it does not preserve additional comments from the input file:

// Settings for MyMod.
{
  // Scale of the HUD overlay.
  "hudScale": 3,
  "showHints": true
}

TOML (ConfigFormat.TOML) writes standard TOML:

#Settings for MyMod.

#Scale of the HUD overlay.
hudScale = 3
showHints = true

TOML limitation — null fields: TOML has no null literal, so a null field is omitted from the file entirely and comes back as its declared default on the next load. JSON5 preserves null as a literal. If your config has nullable fields that may legitimately be null, stay on JSON5 or give them non-null defaults.

Switching formats: changing format changes the file extension. The previous file is no longer read, and defaults are written to the new one. Choose a format before the first public release when possible, because Lite Config does not migrate data between formats automatically.

See Names and Paths for how the format, config name, and optional subdirectory determine the final file location.