528
edits
Changes
Jump to navigation
Jump to search
Line 41:
Line 41: − + + + Line 47:
Line 49: − + + + + + + + + + + + + + + Line 60:
Line 75: − + Line 84:
Line 99: − + + − * 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>). − +
Modding:Modder Guide/APIs/Integrations (view source)
Revision as of 19:53, 26 November 2022
, 19:53, 26 November 2022→Using an API
</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()
return new YourModApi();
return new YourModApi();
}
}
</syntaxhighlight></li>
</syntaxhighlight>
</li>
<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.
<syntaxhighlight lang="c#">
public override object GetApi(IModInfo mod)
{
return new YourModApi(mod.Manifest);
}
</syntaxhighlight>
</li>
</ul>
</li>
</ol>
</ol>
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
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.
===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.
==Message sending==
==Message sending==
You can send messages using [[Modding:Modder Guide/APIs/Multiplayer|the multiplayer API]], with a destination ranging from very narrow (''e.g.,'' one mod on one connected computer) to very broad (all mods on all computers). Messages can also be sent to the current computer, ''e.g.,''to communicate between two mods. This can be used for a variety of integrations.
You can send messages using [[Modding:Modder Guide/APIs/Multiplayer|the multiplayer API]], with a destination ranging from very narrow (''e.g.,'' one mod on one connected computer) to very broad (all mods on all computers). Messages can also be sent to the current computer, ''e.g.,'' to communicate between two mods. This can be used for a variety of integrations.
For example:
For example:
* 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.)