528
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + Line 7:
Line 7: − + Line 14:
Line 14: − + Line 21:
Line 21: + + − + Line 35:
Line 37: − + Line 49:
Line 51: − + − + − public class ModEntry : Mod+ Line 80:
Line 82: − + + + − + + − + − + − + − } − </syntaxhighlight> − − {{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: − − <syntaxhighlight lang="c#"> − class ModConfig − { − public KeybindList ToggleKey { get; set; } = KeybindList.ForSingle(SButton.F2); − − This is written/parsed the same way, but lets players specify multi-key or alternative bindings like <code>"LeftShift + F2, LeftTrigger"</code>. − }}
Modding:Modder Guide/APIs/Config (view source)
Revision as of 02:07, 26 May 2023
, 02:07, 26 May 2023→Using the config file
{{../../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==
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#">
<syntaxhighlight lang="c#">
class ModConfig
public sealed class ModConfig
{
{
public bool ExampleBoolean { get; set; }
public bool ExampleBoolean { get; set; }
</syntaxhighlight>
</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:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
}
}
</syntaxhighlight>
</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:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
class ModConfig
public sealed class ModConfig
{
{
public bool ExampleBoolean { get; set; } = true;
public bool ExampleBoolean { get; set; } = true;
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
class ModConfig
public sealed class ModConfig
{
{
public bool ExampleBoolean { get; set; }
public bool ExampleBoolean { get; set; }
==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:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
/// <summary>The main entry point for the mod.</summary>
/// <summary>The main entry point for the mod.</summary>
internal sealed class ModEntry : Mod
{
{
/*********
/*********
</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>.
Note that <samp>ReadConfig</samp> will raise an exception if the user does not provide a valid JSON.
==Keybind settings==
==Keybind settings==
: {{main article|Modding:Modder Guide/APIs/Input}}
: {{main article|Modding:Modder Guide/APIs/Input}}
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#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#">
<syntaxhighlight lang="c#">
class ModConfig
class ModConfig
{
{
public SButton ToggleKey { get; set; } = SButton.F2;
public KeybindList ToggleKey { get; set; } = KeybindList.Parse("LeftShift + F2, LeftTrigger");
}
}
</syntaxhighlight>
</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 <samp>config.json</samp> file as a string:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
"ToggleKey": "F2"
"ToggleKey": "LeftShift + F2, LeftTrigger"
}
}
</syntaxhighlight>
</syntaxhighlight>