Skip to content

How to make a config value players can change (Minecraft mod)

Forge and NeoForge have a config system: a spec built with defineInRange and friends (ForgeConfigSpec on Forge and NeoForge 1.20.1, ModConfigSpec on newer NeoForge), registered with the mod, which writes config/<file>.toml and checks every value. On 1.12.2 Forge builds a .cfg file from the fields of an annotated class. Fabric has none of its own; this one keeps a value in config/<mod>.properties through FabricLoader’s config folder and Java’s Properties, written with its default the first time.

Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.

  1. Define the value with its default and range.
  2. Register or load it when the mod starts.
  3. Read it where you need it (get() on the toml systems, the field itself on 1.12.2).

The example uses these values. Change them in the code.

Setting In the example What it does
value 16 Its default value.
min 1 The lowest value allowed.
max 64 The highest value allowed.
comment How many to give What it means, written above it in the file.

The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.

Fabric 1.18 to 1.21.1, Fabric 1.21.2 to 26.3

Section titled “Fabric 1.18 to 1.21.1, Fabric 1.21.2 to 26.3”

Uses:

  • FabricLoader.getConfigDir
  • java.util.Properties

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import com.example.examplemod.ExampleMod;
import java.io.IOException;
import java.io.Reader;
import java.io.Writer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
import net.fabricmc.loader.api.FabricLoader;
// max_gifts in config/examplemod.properties: How many to give (1 to 64, default 16).
public final class MaxGiftsConfig {
private static final Path FILE = FabricLoader.getInstance().getConfigDir().resolve("examplemod.properties");
private static int value = 16;
private MaxGiftsConfig() {
}
// Called from ExampleMod#onInitialize: reads the value, or writes its default the first time.
public static void load() {
Properties properties = new Properties();
try {
if (Files.exists(FILE)) {
try (Reader reader = Files.newBufferedReader(FILE)) {
properties.load(reader);
}
}
String text = properties.getProperty("max_gifts");
if (text == null) {
properties.setProperty("max_gifts", String.valueOf(value));
try (Writer writer = Files.newBufferedWriter(FILE)) {
properties.store(writer, "Example Mod");
}
} else {
value = Math.max(1, Math.min(64, Integer.parseInt(text.strip())));
}
} catch (IOException | NumberFormatException e) {
ExampleMod.LOGGER.warn("Could not read {} ({}); max_gifts stays {}", FILE, e.getMessage(), value);
}
}
public static int get() {
return value;
}
}

In your main mod class, inside onInitialize:

MaxGiftsConfig.load();

NeoForge 1.20.5 to 1.21.1, NeoForge 1.21.2 to 26.2

Section titled “NeoForge 1.20.5 to 1.21.1, NeoForge 1.21.2 to 26.2”

Uses:

  • ModConfigSpec.Builder.defineInRange
  • ModConfigSpec.IntValue
  • ModContainer.registerConfig
  • ModConfig.Type.COMMON

The value is in config/examplemod-max_gifts.toml; read it with MaxGiftsConfig.MAX_GIFTS.get() once the config has loaded.

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import net.neoforged.neoforge.common.ModConfigSpec;
// max_gifts in config/examplemod-max_gifts.toml: How many to give (1 to 64, default 16); NeoForge checks and corrects it.
public final class MaxGiftsConfig {
private static final ModConfigSpec.Builder BUILDER = new ModConfigSpec.Builder();
public static final ModConfigSpec.IntValue MAX_GIFTS = BUILDER.comment("How many to give").defineInRange("max_gifts", 16, 1, 64);
public static final ModConfigSpec SPEC = BUILDER.build();
private MaxGiftsConfig() {
}
}

In your main mod class, inside <init>:

modContainer.registerConfig(ModConfig.Type.COMMON, MaxGiftsConfig.SPEC, "examplemod-max_gifts.toml");

Uses:

  • ModConfigSpec.Builder.defineInRange
  • ModConfigSpec.IntValue
  • ModLoadingContext.registerConfig
  • ModConfig.Type.COMMON

The value is in config/examplemod-max_gifts.toml; read it with MaxGiftsConfig.MAX_GIFTS.get() once the config has loaded.

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import net.neoforged.neoforge.common.ModConfigSpec;
// max_gifts in config/examplemod-max_gifts.toml: How many to give (1 to 64, default 16); NeoForge checks and corrects it.
public final class MaxGiftsConfig {
private static final ModConfigSpec.Builder BUILDER = new ModConfigSpec.Builder();
public static final ModConfigSpec.IntValue MAX_GIFTS = BUILDER.comment("How many to give").defineInRange("max_gifts", 16, 1, 64);
public static final ModConfigSpec SPEC = BUILDER.build();
private MaxGiftsConfig() {
}
}

In your main mod class, inside <init>:

ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, MaxGiftsConfig.SPEC, "examplemod-max_gifts.toml");

Uses:

  • ModConfigSpec.Builder.defineInRange
  • ModConfigSpec.IntValue
  • ModContainer.registerConfig
  • ModConfig.Type.COMMON

Since 26.3 the config types are LOCAL, CLIENT, SYNCED and STARTUP; STARTUP is the old COMMON (loaded on both sides, not synced).

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import net.neoforged.neoforge.common.ModConfigSpec;
// max_gifts in config/examplemod-max_gifts.toml: How many to give (1 to 64, default 16); NeoForge checks and corrects it.
public final class MaxGiftsConfig {
private static final ModConfigSpec.Builder BUILDER = new ModConfigSpec.Builder();
public static final ModConfigSpec.IntValue MAX_GIFTS = BUILDER.comment("How many to give").defineInRange("max_gifts", 16, 1, 64);
public static final ModConfigSpec SPEC = BUILDER.build();
private MaxGiftsConfig() {
}
}

In your main mod class, inside <init>:

modContainer.registerConfig(ModConfig.Type.STARTUP, MaxGiftsConfig.SPEC, "examplemod-max_gifts.toml");

Uses:

  • ForgeConfigSpec.Builder.defineInRange
  • ForgeConfigSpec.IntValue
  • ModLoadingContext.registerConfig

The value is in config/examplemod-max_gifts.toml; read it with MaxGiftsConfig.MAX_GIFTS.get() once the config has loaded.

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import net.minecraftforge.common.ForgeConfigSpec;
// max_gifts in config/examplemod-max_gifts.toml: How many to give (1 to 64, default 16); Forge checks and corrects it.
public final class MaxGiftsConfig {
private static final ForgeConfigSpec.Builder BUILDER = new ForgeConfigSpec.Builder();
public static final ForgeConfigSpec.IntValue MAX_GIFTS = BUILDER.comment("How many to give").defineInRange("max_gifts", 16, 1, 64);
public static final ForgeConfigSpec SPEC = BUILDER.build();
private MaxGiftsConfig() {
}
}

In your main mod class, inside <init>:

ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, MaxGiftsConfig.SPEC, "examplemod-max_gifts.toml");

Uses:

  • ForgeConfigSpec.Builder.defineInRange
  • ForgeConfigSpec.IntValue
  • ModLoadingContext.registerConfig

The value is in config/examplemod-max_gifts.toml; read it with MaxGiftsConfig.MAX_GIFTS.get() once the config has loaded.

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import net.minecraftforge.common.ForgeConfigSpec;
// max_gifts in config/examplemod-max_gifts.toml: How many to give (1 to 64, default 16); NeoForge checks and corrects it.
public final class MaxGiftsConfig {
private static final ForgeConfigSpec.Builder BUILDER = new ForgeConfigSpec.Builder();
public static final ForgeConfigSpec.IntValue MAX_GIFTS = BUILDER.comment("How many to give").defineInRange("max_gifts", 16, 1, 64);
public static final ForgeConfigSpec SPEC = BUILDER.build();
private MaxGiftsConfig() {
}
}

In your main mod class, inside <init>:

ModLoadingContext.get().registerConfig(ModConfig.Type.COMMON, MaxGiftsConfig.SPEC, "examplemod-max_gifts.toml");

Uses:

  • FabricLoader.getConfigDir
  • java.util.Properties

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import com.example.examplemod.ExampleMod;
import java.io.IOException;
import java.io.Reader;
import java.io.Writer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
import net.fabricmc.loader.api.FabricLoader;
// max_gifts in config/examplemod.properties: How many to give (1 to 64, default 16).
public final class MaxGiftsConfig {
private static final Path FILE = FabricLoader.getInstance().getConfigDir().resolve("examplemod.properties");
private static int value = 16;
private MaxGiftsConfig() {
}
// Called from ExampleMod#onInitialize: reads the value, or writes its default the first time.
public static void load() {
Properties properties = new Properties();
try {
if (Files.exists(FILE)) {
try (Reader reader = Files.newBufferedReader(FILE)) {
properties.load(reader);
}
}
String text = properties.getProperty("max_gifts");
if (text == null) {
properties.setProperty("max_gifts", String.valueOf(value));
try (Writer writer = Files.newBufferedWriter(FILE)) {
properties.store(writer, "Example Mod");
}
} else {
value = Math.max(1, Math.min(64, Integer.parseInt(text.trim())));
}
} catch (IOException | NumberFormatException e) {
ExampleMod.LOGGER.warn("Could not read {} ({}); max_gifts stays {}", FILE, e.getMessage(), value);
}
}
public static int get() {
return value;
}
}

In your main mod class, inside onInitialize:

MaxGiftsConfig.load();

Uses:

  • @Config
  • @Config.RangeInt
  • @Config.Comment
  • ConfigManager.sync

The value is in config/examplemod-max_gifts.cfg; read it as MaxGiftsConfig.max_gifts. Forge builds the file from the annotated fields of the class, so nothing has to be registered.

src/main/java/com/example/examplemod/config/MaxGiftsConfig.java

package com.example.examplemod.config;
import com.example.examplemod.ExampleMod;
import net.minecraftforge.common.config.Config;
import net.minecraftforge.common.config.ConfigManager;
import net.minecraftforge.fml.client.event.ConfigChangedEvent;
import net.minecraftforge.fml.common.Mod;
import net.minecraftforge.fml.common.eventhandler.SubscribeEvent;
// max_gifts in config/examplemod-max_gifts.cfg: How many to give (1 to 64, default 16). Forge builds the file from the annotated fields and checks the range.
@Config(modid = ExampleMod.MOD_ID, name = "examplemod-max_gifts")
public class MaxGiftsConfig {
@Config.Comment("How many to give")
@Config.RangeInt(min = 1, max = 64)
public static int max_gifts = 16;
// Reloads the fields when the file changes in the game's config screen.
@Mod.EventBusSubscriber(modid = ExampleMod.MOD_ID)
public static class Sync {
@SubscribeEvent
public static void onChanged(ConfigChangedEvent.OnConfigChangedEvent event) {
if (event.getModID().equals(ExampleMod.MOD_ID)) {
ConfigManager.sync(ExampleMod.MOD_ID, Config.Type.INSTANCE);
}
}
}
}

Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.