114
edits
Changes
Modding:Modder Guide/APIs/Data (view source)
Revision as of 18:22, 19 February 2021
, 18:22, 19 February 2021Replace deprecated <source> tags with <syntaxhighlight> tags
<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 <tt>ModData</tt>, but you can use different names too.
<source lang="c#">
<syntaxhighlight lang="c#">
// read file
// read file
var model = this.Helper.Data.ReadJsonFile<ModData>("data.json") ?? new ModData();
var model = this.Helper.Data.ReadJsonFile<ModData>("data.json") ?? new ModData();
// save file (if needed)
// save file (if needed)
this.Helper.Data.WriteJsonFile("data.json", model);
this.Helper.Data.WriteJsonFile("data.json", model);
</source>
</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 <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>
<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 <tt>ModData</tt> and your key is <tt>example-key</tt>, but you can use different values.
<source lang="c#">
<syntaxhighlight lang="c#">
// read file
// read file
var model = this.Helper.Data.ReadSaveData<ModData>("example-key");
var model = this.Helper.Data.ReadSaveData<ModData>("example-key");
// save file (if needed)
// save file (if needed)
this.Helper.Data.WriteSaveData("example-key", model);
this.Helper.Data.WriteSaveData("example-key", model);
</source>
</syntaxhighlight>
Note that <tt>ReadSaveData</tt> will return <tt>null</tt> if the data doesn't exist.</li>
Note that <tt>ReadSaveData</tt> will return <tt>null</tt> if the data doesn't exist.</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 <tt>ModData</tt> and your key is <tt>example-key</tt>, but you can use different values.
<source lang="c#">
<syntaxhighlight lang="c#">
// read file
// read file
var model = this.Helper.Data.ReadGlobalData<ModData>("example-key");
var model = this.Helper.Data.ReadGlobalData<ModData>("example-key");
// save file (if needed)
// save file (if needed)
this.Helper.Data.WriteGlobalData("example-key", model);
this.Helper.Data.WriteGlobalData("example-key", model);
</source>
</syntaxhighlight>
Note that <tt>ReadGlobalData</tt> will return <tt>null</tt> if the data doesn't exist.</li>
Note that <tt>ReadGlobalData</tt> will return <tt>null</tt> if the data doesn't exist.</li>
===Creating a data model===
===Creating a data model===
The ''data model'' is a C# class you create, with properties representing the data you want to store. It can contain almost anything from a few boolean fields to a complex object graph. Here's a simple data model:
The ''data model'' is a C# class you create, with properties representing the data you want to store. It can contain almost anything from a few boolean fields to a complex object graph. Here's a simple data model:
<source lang="c#">
<syntaxhighlight lang="c#">
class ModData
class ModData
{
{
public int ExampleNumber { get; set; }
public int ExampleNumber { get; set; }
}
}
</source>
</syntaxhighlight>
If you save that model to a JSON file, the file would look like this:
If you save that model to a JSON file, the file would look like this:
<source lang="json">
<syntaxhighlight lang="json">
{
{
"ExampleBoolean": false,
"ExampleBoolean": false,
"ExampleNumber": 0
"ExampleNumber": 0
}
}
</source>
</syntaxhighlight>
===Default values===
===Default values===
You can optionally set default values in your data model:
You can optionally set default values in your data model:
<source lang="c#">
<syntaxhighlight lang="c#">
class ModData
class ModData
{
{
public int ExampleNumber { get; set; } = 5;
public int ExampleNumber { get; set; } = 5;
}
}
</source>
</syntaxhighlight>
...or set defaults with a constructor:
...or set defaults with a constructor:
<source lang="c#">
<syntaxhighlight lang="c#">
class ModData
class ModData
{
{
}
}
}
}
</source>
</syntaxhighlight>
==Data key==
==Data key==
A ''data key'' identifies your data, which lets you access the data again later. It should be unique within your mod, but there's no need to worry about conflicts with other mods (SMAPI will namespace the key internally). A data key can only contain letters, numbers, underscores, hyphens, or dots.
A ''data key'' identifies your data, which lets you access the data again later. It should be unique within your mod, but there's no need to worry about conflicts with other mods (SMAPI will namespace the key internally). A data key can only contain letters, numbers, underscores, hyphens, or dots.