Modding:Migrate to SMAPI 2.0 - Revision history

imported>Margotbean: zh link

2026-04-14T08:00:59Z

zh link

← Older revision		Revision as of 08:00, 14 April 2026
Line 276:		Line 276:

	[[Category:Modding]]		[[Category:Modding]]

			[[zh:模组:迁移至SMAPI 2.0]]

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

2021-11-04T18:48:20Z

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

Show changes

imported>RetroEdit: Replace deprecated tags with tags; add new template Template:Modder compatibility header

2021-02-19T17:46:31Z

Replace deprecated <source> tags with <syntaxhighlight> tags; add new template Template:Modder compatibility header

← Older revision		Revision as of 17:46, 19 February 2021
Line 1:		Line 1:
	←[[Modding:Index\|Index]]		←[[Modding:Index\|Index]]

	~~'''This page is for modders. Players: see [[Modding:Mod~~ compatibility~~]] instead.'''~~		{{Modder compatibility header}}

	This page explains how to update your SMAPI mod code for compatibility with SMAPI 1.9 (released alongside Stardew Valley 1.2 in April 2017) and 2.0 (released in October 2017).		This page explains how to update your SMAPI mod code for compatibility with SMAPI 1.9 (released alongside Stardew Valley 1.2 in April 2017) and 2.0 (released in October 2017).

Line 169:		Line 168:
	Change your mod's entry class from this:		Change your mod's entry class from this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	/// <summary>Initialise the mod.</summary>		/// <summary>Initialise the mod.</summary>
	public override void Entry(params object[] objects)		public override void Entry(params object[] objects)
Line 175:		Line 174:
	// your code		// your code
	}		}
	</~~source~~>		</syntaxhighlight>

	to this:		to this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	/// <summary>The mod entry point, called after the mod is first loaded.</summary>		/// <summary>The mod entry point, called after the mod is first loaded.</summary>
	/// <param name="helper">Provides simplified APIs for writing mods.</param>		/// <param name="helper">Provides simplified APIs for writing mods.</param>
Line 186:		Line 185:
	// your code		// your code
	}		}
	</~~source~~>		</syntaxhighlight>

	===Mod configuration===		===Mod configuration===
Line 196:		Line 195:
	<li>Find your subclass of <tt>StardewModdingAPI.Config</tt>, which probably looks something like this:		<li>Find your subclass of <tt>StardewModdingAPI.Config</tt>, which probably looks something like this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	class SampleConfig : StardewModdingAPI.Config		class SampleConfig : StardewModdingAPI.Config
	{		{
Line 209:		Line 208:
	}		}
	}		}
	</~~source~~></li>		</syntaxhighlight></li>

	<li>Edit this class as follows:		<li>Edit this class as follows:
Line 219:		Line 218:
	<li>Your class should now look something like this:		<li>Your class should now look something like this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	class SampleConfig		class SampleConfig
	{		{
Line 225:		Line 224:
	public float ExampleFloat { get; set; } = 0.5;		public float ExampleFloat { get; set; } = 0.5;
	}		}
	</~~source~~>		</syntaxhighlight>

	or like this if you used a constructor:		or like this if you used a constructor:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	class SampleConfig		class SampleConfig
	{		{
Line 241:		Line 240:
	}		}
	}		}
	</~~source~~></li>		</syntaxhighlight></li>

	<li>In your <tt>Mod</tt> class, change anything that looks like this:		<li>In your <tt>Mod</tt> class, change anything that looks like this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var config = new SampleConfig().InitializeConfig(this.BaseConfigPath);		var config = new SampleConfig().InitializeConfig(this.BaseConfigPath);
	</~~source~~>		</syntaxhighlight>

	to this:		to this:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var config = helper.ReadConfig<SampleConfig>();		var config = helper.ReadConfig<SampleConfig>();
	</~~source~~></li>		</syntaxhighlight></li>

	<li>If you use other methods, here's how to migrate them:		<li>If you use other methods, here's how to migrate them:

imported>Pathoschild: /* What's changing and how much does it impact mods? */ fix typo

2020-10-09T17:16:25Z

What's changing and how much does it impact mods?: fix typo

← Older revision		Revision as of 17:16, 9 October 2020
Line 9:		Line 9:
	[[File:SMAPI compatibility.png\|thumb\|SMAPI compatibility over time. The SMAPI 2.0 release in October 2017 appears as a small bump.]]		[[File:SMAPI compatibility.png\|thumb\|SMAPI compatibility over time. The SMAPI 2.0 release in October 2017 appears as a small bump.]]

	The last major breaking change was in SMAPI 0.40 (April 2016). Since then 23 SMAPI releases were published with almost full backwards compatibility. SMAPI has matured significantly since version 0.40, and its APIs have converged towards better consistency. Older APIs have been [[wikipedia:Deprecation\|deprecated]] with full support, but this introduces significant maintenance overhead. A few rarely-used APIs were dropped in SMAPI 1.9 (when Stardew Valley 1.2 broke many mods),and SMAPI 2.0 is the release which finally drops support for these old APIs.		The last major breaking change was in SMAPI 0.40 (April 2016). Since then 23 SMAPI releases were published with almost full backwards compatibility. SMAPI has matured significantly since version 0.40, and its APIs have converged towards better consistency. Older APIs have been [[wikipedia:Deprecation\|deprecated]] with full support, but this introduces significant maintenance overhead. A few rarely-used APIs were dropped in SMAPI 1.9 (when Stardew Valley 1.2 broke many mods), and SMAPI 2.0 is the release which finally drops support for these old APIs.

	Although this is a major change, significant effort was undertaken to minimise the impact on mods: (a) the APIs were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal; (b) dozens of pull requests were submitted to update affected mods; (c) unofficial updates were created for mods which haven't updated officially yet; and (d) the changes were actively communicated and documented to modders. This means that SMAPI 2.0 has a minimal impact on mod compatibility (see chart on the right).		Although this is a major change, significant effort was undertaken to minimise the impact on mods: (a) the APIs were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal; (b) dozens of pull requests were submitted to update affected mods; (c) unofficial updates were created for mods which haven't updated officially yet; and (d) the changes were actively communicated and documented to modders. This means that SMAPI 2.0 has a minimal impact on mod compatibility (see chart on the right).

imported>Margotbean: update link

2019-05-07T20:08:22Z

update link

← Older revision		Revision as of 20:08, 7 May 2019
Line 1:		Line 1:
	←[[Modding:Index\|Index]]		←[[Modding:Index\|Index]]

	'''This page is for modders. Players: see [[Modding:~~SMAPI~~ compatibility]] instead.'''		'''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.'''

	This page explains how to update your SMAPI mod code for compatibility with SMAPI 1.9 (released alongside Stardew Valley 1.2 in April 2017) and 2.0 (released in October 2017).		This page explains how to update your SMAPI mod code for compatibility with SMAPI 1.9 (released alongside Stardew Valley 1.2 in April 2017) and 2.0 (released in October 2017).

imported>Margotbean: direct link

2018-10-11T18:30:28Z

direct link

← Older revision		Revision as of 18:30, 11 October 2018
Line 165:		Line 165:

	===Mod entry method===		===Mod entry method===
	''For the latest documentation, see [[Modding:Modder Guide]].''		''For the latest documentation, see [[Modding:Modder Guide/Get Started]].''

	Change your mod's entry class from this:		Change your mod's entry class from this:

imported>Pathoschild: update link

2018-06-26T23:17:02Z

update link

← Older revision		Revision as of 23:17, 26 June 2018
Line 109:		Line 109:
	\| 2.0		\| 2.0
	\| <tt>Mod.PerSaveConfigFolder</tt>		\| <tt>Mod.PerSaveConfigFolder</tt>
	\| use [[Modding:~~Creating a SMAPI mod#Configuration~~\|per-save JSON files]] instead.		\| use [[Modding:Modder Guide/APIs/Config\|per-save JSON files]] instead.
	\|-		\|-
	\| 1.0		\| 1.0

imported>Pathoschild: update links

2018-06-26T23:16:22Z

update links

← Older revision		Revision as of 23:16, 26 June 2018
Line 114:		Line 114:
	\| 2.0		\| 2.0
	\| <tt>Mod.PerSaveConfigPath</tt>		\| <tt>Mod.PerSaveConfigPath</tt>
	\| use [[Modding:~~Creating a SMAPI mod#Configuration~~\|per-save JSON files]] instead.		\| use [[Modding:Modder Guide/APIs/Config\|per-save JSON files]] instead.
	\|-		\|-
	\| 1.0		\| 1.0
Line 165:		Line 165:

	===Mod entry method===		===Mod entry method===
	''For the latest documentation, see [[Modding:~~Creating a SMAPI mod#Write the code~~]].''		''For the latest documentation, see [[Modding:Modder Guide]].''

	Change your mod's entry class from this:		Change your mod's entry class from this:
Line 189:		Line 189:

	===Mod configuration===		===Mod configuration===
	''For the latest documentation, see [[Modding:~~Creating a SMAPI mod#Configuration~~]].''		''For the latest documentation, see [[Modding:Modder Guide/APIs/Config]].''

	If you use <tt>config.json</tt>, it's much easier in 1.0.		If you use <tt>config.json</tt>, it's much easier in 1.0.
Line 274:		Line 274:
	</ol>		</ol>

	For more information, see [[Modding:~~Creating a SMAPI mod#Configuration~~]].		For more information, see [[Modding:Modder Guide/APIs/Config]].

	[[Category:Modding]]		[[Category:Modding]]

imported>Pathoschild: expand & rewrite into migration guide

2018-05-07T21:10:54Z

expand & rewrite into migration guide

← Older revision		Revision as of 21:10, 7 May 2018
Line 1:		Line 1:
	← [[Modding:Index\|Index]]		←[[Modding:Index\|Index]]

	~~In rare cases, SMAPI needs to change the interfaces it exposes to mods. (This doesn~~'~~t happen often, because SMAPI strives to expose abstract interfaces that aren~~'~~t tightly coupled to changes in the game~~.~~) When an interface does need to change, the old interface is~~ [[~~wikipedia~~:~~Deprecation\|deprecated~~]] ~~and supported long enough to let mods update at their own pace~~.		'''This page is for modders. Players: see [[Modding:SMAPI compatibility]] instead.'''

	~~==How~~ to update your mod==		This page explains how to update your SMAPI mod code for compatibility with SMAPI 1.9 (released alongside Stardew Valley 1.2 in April 2017) and 2.0 (released in October 2017).
	~~You don't need to comb through your~~ code; SMAPI ~~can tell you if you're using a deprecated interface:~~

	# Use the latest [https://smapi.io/ SMAPI for developers] download. This will show deprecation messages in the console:<br />[[File:Modding - updating deprecated SMAPI code - deprecation warnings.png]]		==Overview==
	~~# When you look at the code, you~~'~~ll see a deprecation warning with a hint of~~ how ~~to fix~~ it~~:<br />~~[[File:~~Modding - updating deprecated~~ SMAPI ~~code - deprecation intellisense~~.png]]		===What's changing and how much does it impact mods?===
	~~# Optionally, you can refer to the following sections on how to replace specific interfaces.~~		[[File:SMAPI compatibility.png\|thumb\|SMAPI compatibility over time. The SMAPI 2.0 release in October 2017 appears as a small bump.]]

	~~==How~~ deprecated ~~interfaces are phased out==~~		The last major breaking change was in SMAPI 0.40 (April 2016). Since then 23 SMAPI releases were published with almost full backwards compatibility. SMAPI has matured significantly since version 0.40, and its APIs have converged towards better consistency. Older APIs have been [[wikipedia:Deprecation\|deprecated]] with full support, but this introduces significant maintenance overhead. A few rarely-used APIs were dropped in SMAPI 1.9 (when Stardew Valley 1.2 broke many mods),and SMAPI 2.0 is the release which finally drops support for these old APIs.
	~~Deprecated interfaces are fully supported until their removal~~. ~~They'll slowly move through~~ these ~~phases:~~

	~~{\| class="wikitable"~~		Although this is a major change, significant effort was undertaken to minimise the impact on mods: (a) the APIs were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal; (b) dozens of pull requests were submitted to update affected mods; (c) unofficial updates were created for mods which haven't updated officially yet; and (d) the changes were actively communicated and documented to modders. This means that SMAPI 2.0 has a minimal impact on mod compatibility (see chart on the right).
	\|-
	~~! severity !! description~~
	\|-
	~~\| ''notice'' \|\| The interface~~ is ~~deprecated~~, ~~but mod authors have time~~ to ~~update their~~ mods~~. Nothing is reported to~~ the ~~console, though deprecation messages are shown~~ in the ~~log file.~~
	\|-
	~~\| ''info'' \|\| Mods should no longer use the interface. Debug-level~~ deprecation ~~messages are shown in the console.~~
	\|-
	~~\| ''pending~~ removal'~~' \|\| Mods should no longer use~~ the ~~interface~~. ~~Warning-level deprecation messages in the console indicate~~ the ~~mod will break soon if it doesn't update~~.
	\|}

	~~The~~ interface ~~will then be removed entirely.~~		===How to update your mod===
			You don't need to comb through your code manually. SMAPI can tell you if you're using a deprecated interface:

	~~==Deprecated interfaces==~~		# Use the latest [https://smapi.io/ SMAPI for developers] download. This will show deprecation messages in the console:<br />[[File:Modding - updating deprecated SMAPI code - deprecation warnings.png]]
	~~===Currently~~ deprecated~~===~~		# When you look at the code, you'll see a deprecation warning with a hint of how to fix it:<br />[[File:Modding - updating deprecated SMAPI code - deprecation intellisense.png]]
	~~These are currently deprecated:~~		# Optionally, you can refer to the following sections on how to replace specific interfaces.

	~~{\| class~~=~~"wikitable"~~		==Major changes==
	\|-		===Removed APIs===
	~~! since~~		The following APIs were removed in SMAPI 1.9 and 2.0.
	~~! interfaces~~
	~~! severity~~
	~~! replacement~~
	\|-
	~~\| 2~~.3
	~~\| <tt>IReflectionHelper.GetPrivateField</tt><br /><tt>IReflectionHelper.GetPrivateMethod</tt><br /><tt>IReflectionHelper.GetPrivateProperty</tt>~~
	~~\| ''notice''~~
	~~\| renamed to <tt>GetField</tt>, <tt>GetMethod</tt>,~~ and <tt>GetProperty</tt> respectively; their return values have also been renamed (<tt>IPrivateField</tt> → <tt>IReflectedField</tt>, <tt>IPrivateProperty</tt> → <tt>IReflectedProperty</tt>, and <tt>IPrivateMethod</tt> → <tt>IReflectedMethod</tt>).
	\|-
	\| 2.3
	~~\| <tt>IReflectionHelper.GetPrivateValue</tt>~~
	~~\| ''notice''~~
	~~\| use <tt>GetPrivateField(...).GetValue()</tt> instead~~.
	\|-
	~~\| 2.5~~
	~~\| <tt>helper.CreateTransitionalContentPack</tt>~~
	~~\| ''notice''~~
	\| use [[Modding:Content packs\|SMAPI content packs]]. This method was added in 2.5 so older mods with their own content pack format could use the standard APIs to simplify the transition to SMAPI content packs.
	\|}

	~~===Removed in SMAPI 2.0===~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
	! deprecated		! deprecated
	! removed		! removed
	! ~~interfaces~~		! old APIs
	! replacement		! replacement
	\|-		\|-
Line 193:		Line 163:

	<small>¹ Stardew Valley 1.2 broke many existing mods, so SMAPI 1.9 used the opportunity to remove the most rarely-used deprecated APIs.</small>		<small>¹ Stardew Valley 1.2 broke many existing mods, so SMAPI 1.9 used the opportunity to remove the most rarely-used deprecated APIs.</small>

	~~==Migration guides==~~
	~~This section provides more information for some migrations mentioned in the previous section.~~

	===Mod entry method===		===Mod entry method===

imported>Pathoschild: Pathoschild moved page Modding:Updating deprecated SMAPI code to Modding:Migrate to SMAPI 2.0: use new migration guide convention

2018-05-07T20:27:20Z

Pathoschild moved page Modding:Updating deprecated SMAPI code to Modding:Migrate to SMAPI 2.0: use new migration guide convention

← Older revision		Revision as of 20:27, 7 May 2018
(No difference)