Difference between revisions of "Modding:Modder Guide/APIs/Config"
Pathoschild (talk | contribs) (+ keybind settings) |
m (Replace deprecated <source> tags with <syntaxhighlight> tags) |
||
Line 6: | Line 6: | ||
===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: | ||
− | < | + | <syntaxhighlight lang="c#"> |
class ModConfig | class ModConfig | ||
{ | { | ||
Line 12: | Line 12: | ||
public int ExampleNumber { get; set; } | public int ExampleNumber { get; set; } | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
That model would be saved to <tt>config.json</tt> with this content: | That model would be saved to <tt>config.json</tt> with this content: | ||
− | < | + | <syntaxhighlight lang="json"> |
{ | { | ||
"ExampleBoolean": false, | "ExampleBoolean": false, | ||
"ExampleNumber": 0 | "ExampleNumber": 0 | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
===Default values=== | ===Default values=== | ||
You can set default values in your data model: | You can set default values in your data model: | ||
− | < | + | <syntaxhighlight lang="c#"> |
class ModConfig | class ModConfig | ||
{ | { | ||
Line 30: | Line 30: | ||
public int ExampleNumber { get; set; } = 5; | public int ExampleNumber { get; set; } = 5; | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
...or set defaults with a constructor: | ...or set defaults with a constructor: | ||
− | < | + | <syntaxhighlight lang="c#"> |
class ModConfig | class ModConfig | ||
{ | { | ||
Line 46: | Line 46: | ||
} | } | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
==Using the config file== | ==Using the config file== | ||
Line 54: | Line 54: | ||
<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 <tt>ModEntry</tt> class: | ||
− | < | + | <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 | public class ModEntry : Mod | ||
Line 76: | Line 76: | ||
} | } | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
</li> | </li> | ||
</ol> | </ol> | ||
Line 86: | Line 86: | ||
You can use SMAPI's [[Modding:Modder Guide/APIs/Input#SButton|<tt>SButton</tt>]] type directly in your config model to configure keybindings: | You can use SMAPI's [[Modding:Modder Guide/APIs/Input#SButton|<tt>SButton</tt>]] type directly in your config model to configure keybindings: | ||
− | < | + | <syntaxhighlight lang="c#"> |
class ModConfig | class ModConfig | ||
{ | { | ||
public SButton ToggleKey { get; set; } = SButton.F2; | public SButton ToggleKey { get; set; } = SButton.F2; | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
The value is automatically written/parsed in the <tt>config.json</tt> file as a string: | The value is automatically written/parsed in the <tt>config.json</tt> file as a string: | ||
− | < | + | <syntaxhighlight lang="json"> |
{ | { | ||
"ToggleKey": "F2" | "ToggleKey": "F2" | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
{{SMAPI upcoming|3.9| | {{SMAPI upcoming|3.9| | ||
For compatibility with split-screen (when you may have players on both keyboard and controller), you should use [[Modding:Modder Guide/APIs/Input#KeybindList|<tt>KeybindList</tt>]] instead: | For compatibility with split-screen (when you may have players on both keyboard and controller), you should use [[Modding:Modder Guide/APIs/Input#KeybindList|<tt>KeybindList</tt>]] instead: | ||
− | < | + | <syntaxhighlight lang="c#"> |
class ModConfig | class ModConfig | ||
{ | { | ||
public KeybindList ToggleKey { get; set; } = KeybindList.ForSingle(SButton.F2); | public KeybindList ToggleKey { get; set; } = KeybindList.ForSingle(SButton.F2); | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
This is written/parsed the same way, but lets players specify multi-key or alternative bindings like <code>"LeftShift + F2, LeftTrigger"</code>. | This is written/parsed the same way, but lets players specify multi-key or alternative bindings like <code>"LeftShift + F2, LeftTrigger"</code>. | ||
}} | }} |
Revision as of 18:19, 19 February 2021
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
You can let users configure your mod through a standard config.json file. SMAPI will automatically create the file and take care of reading, normalising, and updating it.
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:
class ModConfig
{
public bool ExampleBoolean { get; set; }
public int ExampleNumber { get; set; }
}
That model would be saved to config.json with this content:
{
"ExampleBoolean": false,
"ExampleNumber": 0
}
Default values
You can set default values in your data model:
class ModConfig
{
public bool ExampleBoolean { get; set; } = true;
public int ExampleNumber { get; set; } = 5;
}
...or set defaults with a constructor:
class ModConfig
{
public bool ExampleBoolean { get; set; }
public int ExampleNumber { get; set; }
public ModConfig()
{
this.ExampleBoolean = true;
this.ExampleNumber = 5;
}
}
Using the config file
To read the config.json (SMAPI will create it automatically):
- Create your config model.
- Access the config values in your ModEntry class:
/// <summary>The main entry point for the mod.</summary> public class ModEntry : Mod { /********* ** Properties *********/ /// <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; } }
That's it! When the player launches the game, SMAPI will create the config.json 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 this.Helper.WriteConfig(this.Config).
Keybind settings
- Main article: Modding:Modder Guide/APIs/Input
You can use SMAPI's SButton type directly in your config model to configure keybindings:
class ModConfig
{
public SButton ToggleKey { get; set; } = SButton.F2;
}
The value is automatically written/parsed in the config.json file as a string:
{
"ToggleKey": "F2"
}
class ModConfig
{
public KeybindList ToggleKey { get; set; } = KeybindList.ForSingle(SButton.F2);
}
"LeftShift + F2, LeftTrigger"
.