This page has been moved to the wiki. See the latest version at Modding:Creating a SMAPI mod.
« back to index

Advanced SMAPI mod configuration

This page explains more advanced ways to use JSON files through this.Helper. This page is overkill for the vast majority of mods; see creating a SMAPI mod for a simpler approach that is sufficient for most mods.

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 (see the main guide for more details):

    class ModData
    {
       public bool ExampleBoolean { get; set; }
       public float ExampleFloat { get; set; }
    
       public ModData()
       {
          this.ExampleBoolean = true;
          this.ExampleFloat = 0.5;
       }
    }
    
  2. In your mod code, just 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 also specify a directory path (relative to your mod directory) instead of just the file name. The directories will be created automatically if needed. For example, here’s how you’d use per-save config files:

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

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