Modding:Modder Guide/APIs
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
SMAPI provides a number of APIs for mods to use. Click a section on the right or below for more details.
Basic APIs
page | summary |
---|---|
Manifest | A file needed for every mod or content pack which describes the mod, lists dependencies, enables update checks, etc. |
Events | Respond when something happens in the game (e.g. when a save is loaded), and often include details about what happened. |
Mod configuration | Let players edit a config.json file to configure your mod. |
Content | Load images/maps/data, and edit or replace the game's images/maps/data. |
Logging | Write messages to the SMAPI console and log. |
Reflection | Access fields, properties, or methods which are normally inaccessible. |
Multiplayer | Provides methods for supporting multiplayer. |
Translation | Translate your mod text into any game language. |
Utilities | Use constants, contextual information, date logic, and semantic versions. |
Advanced APIs
page | summary |
---|---|
Content packs | Let other modders provide files for your mod to read, which players can install like any other mod. |
Console commands | Add custom commands to the SMAPI console. |
Mod integrations | Get information about loaded mods, and integrate with mods using mod-provided APIs. |
Mod APIs
Logging
Your mod can write messages to the console window and log file using the monitor. For example, this code:
this.Monitor.Log("a trace message", LogLevel.Trace);
this.Monitor.Log("a debug message", LogLevel.Debug);
this.Monitor.Log("an info message", LogLevel.Info);
this.Monitor.Log("a warning message", LogLevel.Warn);
this.Monitor.Log("an error message", LogLevel.Error);
will log something like this:
[18:00:00 TRACE Mod Name] a trace message
[18:00:00 DEBUG Mod Name] a debug message
[18:00:00 INFO Mod Name] an info message
[18:00:00 WARN Mod Name] a warning message
[18:00:00 ERROR Mod Name] an error message
Note that LogLevel.Trace messages won't appear in the console window by default, they'll only be written to the log file. Trace messages are for troubleshooting details that are useful when someone sends you their error log, but which the player normally doesn't need to see. (You can see trace messages in the console if you install the "SMAPI for developers" version.)
Reflection
SMAPI provides an API for robustly accessing fields, properties, or methods you otherwise couldn't access, such as private fields. You can use it from helper.Reflection in your entry method, or this.Helper.Reflection elsewhere in your entry class.
Here are a few examples of what this lets you do:
// did you pet your pet today?
bool wasPet = this.Helper.Reflection.GetField<bool>(pet, "wasPetToday").GetValue();
// what is the spirit forecast today?
string forecast = this.Helper.Reflection
.GetMethod(new TV(), "getFortuneForecast")
.Invoke<string>();
// randomise the mines
if(Game1.currentLocation is MineShaft)
this.Helper.Reflection.GetField<Random>(Game1.currentLocation, "mineRandom").SetValue(new Random());
This works with static or instance fields/methods, caches the reflection to improve performance, and will throw useful errors automatically when reflection fails.
If you need to do more, you can switch to C#'s underlying reflection API:
FieldInfo field = this.Helper.Reflection.GetField<string>(…).FieldInfo;
MethodInfo method = this.Helper.Reflection.GetMethod(…).MethodInfo;
Multiplayer
The multiplayer API provides methods to support modding in a multiplayer context:
// get a unique multiplayer ID (e.g. for animal IDs)
int uniqueID = this.Helper.Multiplayer.GetNewID();
// get the locations being sync'd from the main player
foreach (GameLocation location in this.Helper.Multiplayer.GetActiveLocations())