translators
8,456
edits
Changes
Jump to navigation
Jump to search
Modding:Modder Guide/APIs/Mod structure (view source)
Revision as of 00:44, 2 April 2019
, 00:44, 2 April 2019create initial draft
{{../../header}}
'''See [[Modding:Modder Guide]] for an introduction to creating a SMAPI mod. This is a technical reference page which assumes you've already followed that guide.'''
__TOC__
==Basic structure==
A SMAPI mod must have...
# a compiled DLL file which contains the code to run as part of the mod (see [[#Mod entry|''mod entry'' below]]);
# a [[Modding:Modder Guide/APIs/Manifest|<tt>manifest.json</tt> file]] which describes the mod.
It may optionally have...
# any number of [[#Dependencies|compiled <tt>.dll</tt> and <tt>.pdb</tt> files referenced by the main mod DLL]];
# an [[Modding:Modder Guide/APIs/Translation|<tt>i18n</tt> folder containing translations]];
# any number of custom files used by the mod code (usually in an <tt>assets</tt> folder by convention).
==Mod entry==
The main mod project must have a subclass of <tt>StardewModdingAPI.Mod</tt>. The class is often named <tt>ModEntry</tt> by convention, but you can use any valid C# name. The class must implement an <tt>Entry</tt> method, which SMAPI will call once the mod is loaded. The <tt>IModHelper helper</tt> argument provides access to nearly all [[Modding:Modder Guide/APIs|SMAPI APIs]], but you can access it via <tt>this.Helper</tt> in other methods.
Here's the minimum possible implementation (which does nothing at all):
<source lang="c#">
using StardewModdingAPI;
/// <summary>The mod entry point.</summary>
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)
{
}
}
</source>
This is a good place to [[Modding:Modder Guide/APIs/Config|read configuration]], [[Modding:Modder Guide/APIs/Events|register event handlers]], and [[Modding:Modder Guide/APIs/Content|load mod assets]]. However the method may be called very early in the process before the game is initialised, so you should use events like <tt>GameLaunched</tt>, <tt>SaveLoaded</tt>, or <tt>DayStarted</tt> if you need initialised game data.
==Dependencies==
Most mods are self-contained and only have one DLL file, but that's not a hard limit. Here are some common patterns:
* [[Modding:Modder Guide/APIs/Manifest#Dependencies|Declare a dependency on another mod]], and SMAPI will load the other mod before yours and show a friendly error if it's not installed. You can [[Modding:Modder Guide/APIs/Integrations|use a mod-provided API]] if the mod has one, or reference the DLL directly. (If you reference a mod DLL, make sure it's ''not'' [https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx marked 'copy local'] to avoid issues; SMAPI will load the installed version instead.)
* [https://docs.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/shared-projects Create a shared project] and reference it from your mod project. The shared project's code will be compiled as part of your mod project (so it'll be one DLL containing both projects in the mod folder).
* Reference projects/DLLs and copy their DLLs into your mod folder. SMAPI will detect the reference and load the DLLs from your mod folder automatically. '''Don't do this for referencing a mod''' — that can cause confusing errors when multiple versions are available (see the first option instead).
{{modding guide footer
|prev = [[Modding:Modder Guide/APIs|SMAPI reference]]
|next =
}}
'''See [[Modding:Modder Guide]] for an introduction to creating a SMAPI mod. This is a technical reference page which assumes you've already followed that guide.'''
__TOC__
==Basic structure==
A SMAPI mod must have...
# a compiled DLL file which contains the code to run as part of the mod (see [[#Mod entry|''mod entry'' below]]);
# a [[Modding:Modder Guide/APIs/Manifest|<tt>manifest.json</tt> file]] which describes the mod.
It may optionally have...
# any number of [[#Dependencies|compiled <tt>.dll</tt> and <tt>.pdb</tt> files referenced by the main mod DLL]];
# an [[Modding:Modder Guide/APIs/Translation|<tt>i18n</tt> folder containing translations]];
# any number of custom files used by the mod code (usually in an <tt>assets</tt> folder by convention).
==Mod entry==
The main mod project must have a subclass of <tt>StardewModdingAPI.Mod</tt>. The class is often named <tt>ModEntry</tt> by convention, but you can use any valid C# name. The class must implement an <tt>Entry</tt> method, which SMAPI will call once the mod is loaded. The <tt>IModHelper helper</tt> argument provides access to nearly all [[Modding:Modder Guide/APIs|SMAPI APIs]], but you can access it via <tt>this.Helper</tt> in other methods.
Here's the minimum possible implementation (which does nothing at all):
<source lang="c#">
using StardewModdingAPI;
/// <summary>The mod entry point.</summary>
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)
{
}
}
</source>
This is a good place to [[Modding:Modder Guide/APIs/Config|read configuration]], [[Modding:Modder Guide/APIs/Events|register event handlers]], and [[Modding:Modder Guide/APIs/Content|load mod assets]]. However the method may be called very early in the process before the game is initialised, so you should use events like <tt>GameLaunched</tt>, <tt>SaveLoaded</tt>, or <tt>DayStarted</tt> if you need initialised game data.
==Dependencies==
Most mods are self-contained and only have one DLL file, but that's not a hard limit. Here are some common patterns:
* [[Modding:Modder Guide/APIs/Manifest#Dependencies|Declare a dependency on another mod]], and SMAPI will load the other mod before yours and show a friendly error if it's not installed. You can [[Modding:Modder Guide/APIs/Integrations|use a mod-provided API]] if the mod has one, or reference the DLL directly. (If you reference a mod DLL, make sure it's ''not'' [https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx marked 'copy local'] to avoid issues; SMAPI will load the installed version instead.)
* [https://docs.microsoft.com/en-us/xamarin/cross-platform/app-fundamentals/shared-projects Create a shared project] and reference it from your mod project. The shared project's code will be compiled as part of your mod project (so it'll be one DLL containing both projects in the mod folder).
* Reference projects/DLLs and copy their DLLs into your mod folder. SMAPI will detect the reference and load the DLLs from your mod folder automatically. '''Don't do this for referencing a mod''' — that can cause confusing errors when multiple versions are available (see the first option instead).
{{modding guide footer
|prev = [[Modding:Modder Guide/APIs|SMAPI reference]]
|next =
}}