Modding:Modder Guide/APIs/Integrations - Revision history

imported>MagneticJungle: Fix typo with samp tag

2026-08-02T17:17:51Z

Fix typo with samp tag

← Older revision		Revision as of 17:17, 2 August 2026
Line 99:		Line 99:
	Notes:		Notes:
	* You can't call <samp>GetApi</samp> until all mods are initialised and their <samp>Entry</samp> methods called. You can use the <samp>GameLoop.GameLaunched</samp> [[#Events\|event]] if you need to access mod APIs early; this is guaranteed to happen after all mods are initialised.		* You can't call <samp>GetApi</samp> until all mods are initialised and their <samp>Entry</samp> methods called. You can use the <samp>GameLoop.GameLaunched</samp> [[#Events\|event]] if you need to access mod APIs early; this is guaranteed to happen after all mods are initialised.
	* You should always null-check APIs you consume. <samp>GetApi</samp> will return <samp>null</samp> if the API isn't available (''e.g.,'' because the mod isn't already installed or doesn't have one). If <samp>~~GetAPi~~</~~smap~~> cannot map an API, it will throw an exception.		* You should always null-check APIs you consume. <samp>GetApi</samp> will return <samp>null</samp> if the API isn't available (''e.g.,'' because the mod isn't already installed or doesn't have one). If <samp>GetApi</samp> cannot map an API, it will throw an exception.
	* Keep in mind that mods may change their API interfaces over time; it may be useful to check the version of the other mod before trying to map the interface.		* Keep in mind that mods may change their API interfaces over time; it may be useful to check the version of the other mod before trying to map the interface.

imported>Sunbeam135 at 19:39, 9 January 2026

2026-01-09T19:39:50Z

← Older revision		Revision as of 19:39, 9 January 2026
Line 127:		Line 127:
	Make sure the path to <samp>ContentPatcher.dll</samp> is correct on your own installation.		Make sure the path to <samp>ContentPatcher.dll</samp> is correct on your own installation.

			[[ru:Модификации:Руководство мододела/API/Интеграции]]
	[[zh:模组:制作指南/APIs/Integrations]]		[[zh:模组:制作指南/APIs/Integrations]]

imported>VulpesLucida: zh link

2025-01-05T14:34:35Z

zh link

← Older revision		Revision as of 14:34, 5 January 2025
Line 126:		Line 126:

	Make sure the path to <samp>ContentPatcher.dll</samp> is correct on your own installation.		Make sure the path to <samp>ContentPatcher.dll</samp> is correct on your own installation.

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

imported>Selph at 23:20, 26 October 2024

2024-10-26T23:20:08Z

← Older revision		Revision as of 23:20, 26 October 2024
Line 117:		Line 117:
	You can add a reference to a mod's assembly in your <samp>csproj</samp> and directly import its namespaces and functions into your mod code. Note that this should only be attempted if what you want isn't available through the mod's public API, or if this is the target mod's intended method of exposing its own. This would also make said mod a hard dependency for your own mod.		You can add a reference to a mod's assembly in your <samp>csproj</samp> and directly import its namespaces and functions into your mod code. Note that this should only be attempted if what you want isn't available through the mod's public API, or if this is the target mod's intended method of exposing its own. This would also make said mod a hard dependency for your own mod.

	For example, this snippet ~~in your~~ adds an assembly reference to Content Patcher's assembly in your mod code under the <samp>ContentPatcher</samp> namespace, without also including <samp>ContentPatcher.dll</samp> in your mod build:		For example, this snippet adds an assembly reference to Content Patcher's assembly in your mod code under the <samp>ContentPatcher</samp> namespace, without also including <samp>ContentPatcher.dll</samp> in your mod build:

	<syntaxhighlight lang="xml">		<syntaxhighlight lang="xml">

imported>Selph: Add Shared assembly reference

2024-10-26T23:17:03Z

Add Shared assembly reference

← Older revision		Revision as of 23:17, 26 October 2024
Line 111:		Line 111:
	* Request something from a host mod. (Tractor Mod uses this to summon a tractor to the current player in multiplayer, even if the tractor isn't in a location synced to that player.)		* Request something from a host mod. (Tractor Mod uses this to summon a tractor to the current player in multiplayer, even if the tractor isn't in a location synced to that player.)
	* Notify another mod about something. (Chests Anywhere uses this to notify Automate when a chest's automation options are edited.)		* Notify another mod about something. (Chests Anywhere uses this to notify Automate when a chest's automation options are edited.)

			==Shared assembly reference==
			''NOTE'': This is not a SMAPI feature, but this is documented here since it is also a common pattern for providing mod integration.

			You can add a reference to a mod's assembly in your <samp>csproj</samp> and directly import its namespaces and functions into your mod code. Note that this should only be attempted if what you want isn't available through the mod's public API, or if this is the target mod's intended method of exposing its own. This would also make said mod a hard dependency for your own mod.

			For example, this snippet in your adds an assembly reference to Content Patcher's assembly in your mod code under the <samp>ContentPatcher</samp> namespace, without also including <samp>ContentPatcher.dll</samp> in your mod build:

			<syntaxhighlight lang="xml">
			<ItemGroup>
			<Reference Include="ContentPatcher" HintPath="$(GamePath)\Mods\ContentPatcher\ContentPatcher.dll" Private="false" />
			</ItemGroup>
			</syntaxhighlight>

			Make sure the path to <samp>ContentPatcher.dll</samp> is correct on your own installation.

imported>Atravita: /* Using an API */

2022-11-26T19:53:47Z

Using an API

← Older revision		Revision as of 19:53, 26 November 2022
Line 75:		Line 75:
	You can use a mod-provided API by mapping it to an [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/interface interface]:		You can use a mod-provided API by mapping it to an [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/interface interface]:
	<ol>		<ol>
	<li>Create an interface with only the properties and methods you want to access. (If you directly reference the mod DLL and it provides a public API interface, you can use that instead.)		<li>Create an interface with only the properties and methods you want to access. This interface must be public and cannot be an inner interface. (If you directly reference the mod DLL and it provides a public API interface, you can use that instead.)
	<syntaxhighlight lang="C#">		<syntaxhighlight lang="C#">
	public interface ISomeModApi		public interface ISomeModApi

imported>Atravita: /* Known limitations */ no longer a limitation

2022-11-25T15:45:03Z

Known limitations: no longer a limitation

← Older revision		Revision as of 15:45, 25 November 2022
Line 104:		Line 104:
	===Known limitations===		===Known limitations===
	* When providing an API, the interface and implementation must be public.		* When providing an API, the interface and implementation must be public.
	* When mapping an API to a custom interface using <samp>GetApi<T></samp> (''i.e.,'' not using the mod's original interface), only the API interface itself can be proxied. Method return values and parameters must be types that both mods have access to (''e.g.,'' built-in types like <samp>bool</samp>, SMAPI types like <samp>IManifest</samp>, or game types like <samp>GameLocation</samp>).

	==Message sending==		==Message sending==

imported>Atravita: /* Using an API */

2022-11-25T15:44:38Z

Using an API

← Older revision		Revision as of 15:44, 25 November 2022
Line 99:		Line 99:
	Notes:		Notes:
	* You can't call <samp>GetApi</samp> until all mods are initialised and their <samp>Entry</samp> methods called. You can use the <samp>GameLoop.GameLaunched</samp> [[#Events\|event]] if you need to access mod APIs early; this is guaranteed to happen after all mods are initialised.		* You can't call <samp>GetApi</samp> until all mods are initialised and their <samp>Entry</samp> methods called. You can use the <samp>GameLoop.GameLaunched</samp> [[#Events\|event]] if you need to access mod APIs early; this is guaranteed to happen after all mods are initialised.
	* You should always null-check APIs you consume. <samp>GetApi</samp> will return <samp>null</samp> if the API isn't available (''e.g.,'' because the mod isn't already installed or doesn't have one), ~~or if~~ an ~~error occurs fetching the API~~.		* You should always null-check APIs you consume. <samp>GetApi</samp> will return <samp>null</samp> if the API isn't available (''e.g.,'' because the mod isn't already installed or doesn't have one). If <samp>GetAPi</smap> cannot map an API, it will throw an exception.
	* Keep in mind that mods may change their API interfaces over time; it may be useful to check the version of the other mod before trying to map the interface.		* Keep in mind that mods may change their API interfaces over time; it may be useful to check the version of the other mod before trying to map the interface.

imported>Pathoschild: /* Providing an API */ update for SMAPI 3.17.0 release

2022-10-10T16:18:33Z

Providing an API: update for SMAPI 3.17.0 release

← Older revision		Revision as of 16:18, 10 October 2022
Line 51:		Line 51:
	</syntaxhighlight>		</syntaxhighlight>
	</li>		</li>
	<li>~~{{SMAPI upcoming\|3.17.0\|content=~~''Or'' Override <samp>GetApi(IModInfo mod)</samp> to provide one instance per mod. This will be called once for each mod that requests an API.		<li>''Or'' Override <samp>GetApi(IModInfo mod)</samp> to provide one instance per mod. This will be called once for each mod that requests an API.

	Note that this info is provided for informational purposes only (e.g. to log errors). Denying API access to specific mods is strongly discouraged and may be considered abusive.		Note that this info is provided for informational purposes only (e.g. to log errors). Denying API access to specific mods is strongly discouraged and may be considered abusive.
Line 59:		Line 59:
	return new YourModApi(mod.Manifest);		return new YourModApi(mod.Manifest);
	}		}
	</syntaxhighlight>}}		</syntaxhighlight>
	</li>		</li>
	</ul>		</ul>

imported>Pathoschild: /* Providing an API */ + GetApi(IModInfo mod) in SMAPI 3.17.0

2022-10-09T17:23:46Z

Providing an API: + GetApi(IModInfo mod) in SMAPI 3.17.0

← Older revision		Revision as of 17:23, 9 October 2022
Line 41:		Line 41:
	</syntaxhighlight>		</syntaxhighlight>
	(You can use a [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/constructors constructor] to initialise the API if desired.)</li>		(You can use a [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/constructors constructor] to initialise the API if desired.)</li>
	<li>Override <samp>GetApi</samp> in your mod's entry class and return an instance of your API:		<li>Override <samp>GetApi</samp> in your mod's entry class and return an instance of your API. You can choose between two versions of this method:
			<ul>
			<li>Override <samp>GetApi()</samp> to provide one instance of the API to all mods. This will only be called once, and SMAPI will cache the mod instance.
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	public override object GetApi()		public override object GetApi()
Line 47:		Line 49:
	return new YourModApi();		return new YourModApi();
	}		}
	</syntaxhighlight></li>		</syntaxhighlight>
			</li>
			<li>{{SMAPI upcoming\|3.17.0\|content=''Or'' Override <samp>GetApi(IModInfo mod)</samp> to provide one instance per mod. This will be called once for each mod that requests an API.

			Note that this info is provided for informational purposes only (e.g. to log errors). Denying API access to specific mods is strongly discouraged and may be considered abusive.
			<syntaxhighlight lang="c#">
			public override object GetApi(IModInfo mod)
			{
			return new YourModApi(mod.Manifest);
			}
			</syntaxhighlight>}}
			</li>
			</ul>
			</li>
	</ol>		</ol>