Difference between revisions of "Modding:Modder Guide/APIs/Config"
Pathoschild (talk | contribs) (+ footer nav links) |
Pathoschild (talk | contribs) (move JSON files info to new Modding:Modder Guide/APIs/Data, rewrite into self-contained config page) |
||
Line 1: | Line 1: | ||
{{../../header}} | {{../../header}} | ||
− | You can let users configure your mod through a <tt>config.json</tt> file | + | 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. |
− | ==Config | + | ==Config model== |
− | Here's | + | ===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: | ||
+ | <source lang="c#"> | ||
+ | class ModConfig | ||
+ | { | ||
+ | public bool ExampleBoolean { get; set; } | ||
+ | public float ExampleFloat { get; set; } | ||
+ | } | ||
+ | </source> | ||
− | < | + | If you save that model to a JSON file, the file would look like this: |
− | < | + | <source lang="json"> |
+ | { | ||
+ | "ExampleBoolean": false, | ||
+ | "ExampleFloat": 0 | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | ===Default values=== | ||
+ | You can set default values in your data model: | ||
<source lang="c#"> | <source lang="c#"> | ||
class ModConfig | class ModConfig | ||
Line 30: | Line 46: | ||
} | } | ||
} | } | ||
− | </source></li> | + | </source> |
− | <li> | + | |
+ | ==Using the config file== | ||
+ | To read the <tt>config.json</tt> (SMAPI will create it automatically): | ||
+ | |||
+ | <ol> | ||
+ | <li>Create your [[#Config model|config model]].</li> | ||
+ | <li>Access the config values in your <tt>ModEntry</tt> class: | ||
<source lang="c#"> | <source lang="c#"> | ||
/// <summary>The main entry point for the mod.</summary> | /// <summary>The main entry point for the mod.</summary> | ||
Line 58: | Line 80: | ||
</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( | + | 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>. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | this. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
{{modding guide footer | {{modding guide footer |
Revision as of 19:53, 18 August 2018
- 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 float ExampleFloat { get; set; }
}
If you save that model to a JSON file, the file would look like this:
{
"ExampleBoolean": false,
"ExampleFloat": 0
}
Default values
You can set default values in your data model:
class ModConfig
{
public bool ExampleBoolean { get; set; } = true;
public float ExampleFloat { get; set; } = 0.5f;
}
...or set defaults with a constructor:
class ModConfig
{
public bool ExampleBoolean { get; set; }
public float ExampleFloat { get; set; }
public ModConfig()
{
this.ExampleBoolean = true;
this.ExampleFloat = 0.5f;
}
}
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).