Line 1: |
Line 1: |
| {{../../header}} | | {{../../header}} |
| | | |
− | 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. | + | You can let users configure your mod through a standard <samp>config.json</samp> file. SMAPI will automatically create the file and take care of reading, normalising, and updating it. |
| | | |
| ==Config model== | | ==Config model== |
| ===Creating a config model=== | | ===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: | | 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#"> | + | <syntaxhighlight lang="c#"> |
− | class ModConfig | + | public sealed class ModConfig |
| { | | { |
| public bool ExampleBoolean { get; set; } | | public bool ExampleBoolean { get; set; } |
− | public float ExampleFloat { get; set; } | + | public int ExampleNumber { get; set; } |
| } | | } |
− | </source> | + | </syntaxhighlight> |
| | | |
− | That model would be saved to <tt>config.json</tt> with this content: | + | That model would be saved to <samp>config.json</samp> with this content: |
− | <source lang="json"> | + | <syntaxhighlight lang="json"> |
| { | | { |
| "ExampleBoolean": false, | | "ExampleBoolean": false, |
− | "ExampleFloat": 0 | + | "ExampleNumber": 0 |
| } | | } |
− | </source> | + | </syntaxhighlight> |
| + | |
| + | These properties must be public. |
| | | |
| ===Default values=== | | ===Default values=== |
| You can set default values in your data model: | | You can set default values in your data model: |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
− | class ModConfig | + | public sealed class ModConfig |
| { | | { |
| public bool ExampleBoolean { get; set; } = true; | | public bool ExampleBoolean { get; set; } = true; |
− | public float ExampleFloat { get; set; } = 0.5f; | + | public int ExampleNumber { get; set; } = 5; |
| } | | } |
− | </source> | + | </syntaxhighlight> |
| | | |
| ...or set defaults with a constructor: | | ...or set defaults with a constructor: |
| | | |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
− | class ModConfig | + | public sealed class ModConfig |
| { | | { |
| public bool ExampleBoolean { get; set; } | | public bool ExampleBoolean { get; set; } |
− | public float ExampleFloat { get; set; } | + | public int ExampleNumber { get; set; } |
| | | |
| public ModConfig() | | public ModConfig() |
| { | | { |
| this.ExampleBoolean = true; | | this.ExampleBoolean = true; |
− | this.ExampleFloat = 0.5f; | + | this.ExampleNumber = 5; |
| } | | } |
| } | | } |
− | </source> | + | </syntaxhighlight> |
| | | |
| ==Using the config file== | | ==Using the config file== |
− | To read the <tt>config.json</tt> (SMAPI will create it automatically): | + | To read the <samp>config.json</samp> (SMAPI will create it automatically): |
| | | |
| <ol> | | <ol> |
| <li>Create your [[#Config model|config model]].</li> | | <li>Create your [[#Config model|config model]].</li> |
− | <li>Access the config values in your <tt>ModEntry</tt> class: | + | <li>Access the config values in your <samp>ModEntry</samp> class: |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
| /// <summary>The main entry point for the mod.</summary> | | /// <summary>The main entry point for the mod.</summary> |
− | public class ModEntry : Mod
| + | internal sealed class ModEntry : Mod |
| { | | { |
| /********* | | /********* |
Line 76: |
Line 78: |
| } | | } |
| } | | } |
− | </source> | + | </syntaxhighlight> |
| </li> | | </li> |
| </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(this.Config)</tt>. | + | That's it! When the player launches the game, SMAPI will create the <samp>config.json</samp> 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 <samp>this.Helper.WriteConfig(this.Config)</samp>. |
| | | |
− | {{modding guide footer | + | Note that <samp>ReadConfig</samp> will raise an exception if the user does not provide a valid JSON. |
− | |prev = [[Modding:Modder Guide/APIs|SMAPI reference]]
| + | |
− | |next =
| + | ==Keybind settings== |
− | }} | + | : {{main article|Modding:Modder Guide/APIs/Input}} |
| + | |
| + | You can use SMAPI's [[Modding:Modder Guide/APIs/Input#KeybindList|<samp>KeybindList</samp>]] in your model to let users configure keybinds. This automatically supports multi-key or alternative bindings (''e.g.,'' to support split-screen mode): |
| + | |
| + | <syntaxhighlight lang="c#"> |
| + | class ModConfig |
| + | { |
| + | public KeybindList ToggleKey { get; set; } = KeybindList.Parse("LeftShift + F2, LeftTrigger"); |
| + | } |
| + | </syntaxhighlight> |
| + | |
| + | The value is automatically written/parsed in the <samp>config.json</samp> file as a string: |
| + | <syntaxhighlight lang="json"> |
| + | { |
| + | "ToggleKey": "LeftShift + F2, LeftTrigger" |
| + | } |
| + | </syntaxhighlight> |