Modding:Modder Guide/APIs/Content
Creating SMAPI mods 
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
The content API lets you read custom assets, or read/edit/replace game assets.
Intro
What's an 'asset'?
An asset is one image, map, or data structure provided to the game. The game stores its default assets in its Content folder, though mods can have custom assets too. For example, all of Abigail's portraits are stored in one asset inside Content\Portraits\Abigail.xnb. If you unpack that file, you'll see it contains an image file:
See Editing XNB files for more info about asset files.
What's an 'asset name'?
An asset name identifies an asset. For a Content file, this is the file path relative to Content without the .xnb extension or language. For example, Content\Maps\Desert.xnb and Content\Maps\Desert.ja-JA.xnb both have asset name Maps\Desert.
What does the content API do?
SMAPI handles content loading for the game. This lets you...
- read images or maps from your mod folder (with support for .xnb, .png, and .tbin files);
- read assets from the game's Content folder;
- make changes to game assets (without changing the actual files);
- provide new assets to the game.
The rest of this page explains each one in more detail.
Read assets
Read mod assets
You can read custom assets from your mod folder by specifying its path (relative to your mod folder) and type. For example:
// read an image file
Texture2D texture = helper.Content.Load<Texture2D>("assets/texture.png", ContentSource.ModFolder);
// read a map file
Map map = helper.Content.Load<Map>("assets/map.tbin", ContentSource.ModFolder);
// read a data file
IDictionary<string, string> data = helper.Content.Load<Dictionary<string, string>>("assets/data.json", ContentSource.ModFolder);
The supported file types are...
| file extension | in-game type | notes |
|---|---|---|
| .xnb | any | A packed file, like those in the game's Content folder. Not recommended since it's harder to edit and maintain. |
| .json | any | A data file, typically used to store Dictionary<int, string> or Dictionary<string, string> data. |
| .png | Texture2D | An image file. You can use this to load textures, spritesheets, tilesheets, etc. |
| .tbin | xTile.Map | A map file, which can be used to create or modify an in-game location. SMAPI will automatically match tilesheets to image files in the same folder as the map if they exist; otherwise the game will check the Content folders for them. |
Some usage notes:
- The normal convention is to have them in an assets subfolder, though that's not required.
- Don't worry about which path separators you use; SMAPI will normalise them automatically.
- To avoid performance issues, don't call content.Load<T> repeatedly in draw code. Instead, load your asset once and reuse it.
Get actual mod asset keys
When you load an asset from your mod folder, SMAPI stores it with an asset name that uniquely identifies it. If you need to pass the asset name to game code, you can retrieve the actual asset name:
tilesheet.ImageSource = helper.Content.GetActualAssetKey("assets/tilesheet.png", ContentSource.ModFolder);
Read content assets
You can also read assets from the game folder:
Texture2D portraits = helper.Content.Load<Texture2D>("Portraits/Abigail", ContentSource.GameContent);
Note that this requires the asset name, not a filename. You can get the asset name by taking the path relative to the Content folder, and removing the language code and .xnb extension. See #What's an 'asset'?.
Edit the game's assets
Edit an asset after it's loaded
You can edit any of the game's assets after it's loaded from the file (but before it's provided to the game), without changing the original files. You do this by implementing IAssetEditor in your Mod class, which adds two methods: CanEdit<T> returns whether the mod can edit a particular asset, and Edit<T> makes any changes needed. SMAPI will call your CanEdit<T> every time an asset is loaded (which may happen multiple times per asset), then call Edit<T> if it returns true.
For example, here's a mod which makes crops grow in any season and changes the winter dirt texture.
public class ModEntry : Mod, IAssetEditor
{
/// <summary>Get whether this instance can edit the given asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public bool CanEdit<T>(IAssetInfo asset)
{
// change crop seasons
if (asset.AssetNameEquals("Data/Crops"))
{
return true;
}
// change dirt texture
if (asset.AssetNameEquals("TerrainFeatures/hoeDirtSnow"))
{
return true;
}
return false;
}
/// <summary>Edit a matched asset.</summary>
/// <param name="asset">A helper which encapsulates metadata about an asset and enables changes to it.</param>
public void Edit<T>(IAssetData asset)
{
// change crop seasons
if (asset.AssetNameEquals("Data/Crops"))
{
IDictionary<int, string> data = asset.AsDictionary<int, string>().Data;
foreach (int cropID in data.Keys)
{
string[] fields = data[cropID].Split('/');
fields[1] = "spring summer fall winter";
data[cropID] = string.Join("/", fields);
}
}
// change dirt texture
else if (asset.AssetNameEquals("TerrainFeatures/hoeDirtSnow"))
{
asset.ReplaceWith(this.Helper.Content.Load<Texture2D>("TerrainFeatures/hoeDirt", ContentSource.GameContent));
}
}
}
The IAssetData asset argument your Edit method receives has some helpers to make editing data easier.
- The above example uses asset.AsDictionary<int, string>().Set(...) to make changes to each entry in the dictionary.
- The above example also uses asset.ReplaceWith to replace the entire asset with a new version. (Usually you shouldn't do that though; see Replace an asset entirely below.
- You can retrieve the underlying data to change it:
public void Edit<T>(IAssetData asset) { IDictionary<int, string> crops = asset.AsDictionary<int, string>().Data; crops[999] = "... some new crop string ..."; }
- You can paste a custom image into a texture being loaded (e.g. to replace one sprite):
public void Edit<T>(IAssetData asset) { Texture2D customTexture = this.Helper.Content.Load<Texture2D>("custom-texture.png", ContentSource.ModFolder); asset .AsImage() .PatchImage(customTexture, targetArea: new Rectangle(300, 100, 200, 200)); }
See IntelliSense for the asset argument for more info.
Replace an asset entirely
Sometimes you may need to replace an asset entirely (without changing the original file), not just edit it after it's loaded. In other words, you're providing the asset to SMAPI yourself so the original file won't be read at all. Note that two mods can't both provide the same asset.
You can do this by implementing IAssetLoader in your Mod class. This adds two methods: CanLoad<T> returns whether the mod can provide a particular asset, and Load<T> provides the asset data. SMAPI will call your CanLoad<T> every time an asset is loaded (which may happen multiple times per asset), then call Load<T> if it returns true. (If multiple mods return true from CanLoad<T> for the same asset, SMAPI will display an error and not call Load<T> for any of them.)
For example, here's a mod which replaces Abigail's portraits with a custom version from its mod folder:
public class ModEntry : Mod, IAssetLoader
{
/// <summary>Get whether this instance can load the initial version of the given asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public bool CanLoad<T>(IAssetInfo asset)
{
if (asset.AssetNameEquals("Portraits/Abigail"))
{
return true;
}
return false;
}
/// <summary>Load a matched asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public T Load<T>(IAssetInfo asset)
{
if (asset.AssetNameEquals("Portraits/Abigail"))
{
return this.Helper.Content.Load<T>("assets/abigail-portaits.png", ContentSource.ModFolder);
}
throw new InvalidOperationException($"Unexpected asset '{asset.AssetName}'.");
}
}
Replace a map file
You can use IAssetLoader to load custom maps too. When you load an unpacked .tbin map file, and an unpacked tilesheet is present in the mod folder (relative to the map file), SMAPI will automatically link the map to that file and handle loading it too. If the tilesheet name starts with a season and underscore, SMAPI patches the game's seasonal logic to seasonalise it too.
For example, let's say you have a mod with this structure:
ExampleMapMod.dll manifest.json assets/ Farm.tbin fall_customTilesheet.png spring_customTilesheet.png summer_customTilesheet.png winter_customTilesheet.png
You can load the custom map like this:
public class ModEntry : Mod, IAssetLoader
{
/// <summary>Get whether this instance can load the initial version of the given asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public bool CanLoad<T>(IAssetInfo asset)
{
return asset.AssetNameEquals("Maps/Farm");
}
/// <summary>Load a matched asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public T Load<T>(IAssetInfo asset)
{
return this.Helper.Content.Load<T>("assets/Farm.tbin");
}
}
That's it! SMAPI will detect a reference to spring_customTilesheet.png, find the file relative to the map file, and load it too. When the season changes in-game, SMAPI will automatically switch it to summer_customTilesheet.png, etc. The other tilesheet references will be left untouched (since there's no local file), and use the Content files.
Add a new asset
Providing a new asset is exactly like replacing an existing one (see previous section). For example, this code adds a new dialogue file for a custom NPC:
public class ModEntry : Mod, IAssetLoader
{
/// <summary>Get whether this instance can load the initial version of the given asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public bool CanLoad<T>(IAssetInfo asset)
{
return asset.AssetNameEquals("Characters/Dialogue/John");
}
/// <summary>Load a matched asset.</summary>
/// <param name="asset">Basic metadata about the asset being loaded.</param>
public T Load<T>(IAssetInfo asset)
{
return (T)(object)new Dictionary<string, string> // (T)(object) converts a known type to the generic 'T' placeholder
{
["Introduction"] = "Hi there! My name is Jonathan."
};
}
}
Advanced
Cache invalidation
You can reload an asset by invalidating it from the cache. It will be reloaded next time the game requests it (and mods will have another chance to intercept it), and SMAPI will automatically update references to the asset in many cases. For example, this lets you change what clothes an NPC is wearing (by invalidating their cached sprites or portraits).
Reloading assets is fairly expensive, so use this API judiciously to avoid impacting game performance. Definitely don't do this every update tick.
Typically you'll invalidate a specific asset key:
helper.Content.InvalidateCache("Data/ObjectInformation");
You can also invalidate assets matching a lambda:
helper.Content.InvalidateCache(asset => asset.DataType == typeof(Texture2D) && asset.AssetNameEquals(@"Data\ObjectInformation.xnb"));
Create separate asset editors/loaders
All the examples above say to implement IAssetEditor or IAssetLoader directly on your mod class. That's fine in the vast majority of cases, but you can also provide separate instances instead:
public class ModEntry : Mod
{
/// <summary>The mod entry point, called after the mod is first loaded.</summary>
/// <param name="helper">Provides simplified APIs for writing mods.</param>
public override void Entry(IModHelper helper)
{
helper.Content.AssetEditors.Add(new MyCropEditor());
helper.Content.AssetLoaders.Add(new MyDialogueLoader());
}
}
When you add or remove an asset editor/loader, SMAPI will call their CanEdit and CanLoad methods for all loaded assets and reload matched assets. This is an expensive process when done outside your Entry method, so avoid adding editors/loaders unnecessarily.