translators
8,403
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − ===Configuration=== − <dl>+ − <dt>Basic configuration</dt>+ − <dd>Here's the simplest way to use <tt>config.json</tt>: − + − <br />You can set defaults directly: − Line 20:
Line 16: − + Line 35:
Line 31: − + − − − <source lang="c#"> − ModConfig config = helper.ReadConfig<ModConfig>(); − </source> − − Values are then accessible through the value config. Example: + − public override void Entry(IModHelper helper)+ − {+ − ModConfig config = helper.ReadConfig<ModConfig>();+ − float exampleF = config.ExampleFloat;+ − }+ + + + + + + + + + + + + Line 56:
Line 58: − + − − <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>: + + + − + Line 75:
Line 76: − + − + − <dd>+ − 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. − + + Line 89:
Line 90: − + − </dl>
Modding:Modder Guide/APIs/Config (view source)
Revision as of 22:35, 27 May 2018
, 22:35, 27 May 2018expand
{{../../header}}
{{../../header}}
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.
==Config files==
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:
<source lang="c#">
<source lang="c#">
class ModConfig
class ModConfig
</source>
</source>
...or with a constructor:
...or set defaults with a constructor:
<source lang="c#">
<source lang="c#">
}
}
</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#">
<source lang="c#">
/// <summary>The main entry point for the mod.</summary>
public class ModEntry : Mod
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;
}
}
}
</source>
</source>
</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>.
==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#">
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===
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.
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#">
// 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>