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.
- Define the value with its default and range.
- Register or load it when the mod starts.
- Read it where you need it (get() on the toml systems, the field itself on 1.12.2).
What you can change
Section titled “What you can change”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. |
For each loader and version
Section titled “For each loader and version”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.getConfigDirjava.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.defineInRangeModConfigSpec.IntValueModContainer.registerConfigModConfig.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");NeoForge 1.20.2 to 1.20.4
Section titled “NeoForge 1.20.2 to 1.20.4”Uses:
ModConfigSpec.Builder.defineInRangeModConfigSpec.IntValueModLoadingContext.registerConfigModConfig.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");NeoForge 26.3
Section titled “NeoForge 26.3”Uses:
ModConfigSpec.Builder.defineInRangeModConfigSpec.IntValueModContainer.registerConfigModConfig.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");Forge 1.16.5 to 1.20.1
Section titled “Forge 1.16.5 to 1.20.1”Uses:
ForgeConfigSpec.Builder.defineInRangeForgeConfigSpec.IntValueModLoadingContext.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");NeoForge 1.20.1
Section titled “NeoForge 1.20.1”Uses:
ForgeConfigSpec.Builder.defineInRangeForgeConfigSpec.IntValueModLoadingContext.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");Fabric 1.16.5 to 1.17.1
Section titled “Fabric 1.16.5 to 1.17.1”Uses:
FabricLoader.getConfigDirjava.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();Forge 1.12.2
Section titled “Forge 1.12.2”Uses:
@Config@Config.RangeInt@Config.CommentConfigManager.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); } } }}Sources
Section titled “Sources”- https://docs.neoforged.net/docs/1.21.1/misc/config
- https://maven.fabricmc.net/docs/fabric-loader-0.16.14/net/fabricmc/loader/api/FabricLoader.html
Related how-tos
Section titled “Related how-tos”- A block that does something when clicked
- A command that runs on the client
- A key the player can press
- A mob with attributes and a spawn egg
- A tool that breaks a 3 by 3 area
In Linen
Section titled “In Linen”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.