Line 317: |
Line 317: |
| You can let users configure your mod through a <tt>config.json</tt> file. SMAPI will automatically create the file and take care of reading, normalising, and updating it. | | You can let users configure your mod through a <tt>config.json</tt> 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 <tt>config.json</tt>: | | Here's the simplest way to use <tt>config.json</tt>: |
| | | |
Line 356: |
Line 357: |
| </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. | + | 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 edit and save the config, you can use <tt>helper.SaveConfig(config)</tt>. You can access the helper in other methods using <tt>this.Helper</tt>. |
| | | |
− | If you need to edit and save the config, you can use <tt>helper.SaveConfig(config)</tt>. You can access the helper in other methods using <tt>this.Helper</tt>.
| + | ====Custom 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 using the <tt>ModHelper</tt>: |
| | | |
− | For more advanced config and JSON scenarios, see [[Modding:Advanced mod configuration]] which covers...
| + | <ol> |
− | * adding custom JSON files;
| + | <li>Create your model (just like the previous section).</li> |
− | * adding per-save JSON files;
| + | <li>In your mod code, just use <tt>this.Helper</tt> to read and write to a named file: |
− | * using a config wrapper for file I/O;
| |
− | * overriding JSON serialization.
| |
| | | |
| + | <source lang="c#"> |
| + | // read file |
| + | var model = this.Helper.ReadJsonFile<ModData>("data.json") ?? new ModData(); |
| | | |
− | <pre>
| + | // save file (if needed) |
− | ---
| + | this.Helper.WriteJsonFile("data.json", model); |
− | layout: default
| + | </source> |
− | title: Advanced SMAPI mod configuration
| |
− | intro: >
| |
− | This page explains more advanced ways to use JSON files through <code>this.Helper</code>.
| |
− | This page is overkill for the vast majority of mods; see
| |
− | <em><a href="creating-a-smapi-mod#configuration">creating a SMAPI mod</a></em>
| |
− | for a simpler approach that is sufficient for most mods.
| |
− | permalink: /for-devs/creating-a-smapi-mod-advanced-config
| |
− | redirect_from:
| |
− | - /guides/creating-a-smapi-mod-advanced-config
| |
− | ---
| |
| | | |
− | ## Custom JSON files
| + | 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. |
− | 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):
| + | ====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: |
| | | |
− | ```c#
| + | <source lang="c#"> |
− | 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:
| |
− | | |
− | ```c#
| |
− | // 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:
| |
− | | |
− | ```c#
| |
| // read file | | // read file |
| var model = this.Helper.ReadJsonFile<ModData>($"{Constants.SaveFolderName}/config.json") ?? new ModData(); | | var model = this.Helper.ReadJsonFile<ModData>($"{Constants.SaveFolderName}/config.json") ?? new ModData(); |
Line 425: |
Line 385: |
| // write file (if needed) | | // write file (if needed) |
| this.Helper.WriteJsonFile($"{Constants.SaveFolderName}/config.json", model); | | this.Helper.WriteJsonFile($"{Constants.SaveFolderName}/config.json", model); |
− | ```
| + | </source> |
− | </pre> | |
| | | |
| ===Content=== | | ===Content=== |