Changes

==Storage options==

==Storage options==

===JSON files===

===JSON files===

You can store data in arbitrary <tt>.json</tt> files in your mod folder. Note that these files will be lost if the player deletes them (e.g. when updating your mod), so this is mainly useful for bundled files, cache files, etc.

You can store data in arbitrary <samp>.json</samp> files in your mod folder. Note that these files will be lost if the player deletes them (e.g. when updating your mod), so this is mainly useful for bundled files, cache files, etc.

<ol>

<ol>

<li>[[#Data model|Create your data model]].</li>

<li>[[#Data model|Create your data model]].</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.

<li>In your mod code, use the mod helper to read/write a named file. This example assumes you created a class named <samp>ModData</samp>, but you can use different names too.

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

</syntaxhighlight>

</syntaxhighlight>

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 <samp>ReadJsonFile</samp> will return <samp>null</samp> 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>

</ol>

===Save data===

===Save data===

You can store arbitrary data in the current save file. This is mainly useful for save-specific data, like player progression and custom items. This is subject to some restrictions: the save file must be loaded (e.g. it won't work on the title screen), it can't be used by farmhands in multiplayer (you can [[Modding:Modder Guide/APIs/Utilities#Context|check <tt>Context.IsMainPlayer</tt>]]), and it'll be discarded if the player exits without saving. If the data needs to be prepared prior to saving, the [[Modding:Modder Guide/APIs/Events#GameLoop.Saving|<tt>GameLoop.Saving</tt> event]] is a good time to do it.

You can store arbitrary data in the current save file. This is mainly useful for save-specific data, like player progression and custom items. This is subject to some restrictions: the save file must be loaded (e.g. it won't work on the title screen), it can't be used by farmhands in multiplayer (you can [[Modding:Modder Guide/APIs/Utilities#Context|check <samp>Context.IsMainPlayer</samp>]]), and it'll be discarded if the player exits without saving. If the data needs to be prepared prior to saving, the [[Modding:Modder Guide/APIs/Events#GameLoop.Saving|<samp>GameLoop.Saving</samp> event]] is a good time to do it.

<ol>

<ol>

<li>[[#Data model|Create your data model]].</li>

<li>[[#Data model|Create your data model]].</li>

<li>[[#Data key|Choose your data key]].</li>

<li>[[#Data key|Choose your data key]].</li>

<li>In your mod code, use the data API to read/write a named entry. This example assumes your data model is <tt>ModData</tt> and your key is <tt>example-key</tt>, but you can use different values.

<li>In your mod code, use the data API to read/write a named entry. This example assumes your data model is <samp>ModData</samp> and your key is <samp>example-key</samp>, but you can use different values.

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

</syntaxhighlight>

</syntaxhighlight>

Note that <tt>ReadSaveData</tt> will return <tt>null</tt> if the data doesn't exist.</li>

Note that <samp>ReadSaveData</samp> will return <samp>null</samp> if the data doesn't exist.</li>

</ol>

</ol>

<li>[[#Data model|Create your data model]].</li>

<li>[[#Data model|Create your data model]].</li>

<li>[[#Data key|Choose your data key]].</li>

<li>[[#Data key|Choose your data key]].</li>

<li>In your mod code, use the data API to read/write a named entry. This example assumes your data model is <tt>ModData</tt> and your key is <tt>example-key</tt>, but you can use different values.

<li>In your mod code, use the data API to read/write a named entry. This example assumes your data model is <samp>ModData</samp> and your key is <samp>example-key</samp>, but you can use different values.

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

</syntaxhighlight>

</syntaxhighlight>

Note that <tt>ReadGlobalData</tt> will return <tt>null</tt> if the data doesn't exist.</li>

Note that <samp>ReadGlobalData</samp> will return <samp>null</samp> if the data doesn't exist.</li>

</ol>

</ol>

==Deletion==

==Deletion==

To remove an entry or file, just pass <code>null</code> as the data model. This works with any of the <tt>Write*</tt> methods except <tt>WriteJsonFile</tt> ({{SMAPI upcoming|3.13.0|inline=1|fixed}}):

To remove an entry or file, just pass <code>null</code> as the data model. This works with any of the <samp>Write*</samp> methods except <samp>WriteJsonFile</samp> ({{SMAPI upcoming|3.13.0|inline=1|fixed}}):

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

// delete entry (if present)

// delete entry (if present)

this.Helper.Data.WriteSaveData<DataModel>("example-key", null);

this.Helper.Data.WriteSaveData<DataModel>("example-key", null);

</syntaxhighlight>

</syntaxhighlight>