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

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

Config files

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 default values directly:

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

   ...or set defaults 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. Here's how you can access the config values in your ModEntry class:

   /// <summary>The main entry point for the mod.</summary>
   public class ModEntry : Mod
   {
       /*********
       ** Properties
       *********/
       /// <summary>The mod configuration from the player.</summary>
       private ModConfig Config;
   
   
       /*********
       ** Public methods
       *********/
       /// <summary>The mod entry point, called after the mod is first loaded.</summary>
       /// <param name="helper">Provides simplified APIs for writing mods.</param>
       public override void Entry(IModHelper helper)
       {
           this.Config = this.Helper.ReadConfig<ModConfig>();
           bool exampleBool = this.Config.ExampleBoolean;
       }
   }
   

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 save some changes, you can use this.Helper.WriteConfig(config).

JSON files

Using 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 too:

1. Create your model (just like the previous section).
2. In your mod code, use the mod helper to read/write a named file. This example assumes you created a class named ModData, but you can use different names too.

   // 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.

Subfolders and file names

The above example just uses "data.json", but you can use any valid file name. If you specify a path relative to your mod folder (like data/some-file.json), SMAPI will create the folders automatically if needed.

Per-save JSON files

You can create per-save files by using the save ID in the name. 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);