Modding:Modder Guide/APIs/Content Packs - Revision history

imported>Margotbean: rm underscores, shorten external link

2026-05-21T05:16:42Z

rm underscores, shorten external link

← Older revision		Revision as of 05:16, 21 May 2026
Line 3:		Line 3:
	A '''content pack''' is a special type of mod that isn't run by SMAPI directly, but contains files your own mod can read.		A '''content pack''' is a special type of mod that isn't run by SMAPI directly, but contains files your own mod can read.

	Note that a custom content pack format is not required to provide integration with content mods; the most common method is to provide a [[Modding:~~Modder_Guide~~/APIs/Content#~~Add_a_new_asset~~\|custom game asset]] that other mods (including Content Patcher packs) can edit. The advantage of custom assets is that both other C# mods and Content Patcher packs can edit them via the content pipeline, with the latter benefiting from convenient features such as tokens, conditional loading and targeted edits, removing the need to implement similar features in your mod.		Note that a custom content pack format is not required to provide integration with content mods; the most common method is to provide a [[Modding:Modder Guide/APIs/Content#Add a new asset\|custom game asset]] that other mods (including Content Patcher packs) can edit. The advantage of custom assets is that both other C# mods and Content Patcher packs can edit them via the content pipeline, with the latter benefiting from convenient features such as tokens, conditional loading and targeted edits, removing the need to implement similar features in your mod.

	See the wiki page for [[Modding:~~Modder_Guide~~/APIs/Content\|loading and editing content]], as well as the [https://stardewmodding.wiki.gg/wiki/Tutorial:_Making_Framework_Mods ~~external tutorial for~~ making framework mods] for more info. The rest of this page details instructions for defining custom content packs formats.		See the wiki page for [[Modding:Modder Guide/APIs/Content\|loading and editing content]], as well as the external tutorial for [https://stardewmodding.wiki.gg/wiki/Tutorial:_Making_Framework_Mods making framework mods] for more info. The rest of this page details instructions for defining custom content packs formats.

	__TOC__		__TOC__

imported>Selph: fix link

2026-05-21T02:37:35Z

fix link

← Older revision		Revision as of 02:37, 21 May 2026
Line 5:		Line 5:
	Note that a custom content pack format is not required to provide integration with content mods; the most common method is to provide a [[Modding:Modder_Guide/APIs/Content#Add_a_new_asset\|custom game asset]] that other mods (including Content Patcher packs) can edit. The advantage of custom assets is that both other C# mods and Content Patcher packs can edit them via the content pipeline, with the latter benefiting from convenient features such as tokens, conditional loading and targeted edits, removing the need to implement similar features in your mod.		Note that a custom content pack format is not required to provide integration with content mods; the most common method is to provide a [[Modding:Modder_Guide/APIs/Content#Add_a_new_asset\|custom game asset]] that other mods (including Content Patcher packs) can edit. The advantage of custom assets is that both other C# mods and Content Patcher packs can edit them via the content pipeline, with the latter benefiting from convenient features such as tokens, conditional loading and targeted edits, removing the need to implement similar features in your mod.

	See the wiki page for [[Modding:Modder_Guide/APIs/Content\|loading and editing content]], as well as the [https://stardewmodding.wiki.gg/wiki/Tutorial:_Making_Framework_Mods\|external tutorial for making framework mods] for more info. The rest of this page details instructions for defining custom content packs formats.		See the wiki page for [[Modding:Modder_Guide/APIs/Content\|loading and editing content]], as well as the [https://stardewmodding.wiki.gg/wiki/Tutorial:_Making_Framework_Mods external tutorial for making framework mods] for more info. The rest of this page details instructions for defining custom content packs formats.

	__TOC__		__TOC__

imported>Selph: Add disclaimer that custom game assets should be preferred

2026-05-21T02:36:40Z

Add disclaimer that custom game assets should be preferred

← Older revision		Revision as of 02:36, 21 May 2026
Line 2:		Line 2:

	A '''content pack''' is a special type of mod that isn't run by SMAPI directly, but contains files your own mod can read.		A '''content pack''' is a special type of mod that isn't run by SMAPI directly, but contains files your own mod can read.

			Note that a custom content pack format is not required to provide integration with content mods; the most common method is to provide a [[Modding:Modder_Guide/APIs/Content#Add_a_new_asset\|custom game asset]] that other mods (including Content Patcher packs) can edit. The advantage of custom assets is that both other C# mods and Content Patcher packs can edit them via the content pipeline, with the latter benefiting from convenient features such as tokens, conditional loading and targeted edits, removing the need to implement similar features in your mod.

			See the wiki page for [[Modding:Modder_Guide/APIs/Content\|loading and editing content]], as well as the [https://stardewmodding.wiki.gg/wiki/Tutorial:_Making_Framework_Mods\|external tutorial for making framework mods] for more info. The rest of this page details instructions for defining custom content packs formats.

	__TOC__		__TOC__

imported>Sunbeam135 at 19:28, 9 January 2026

2026-01-09T19:28:28Z

← Older revision		Revision as of 19:28, 9 January 2026
Line 88:		Line 88:
	</syntaxhighlight>		</syntaxhighlight>

			[[ru:Модификации:Руководство мододела/API/Контент-паки]]
	[[zh:模组:制作指南/APIs/Content Packs]]		[[zh:模组:制作指南/APIs/Content Packs]]

imported>VulpesLucida: zh link

2025-01-05T14:33:52Z

zh link

← Older revision		Revision as of 14:33, 5 January 2025
Line 87:		Line 87:
	);		);
	</syntaxhighlight>		</syntaxhighlight>

			[[zh:模组:制作指南/APIs/Content Packs]]

imported>Shekurika: update code example how to asset from content pack

2022-09-12T16:37:19Z

update code example how to asset from content pack

← Older revision		Revision as of 16:37, 12 September 2022
Line 55:		Line 55:
	You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <samp>LoadAsset</samp>. You can optionally specify a relative path to read from a subfolder.		You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <samp>LoadAsset</samp>. You can optionally specify a relative path to read from a subfolder.
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	Texture2D image = contentPack.~~LoadAsset~~<Texture2D>("image.png");		Texture2D image = contentPack.ModContent.Load<Texture2D>("image.png");
	</syntaxhighlight>		</syntaxhighlight>

imported>Margotbean: Text replacement - "tt>" to "samp>"

2021-11-04T18:48:40Z

Text replacement - "tt>" to "samp>"

← Older revision		Revision as of 18:48, 4 November 2021
Line 5:		Line 5:
	__TOC__		__TOC__
	==Content pack format==		==Content pack format==
	A content pack is a folder containing a <tt>manifest.json</tt> file which specifies your mod in its <tt>ContentPackFor</tt> field (see [[../Manifest\|manifest]]). The format beyond that is up to you to define. For example, {{nexus mod\|1915\|Content Patcher}} requires a <tt>content.json</tt> file, but that's not validated by SMAPI itself. Instead, SMAPI provides an API you can use to read any other file you need from the content pack.		A content pack is a folder containing a <samp>manifest.json</samp> file which specifies your mod in its <samp>ContentPackFor</samp> field (see [[../Manifest\|manifest]]). The format beyond that is up to you to define. For example, {{nexus mod\|1915\|Content Patcher}} requires a <samp>content.json</samp> file, but that's not validated by SMAPI itself. Instead, SMAPI provides an API you can use to read any other file you need from the content pack.

	See [[Modding:Content packs]] for more info about content packs.		See [[Modding:Content packs]] for more info about content packs.
Line 11:		Line 11:
	==Content pack API==		==Content pack API==
	===Get owned content packs===		===Get owned content packs===
	To get the content packs installed for your mod (including a <tt>Manifest</tt> field with the content pack's [[Modding:Modder Guide/APIs/Manifest\|full manifest info]]):		To get the content packs installed for your mod (including a <samp>Manifest</samp> field with the content pack's [[Modding:Modder Guide/APIs/Manifest\|full manifest info]]):
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	foreach(IContentPack contentPack in this.Helper.ContentPacks.GetOwned())		foreach(IContentPack contentPack in this.Helper.ContentPacks.GetOwned())
Line 24:		Line 24:

	===Check if a file exists===		===Check if a file exists===
	You can check if a file exists in the content pack folder using <tt>HasFile</tt>. You can specify a relative path like <tt>data/content.json</tt>.		You can check if a file exists in the content pack folder using <samp>HasFile</samp>. You can specify a relative path like <samp>data/content.json</samp>.

	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
Line 36:		Line 36:

	===Read a JSON file===		===Read a JSON file===
	You can read a JSON file from a content pack folder into [[Modding:Modder Guide/APIs/Data#Data model\|a data model]] (<tt>YourDataModel</tt> in the example below) using <tt>ReadJsonFile</tt>. You can specify a relative path like <tt>data/content.json</tt>. This will return <tt>null</tt> if the file doesn't exist.		You can read a JSON file from a content pack folder into [[Modding:Modder Guide/APIs/Data#Data model\|a data model]] (<samp>YourDataModel</samp> in the example below) using <samp>ReadJsonFile</samp>. You can specify a relative path like <samp>data/content.json</samp>. This will return <samp>null</samp> if the file doesn't exist.

	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
Line 43:		Line 43:

	===Write a JSON file===		===Write a JSON file===
	You can write a JSON file in a content pack folder using <tt>WriteJsonFile</tt>, using a [[Modding:Modder Guide/APIs/Data#Data model\|data model]] (<tt>YourDataModel</tt> in the example below). You can specify a relative path like <tt>data/content.json</tt> (subdirectories will be created automatically if needed). This will create the file if it doesn't exist, or overwrite it if it does.		You can write a JSON file in a content pack folder using <samp>WriteJsonFile</samp>, using a [[Modding:Modder Guide/APIs/Data#Data model\|data model]] (<samp>YourDataModel</samp> in the example below). You can specify a relative path like <samp>data/content.json</samp> (subdirectories will be created automatically if needed). This will create the file if it doesn't exist, or overwrite it if it does.

	'''Note:''' this is best used for generated files. Overwriting the original files isn't recommended, since a bug in your mod which changes an original file might permanently break the content pack and require the player to reinstall it.		'''Note:''' this is best used for generated files. Overwriting the original files isn't recommended, since a bug in your mod which changes an original file might permanently break the content pack and require the player to reinstall it.
Line 53:		Line 53:

	===Read content asset===		===Read content asset===
	You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <tt>LoadAsset</tt>. You can optionally specify a relative path to read from a subfolder.		You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <samp>LoadAsset</samp>. You can optionally specify a relative path to read from a subfolder.
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	Texture2D image = contentPack.LoadAsset<Texture2D>("image.png");		Texture2D image = contentPack.LoadAsset<Texture2D>("image.png");
	</syntaxhighlight>		</syntaxhighlight>

	If you need to pass an asset name to game code, you can use the <tt>GetActualAssetKey</tt> method:		If you need to pass an asset name to game code, you can use the <samp>GetActualAssetKey</samp> method:
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	tilesheet.ImageSource = contentPack.GetActualAssetKey("image.png");		tilesheet.ImageSource = contentPack.GetActualAssetKey("image.png");
Line 64:		Line 64:

	===Get translations===		===Get translations===
	You can read translations from the content pack's <tt>i18n</tt> folder. This is identical to the [[Modding:Modder Guide/APIs/Translation\|translation API]], but accessed through <tt>contentPack.Translations</tt>:		You can read translations from the content pack's <samp>i18n</samp> folder. This is identical to the [[Modding:Modder Guide/APIs/Translation\|translation API]], but accessed through <samp>contentPack.Translations</samp>:
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	string text = contentPack.Translation.Get("item-type.label");		string text = contentPack.Translation.Get("item-type.label");

imported>Pathoschild: /* Create a fake content pack */ update example

2021-07-06T04:37:56Z

Create a fake content pack: update example

← Older revision		Revision as of 04:37, 6 July 2021
Line 78:		Line 78:

	// create with given manifest fields		// create with given manifest fields
	IContentPack contentPack = this.Helper.ContentPacks.~~CreateFake~~(		IContentPack contentPack = this.Helper.ContentPacks.CreateTemporary(
	directoryPath: Path.Combine(this.Helper.DirectoryPath, "content-pack"),		directoryPath: Path.Combine(this.Helper.DirectoryPath, "content-pack"),
	id: Guid.NewGuid().ToString("N"),		id: Guid.NewGuid().ToString("N"),

imported>RetroEdit: Replace deprecated tags with tags

2021-02-19T18:21:27Z

Replace deprecated <source> tags with <syntaxhighlight> tags

← Older revision		Revision as of 18:21, 19 February 2021
Line 12:		Line 12:
	===Get owned content packs===		===Get owned content packs===
	To get the content packs installed for your mod (including a <tt>Manifest</tt> field with the content pack's [[Modding:Modder Guide/APIs/Manifest\|full manifest info]]):		To get the content packs installed for your mod (including a <tt>Manifest</tt> field with the content pack's [[Modding:Modder Guide/APIs/Manifest\|full manifest info]]):
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	foreach(IContentPack contentPack in this.Helper.ContentPacks.GetOwned())		foreach(IContentPack contentPack in this.Helper.ContentPacks.GetOwned())
	{		{
	this.Monitor.Log($"Reading content pack: {contentPack.Manifest.Name} {contentPack.Manifest.Version} from {contentPack.DirectoryPath}");		this.Monitor.Log($"Reading content pack: {contentPack.Manifest.Name} {contentPack.Manifest.Version} from {contentPack.DirectoryPath}");
	}		}
	</~~source~~>		</syntaxhighlight>

	Content packs are listed in load order, so they're already sorted for dependencies. For example, if content pack B requires A, they'll be listed in the order A → B.		Content packs are listed in load order, so they're already sorted for dependencies. For example, if content pack B requires A, they'll be listed in the order A → B.
Line 26:		Line 26:
	You can check if a file exists in the content pack folder using <tt>HasFile</tt>. You can specify a relative path like <tt>data/content.json</tt>.		You can check if a file exists in the content pack folder using <tt>HasFile</tt>. You can specify a relative path like <tt>data/content.json</tt>.

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	if (!contentPack.HasFile("content.json"))		if (!contentPack.HasFile("content.json"))
	{		{
	// show 'required file missing' error		// show 'required file missing' error
	}		}
	</~~source~~>		</syntaxhighlight>

	It is often a good idea to alert the player (and modders who may be using your mod) if the file is missing on deployment.		It is often a good idea to alert the player (and modders who may be using your mod) if the file is missing on deployment.
Line 38:		Line 38:
	You can read a JSON file from a content pack folder into [[Modding:Modder Guide/APIs/Data#Data model\|a data model]] (<tt>YourDataModel</tt> in the example below) using <tt>ReadJsonFile</tt>. You can specify a relative path like <tt>data/content.json</tt>. This will return <tt>null</tt> if the file doesn't exist.		You can read a JSON file from a content pack folder into [[Modding:Modder Guide/APIs/Data#Data model\|a data model]] (<tt>YourDataModel</tt> in the example below) using <tt>ReadJsonFile</tt>. You can specify a relative path like <tt>data/content.json</tt>. This will return <tt>null</tt> if the file doesn't exist.

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	YourDataModel data = contentPack.ReadJsonFile<YourDataFile>("content.json");		YourDataModel data = contentPack.ReadJsonFile<YourDataFile>("content.json");
	</~~source~~>		</syntaxhighlight>

	===Write a JSON file===		===Write a JSON file===
Line 47:		Line 47:
	'''Note:''' this is best used for generated files. Overwriting the original files isn't recommended, since a bug in your mod which changes an original file might permanently break the content pack and require the player to reinstall it.		'''Note:''' this is best used for generated files. Overwriting the original files isn't recommended, since a bug in your mod which changes an original file might permanently break the content pack and require the player to reinstall it.

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	YourDataModel data = new YourDataModel();		YourDataModel data = new YourDataModel();
	contentPack.WriteJsonFile("content.json", data);		contentPack.WriteJsonFile("content.json", data);
	</~~source~~>		</syntaxhighlight>

	===Read content asset===		===Read content asset===
	You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <tt>LoadAsset</tt>. You can optionally specify a relative path to read from a subfolder.		You can read [[Modding:Modder Guide/APIs/Content\|a content asset]] from the content pack folder using <tt>LoadAsset</tt>. You can optionally specify a relative path to read from a subfolder.
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	Texture2D image = contentPack.LoadAsset<Texture2D>("image.png");		Texture2D image = contentPack.LoadAsset<Texture2D>("image.png");
	</~~source~~>		</syntaxhighlight>

	If you need to pass an asset name to game code, you can use the <tt>GetActualAssetKey</tt> method:		If you need to pass an asset name to game code, you can use the <tt>GetActualAssetKey</tt> method:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	tilesheet.ImageSource = contentPack.GetActualAssetKey("image.png");		tilesheet.ImageSource = contentPack.GetActualAssetKey("image.png");
	</~~source~~>		</syntaxhighlight>

	===Get translations===		===Get translations===
	You can read translations from the content pack's <tt>i18n</tt> folder. This is identical to the [[Modding:Modder Guide/APIs/Translation\|translation API]], but accessed through <tt>contentPack.Translations</tt>:		You can read translations from the content pack's <tt>i18n</tt> folder. This is identical to the [[Modding:Modder Guide/APIs/Translation\|translation API]], but accessed through <tt>contentPack.Translations</tt>:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	string text = contentPack.Translation.Get("item-type.label");		string text = contentPack.Translation.Get("item-type.label");
	</~~source~~>		</syntaxhighlight>

	===Create a fake content pack===		===Create a fake content pack===
	In specialised cases, you can create a temporary content pack for a given directory path:		In specialised cases, you can create a temporary content pack for a given directory path:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	// create with random manifest data		// create with random manifest data
	IContentPack contentPack = this.Helper.ContentPacks.CreateFake(		IContentPack contentPack = this.Helper.ContentPacks.CreateFake(
Line 86:		Line 86:
	version: new SemanticVersion(1, 0, 0)		version: new SemanticVersion(1, 0, 0)
	);		);
	</~~source~~>		</syntaxhighlight>

imported>KNakamura: some additions and tips

2020-03-07T11:04:23Z

some additions and tips

← Older revision		Revision as of 11:04, 7 March 2020
Line 20:		Line 20:

	Content packs are listed in load order, so they're already sorted for dependencies. For example, if content pack B requires A, they'll be listed in the order A → B.		Content packs are listed in load order, so they're already sorted for dependencies. For example, if content pack B requires A, they'll be listed in the order A → B.

			As a note, this can be done as early as ModEntry, although mods often choose to perform this step in the GameLoad or SaveLoaded event.

	===Check if a file exists===		===Check if a file exists===
Line 30:		Line 32:
	}		}
	</source>		</source>

			It is often a good idea to alert the player (and modders who may be using your mod) if the file is missing on deployment.

	===Read a JSON file===		===Read a JSON file===