Field Entries

@ConfigEntry describes one field's on-disk name, comment, and restart behavior. @Config(comment = ...) does the same for the file header.

@Config(name = "mymod", comment = "Settings for MyMod.")
public final class MyModConfig {

    @ConfigEntry(name = "hud_scale", comment = "Scale of the HUD overlay, 1 to 4.")
    public int hudScale = 2;

    @ConfigEntry(restart = true, comment = "Takes effect on the next launch.")
    public String worldPreset = "default";

    @ConfigEntry(comment = {"Enable the particle overlay.", "Disable on low-end hardware."})
    public boolean particleOverlay = true;
}

name decouples the file key from the Java field name. Empty by default (uses the Java name). Set it to keep snake_case on disk, to stabilize a key across a Java rename, or to use a key that is not a legal Java identifier.

comment becomes the text above the entry. One array element per line; a blank element is a blank comment line; an element containing newlines is split, so a text block works just as well as an array. Leading whitespace in each line is preserved. Write the text, not the markers — each format renders them its own way:

// JSON5: single line → // comment, multiple lines → /* block */
@ConfigEntry(comment = "Single line.")
@ConfigEntry(comment = {"Line one.", "Line two."})

// TOML: each line gets its own # prefix

A */ in comment text is defused to * / so it can never truncate the JSON5 block.

restart marks a field that is read only at game startup. Any update that changes the value of a restart field is rejected as a whole — none of the other fields in the same mutator are applied either:

UpdateResult result = holder.update(config -> config.worldPreset = "flat");
result.accepted();                       // false
result.violations().getFirst().id();     // "restart.worldPreset"

reset is the exception: it restores every other field to its default while leaving restart fields at the value they had at startup. The restart check follows nested config objects; it does not descend into collections or maps.

---

@ConfigIgnore excludes a public field from persistence entirely. The field never appears in the file, is never read back, is never commented, and is never checked by the restart guard. Its value is whatever the constructor sets it to after every load:

@Config(name = "mymod")
public final class MyModConfig {

    public int hudScale = 2;               // persisted normally

    @ConfigIgnore
    public String sessionCache = "";       // public but never written to disk
}

Use @ConfigIgnore when the field must be public but should never appear in the config file.