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. In a @ConfigGroup, each member chooses its own format independently.

JSON5 (ConfigFormat.JSON) writes files with the .json5 extension. The format is a superset of JSON that preserves comments, tolerates trailing commas, and accepts unquoted keys — so a player can hand-edit the file and Easy Config will still read it back:

// 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, so the old file is simply never read again and the defaults are written to the new one. Deciding on a format before the first public release is worthwhile, as there is no automatic migration path.