Difference between revisions of "Modding:Modder Guide/APIs/Data"
Margotbean (talk | contribs) m (Text replacement - "tt>" to "samp>") |
Margotbean (talk | contribs) m (Text replacement - "(e.g. " to "(''e.g.'', ") |
||
Line 5: | Line 5: | ||
==Storage options== | ==Storage options== | ||
===JSON files=== | ===JSON files=== | ||
− | 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. | + | 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> | ||
Line 27: | Line 27: | ||
===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 <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. | + | 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> |
Revision as of 23:41, 7 November 2021
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
The data API lets you store arbitrary data and retrieve it later. For example, you can use this to store player progression, custom items that can't be saved by the game, etc.
Storage options
JSON files
You can store data in arbitrary .json 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.
- Create your data model.
- In your mod code, use the mod helper to read/write a named file. This example assumes you created a class named ModData, but you can use different names too.
Note that ReadJsonFile will return null 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
// read file var model = this.Helper.Data.ReadJsonFile<ModData>("data.json") ?? new ModData(); // save file (if needed) this.Helper.Data.WriteJsonFile("data.json", model);
?? new ModData()
part.
By changing the file path you specify, you can...
- store JSON files in a subfolder, by specifying a path relative to your mod folder (like
"data/some-file.json"
). SMAPI will create the folders automatically if needed. - create per-save JSON files by using the save ID in the name, like
$"data/{Constants.SaveFolderName}.json"
.
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 check Context.IsMainPlayer), and it'll be discarded if the player exits without saving. If the data needs to be prepared prior to saving, the GameLoop.Saving event is a good time to do it.
- Create your data model.
- Choose your data key.
- In your mod code, use the data API to read/write a named entry. This example assumes your data model is ModData and your key is example-key, but you can use different values.
Note that ReadSaveData will return null if the data doesn't exist.
// read data var model = this.Helper.Data.ReadSaveData<ModData>("example-key"); // save data (if needed) this.Helper.Data.WriteSaveData("example-key", model);
Global app data
You can store arbitrary data on the local computer, synchronised by GOG/Steam if applicable. This data is global (not per-save) and changes are saved immediately.
- Create your data model.
- Choose your data key.
- In your mod code, use the data API to read/write a named entry. This example assumes your data model is ModData and your key is example-key, but you can use different values.
Note that ReadGlobalData will return null if the data doesn't exist.
// read data var model = this.Helper.Data.ReadGlobalData<ModData>("example-key"); // save data (if needed) this.Helper.Data.WriteGlobalData("example-key", model);
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:
class ModData
{
public bool ExampleBoolean { get; set; }
public int ExampleNumber { get; set; }
}
If you save that model to a JSON file, the file would look like this:
{
"ExampleBoolean": false,
"ExampleNumber": 0
}
Default values
You can optionally set default values in your data model:
class ModData
{
public bool ExampleBoolean { get; set; } = true;
public int ExampleNumber { get; set; } = 5;
}
...or set defaults with a constructor:
class ModData
{
public bool ExampleBoolean { get; set; }
public int ExampleNumber { get; set; }
public ModData()
{
this.ExampleBoolean = true;
this.ExampleNumber = 5;
}
}
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.
Deletion
To remove an entry or file, just pass null
as the data model. This works with any of the Write* methods except WriteJsonFile (As of the upcoming SMAPI 3.13.0: fixed):
// delete entry (if present)
this.Helper.Data.WriteSaveData<DataModel>("example-key", null);