Line 1: |
Line 1: |
| {{../../header}} | | {{../../header}} |
| | | |
− | ===Configuration===
| |
| 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. |
| | | |
− | <dl>
| + | ==Config files== |
− | <dt>Basic configuration</dt>
| + | Here's the simplest way to use <tt>config.json</tt>: |
− | <dd>Here's the simplest way to use <tt>config.json</tt>:
| |
| | | |
| <ol> | | <ol> |
− | <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). | + | <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: |
− | <br />You can set defaults directly:
| |
− | | |
| <source lang="c#"> | | <source lang="c#"> |
| class ModConfig | | class ModConfig |
Line 20: |
Line 16: |
| </source> | | </source> |
| | | |
− | ...or with a constructor: | + | ...or set defaults with a constructor: |
| | | |
| <source lang="c#"> | | <source lang="c#"> |
Line 35: |
Line 31: |
| } | | } |
| </source></li> | | </source></li> |
− | | + | <li>Here's how you can access the config values in your <tt>ModEntry</tt> class: |
− | <li>In your <tt>ModEntry::Entry</tt> method, add this line to read the config options: | |
− | | |
− | <source lang="c#">
| |
− | ModConfig config = helper.ReadConfig<ModConfig>();
| |
− | </source>
| |
− | | |
− | Values are then accessible through the value config. Example:
| |
| <source lang="c#"> | | <source lang="c#"> |
| + | /// <summary>The main entry point for the mod.</summary> |
| public class ModEntry : Mod | | public class ModEntry : Mod |
| { | | { |
− | public override void Entry(IModHelper helper)
| + | /********* |
− | {
| + | ** Properties |
− | ModConfig config = helper.ReadConfig<ModConfig>();
| + | *********/ |
− | float exampleF = config.ExampleFloat;
| + | /// <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; |
| + | } |
| } | | } |
| </source> | | </source> |
Line 56: |
Line 58: |
| </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 edit and save the config, you can use <tt>helper.WriteConfig(config)</tt>. You can access the helper in other methods using <tt>this.Helper</tt>.</dd> | + | 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>. |
− | | |
− | <dt>Custom JSON files</dt>
| |
− | <dd>
| |
− | 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>:
| |
| | | |
| + | ==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> | | <ol> |
| <li>Create your model (just like the previous section).</li> | | <li>Create your model (just like the previous section).</li> |
− | <li>In your mod code, use <tt>this.Helper</tt> to read and write to a named file: | + | <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#"> | | <source lang="c#"> |
Line 75: |
Line 76: |
| | | |
| 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> | | 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></dd> | + | </ol> |
| | | |
− | <dt>Per-save JSON files</dt> | + | ===Subfolders and file names=== |
− | <dd>
| + | 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. |
− | 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: | + | ===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#"> | | <source lang="c#"> |
Line 89: |
Line 90: |
| // write file (if needed) | | // write file (if needed) |
| this.Helper.WriteJsonFile($"data/{Constants.SaveFolderName}.json", model); | | this.Helper.WriteJsonFile($"data/{Constants.SaveFolderName}.json", model); |
− | </source></dd> | + | </source> |
− | </dl>
| |