Modding:Modder Guide/APIs/Config

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

Configuration

You can let users configure your mod through a config.json file. SMAPI will automatically create the file and take care of reading, normalising, and updating it.

Basic configuration

Here's the simplest way to use config.json:

1. Create your model. This is just a C# class with properties for the config options you want, and it can contain almost anything from a few boolean fields to a complex object graph (You should try to keep it simple for your users, though).
   You can set defaults directly:

   class ModConfig
   {
      public bool ExampleBoolean { get; set; } = true;
      public float ExampleFloat { get; set; } = 0.5f;
   }
   

   ...or with a constructor:

   class ModConfig
   {
      public bool ExampleBoolean { get; set; }
      public float ExampleFloat { get; set; }
   
      public ModConfig()
      {
         this.ExampleBoolean = true;
         this.ExampleFloat = 0.5f;
      }
   }
   

2. In your ModEntry::Entry method, add this line to read the config options:

   ModConfig config = helper.ReadConfig<ModConfig>();
   

   Values are then accessible through the value config. Example:

   public class ModEntry : Mod
   {
     public override void Entry(IModHelper helper)
     {
       ModConfig config = helper.ReadConfig<ModConfig>();
       float exampleF = config.ExampleFloat;
     }
   }
   

That's it! When the player launches the game, SMAPI will create the config.json file automatically if it doesn't exist yet, using the default config options you provided in your model. If you need to edit and save the config, you can use helper.WriteConfig(config). You can access the helper in other methods using this.Helper.

Custom JSON files

Sometimes one config.json isn't enough, or you need to store data that's not meant to be edited by the user. This is pretty easy using the ModHelper:

1. Create your model (just like the previous section).
2. In your mod code, use this.Helper to read and write to a named file:

   // read file
   var model = this.Helper.ReadJsonFile<ModData>("data.json") ?? new ModData();
   
   // save file (if needed)
   this.Helper.WriteJsonFile("data.json", model);
   

   Note that ReadJsonFile will return null if the file doesn't exist. The above example will create a default instance if that happens; if you don't want to do that, just remove the ?? new ModData() part.

Per-save JSON files

You can create per-save files by using the save ID in the name. If you specify a folder path (relative to your mod folder), SMAPI will create the folders automatically if needed. For example, here's a typical per-save data file:

// read file
var model = this.Helper.ReadJsonFile<ModData>($"data/{Constants.SaveFolderName}.json") ?? new ModData();

// write file (if needed)
this.Helper.WriteJsonFile($"data/{Constants.SaveFolderName}.json", model);