Line 1: |
Line 1: |
| {{../../header}} | | {{../../header}} |
| | | |
− | You can let users configure your mod through a <tt>config.json</tt> file or store data in custom <tt>.json</tt> files. SMAPI will automatically create the file and take care of reading, normalising, and updating it. | + | You can let users configure your mod through a standard <tt>config.json</tt> file. SMAPI will automatically create the file and take care of reading, normalising, and updating it. |
| | | |
− | ==Config files== | + | ==Config model== |
− | Here's the simplest way to use <tt>config.json</tt>: | + | ===Creating a config model=== |
| + | The ''config model'' is a C# class you create, with properties representing the settings you want to store. It can contain almost anything from a few boolean fields to a complex object graph (though you should try to keep things simple for players). Here's a simple config model: |
| + | <source lang="c#"> |
| + | class ModConfig |
| + | { |
| + | public bool ExampleBoolean { get; set; } |
| + | public float ExampleFloat { get; set; } |
| + | } |
| + | </source> |
| | | |
− | <ol> | + | If you save that model to a JSON file, the file would look like this: |
− | <li>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: | + | <source lang="json"> |
| + | { |
| + | "ExampleBoolean": false, |
| + | "ExampleFloat": 0 |
| + | } |
| + | </source> |
| + | |
| + | ===Default values=== |
| + | You can set default values in your data model: |
| <source lang="c#"> | | <source lang="c#"> |
| class ModConfig | | class ModConfig |
Line 30: |
Line 46: |
| } | | } |
| } | | } |
− | </source></li> | + | </source> |
− | <li>Here's how you can access the config values in your <tt>ModEntry</tt> class: | + | |
| + | ==Using the config file== |
| + | To read the <tt>config.json</tt> (SMAPI will create it automatically): |
| + | |
| + | <ol> |
| + | <li>Create your [[#Config model|config model]].</li> |
| + | <li>Access the config values in your <tt>ModEntry</tt> class: |
| <source lang="c#"> | | <source lang="c#"> |
| /// <summary>The main entry point for the mod.</summary> | | /// <summary>The main entry point for the mod.</summary> |
Line 58: |
Line 80: |
| </ol> | | </ol> |
| | | |
− | That's it! When the player launches the game, SMAPI will create the <tt>config.json</tt> 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 <tt>this.Helper.WriteConfig(config)</tt>. | + | That's it! When the player launches the game, SMAPI will create the <tt>config.json</tt> 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 <tt>this.Helper.WriteConfig(this.Config)</tt>. |
− | | |
− | ==JSON files==
| |
− | ===Using JSON files===
| |
− | Sometimes one <tt>config.json</tt> isn't enough, or you need to store data that's not meant to be edited by the user. This is pretty easy too:
| |
− | <ol>
| |
− | <li>Create your model (just like the previous section).</li>
| |
− | <li>In your mod code, use the mod helper to read/write a named file. This example assumes you created a class named <tt>ModData</tt>, but you can use different names too.
| |
− | | |
− | <source lang="c#">
| |
− | // read file
| |
− | var model = this.Helper.ReadJsonFile<ModData>("data.json") ?? new ModData();
| |
− | | |
− | // save file (if needed)
| |
− | this.Helper.WriteJsonFile("data.json", model); | |
− | </source>
| |
− | | |
− | Note that <tt>ReadJsonFile</tt> will return <tt>null</tt> 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 <code>?? new ModData()</code> part.</li>
| |
− | </ol>
| |
− | | |
− | ===Subfolders and file names===
| |
− | The above example just uses <tt>"data.json"</tt>, but you can use any valid file name. If you specify a path relative to your mod folder (like <tt>data/some-file.json</tt>), 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:
| |
− | | |
− | <source lang="c#">
| |
− | // 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);
| |
− | </source>
| |
| | | |
| {{modding guide footer | | {{modding guide footer |