translators
8,403
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + − + − + + + + + + + + + − + − + + + + + + + + + Line 30:
Line 46: − + − + + + + + + + Line 58:
Line 80: − + − − ==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> − <li>Create your model (just like the previous section).</li> − <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#"> − // read file − var model = this.Helper.ReadJsonFile<ModData>("data.json") ?? new ModData(); − − // save file (if needed) − − </source> − − 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> − − ===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. − − ===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#"> − // read file − var model = this.Helper.ReadJsonFile<ModData>($"data/{Constants.SaveFolderName}.json") ?? new ModData(); − − // write file (if needed) − this.Helper.WriteJsonFile($"data/{Constants.SaveFolderName}.json", model); − </source>
Modding:Modder Guide/APIs/Config (view source)
Revision as of 19:53, 18 August 2018
, 19:53, 18 August 2018move JSON files info to new Modding:Modder Guide/APIs/Data, rewrite into self-contained config page
{{../../header}}
{{../../header}}
You can let users configure your mod through a <tt>config.json</tt> file or store data in custom <tt>.json</tt> files. 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 <tt>config.json</tt> file. SMAPI will automatically create the file and take care of reading, normalising, and updating it.
==Config files==
==Config model==
Here's the simplest way to use <tt>config.json</tt>:
===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>
<ol>
If you save that model to a JSON file, the file would look like this:
<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="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
}
}
}
}
</source></li>
</source>
<li>Here's how you can access the config values in your <tt>ModEntry</tt> class:
==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>
</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(config)</tt>.
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.Helper.WriteJsonFile("data.json", model);
{{modding guide footer
{{modding guide footer