Modding:Migrate to SMAPI 3.0 - Revision history

imported>Margotbean: +zh link

2026-04-14T08:00:18Z

+zh link

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

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

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

imported>Pathoschild: /* Is this the modapocalypse? */ copyedit

2022-03-26T05:53:02Z

Is this the modapocalypse?: copyedit

← Older revision		Revision as of 05:53, 26 March 2022
Line 22:		Line 22:

	===Is this the modapocalypse?===		===Is this the modapocalypse?===
	Nope. Although this is a major change, significant ~~effort~~ were undertaken to ~~minimise~~ the impact:		Nope. Although this is a major change, significant efforts were undertaken to minimize the impact:
	* the old events were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal;		* the old events were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal;
	* pull requests were submitted to update affected open-source mods;		* pull requests were submitted to update affected open-source mods;
	* unofficial updates were created for mods which haven't updated officially by the time SMAPI 3.0 is released;		* unofficial updates were created for mods which haven't updated officially by the time SMAPI 3.0 is released;
	* the changes ~~was~~ actively communicated and documented to modders.		* the changes were actively communicated and documented to modders.

	In addition, the current target is ''at least'' 95% compatibility for open-source mods before SMAPI 3.0 is released. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.		In addition, the current target is ''at least'' 95% compatibility for open-source mods before SMAPI 3.0 is released. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.

imported>Margotbean: Text replacement - "''e.g.''," to "''e.g.,''"

2021-11-08T00:40:39Z

Text replacement - "''e.g.''," to "''e.g.,''"

← Older revision		Revision as of 00:40, 8 November 2021
Line 161:		Line 161:
	\|old events = GraphicsEvents.OnPostRenderEvent		\|old events = GraphicsEvents.OnPostRenderEvent
	\|new events = Display.Rendered		\|new events = Display.Rendered
	\|summary = Equivalent, except the new event isn't triggered during certain special cutscenes and minigames (''e.g.'', the [[Sebastian#Six Hearts\|board game scene]]).		\|summary = Equivalent, except the new event isn't triggered during certain special cutscenes and minigames (''e.g.,'' the [[Sebastian#Six Hearts\|board game scene]]).
	}}		}}
	{{/event		{{/event
Line 219:		Line 219:
	\|old events = MenuEvents.MenuChanged, MenuEvents.MenuClosed		\|old events = MenuEvents.MenuChanged, MenuEvents.MenuClosed
	\|new events = Display.MenuChanged		\|new events = Display.MenuChanged
	\|summary = These caused a lot of confusion (''e.g.'', <samp>MenuEvents.MenuClosed</samp> wasn't called when a menu was closed and immediately replaced), so they've been combined into one event which is called when a menu is opened, closed, or replaced. You can check the <samp>e.OldMenu</samp> and <samp>e.NewMenu</samp> event args to know what the change is (''e.g.'', to match the old <samp>MenuEvents.MenuClosed</samp>, check <code>if (e.NewMenu == null)</code>).		\|summary = These caused a lot of confusion (''e.g.,'' <samp>MenuEvents.MenuClosed</samp> wasn't called when a menu was closed and immediately replaced), so they've been combined into one event which is called when a menu is opened, closed, or replaced. You can check the <samp>e.OldMenu</samp> and <samp>e.NewMenu</samp> event args to know what the change is (''e.g.,'' to match the old <samp>MenuEvents.MenuClosed</samp>, check <code>if (e.NewMenu == null)</code>).
	}}		}}
	{{/event		{{/event

imported>Margotbean: Text replacement - "(e.g. " to "(''e.g.'', "

2021-11-07T23:41:43Z

Text replacement - "(e.g. " to "(''e.g.'', "

← Older revision		Revision as of 23:41, 7 November 2021
Line 161:		Line 161:
	\|old events = GraphicsEvents.OnPostRenderEvent		\|old events = GraphicsEvents.OnPostRenderEvent
	\|new events = Display.Rendered		\|new events = Display.Rendered
	\|summary = Equivalent, except the new event isn't triggered during certain special cutscenes and minigames (e.g. the [[Sebastian#Six Hearts\|board game scene]]).		\|summary = Equivalent, except the new event isn't triggered during certain special cutscenes and minigames (''e.g.'', the [[Sebastian#Six Hearts\|board game scene]]).
	}}		}}
	{{/event		{{/event
Line 219:		Line 219:
	\|old events = MenuEvents.MenuChanged, MenuEvents.MenuClosed		\|old events = MenuEvents.MenuChanged, MenuEvents.MenuClosed
	\|new events = Display.MenuChanged		\|new events = Display.MenuChanged
	\|summary = These caused a lot of confusion (e.g. <samp>MenuEvents.MenuClosed</samp> wasn't called when a menu was closed and immediately replaced), so they've been combined into one event which is called when a menu is opened, closed, or replaced. You can check the <samp>e.OldMenu</samp> and <samp>e.NewMenu</samp> event args to know what the change is (e.g. to match the old <samp>MenuEvents.MenuClosed</samp>, check <code>if (e.NewMenu == null)</code>).		\|summary = These caused a lot of confusion (''e.g.'', <samp>MenuEvents.MenuClosed</samp> wasn't called when a menu was closed and immediately replaced), so they've been combined into one event which is called when a menu is opened, closed, or replaced. You can check the <samp>e.OldMenu</samp> and <samp>e.NewMenu</samp> event args to know what the change is (''e.g.'', to match the old <samp>MenuEvents.MenuClosed</samp>, check <code>if (e.NewMenu == null)</code>).
	}}		}}
	{{/event		{{/event

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

2021-11-04T18:48:56Z

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

Show changes

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

2021-02-19T17:47:27Z

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

← Older revision		Revision as of 17:47, 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 mod code for compatibility with SMAPI 3.0. See also [[Modding:Migrate to Stardew Valley 1.4]].		This page explains how to update your mod code for compatibility with SMAPI 3.0. See also [[Modding:Migrate to Stardew Valley 1.4]].

Line 46:		Line 45:

	For example, let's say you have code like this:		For example, let's say you have code like this:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	public override void Entry(IModHelper helper)		public override void Entry(IModHelper helper)
	{		{
Line 54:		Line 53:
	this.VaultRoomID = communityCenter.getAreaNumberFromName("Vault");		this.VaultRoomID = communityCenter.getAreaNumberFromName("Vault");
	}		}
	</~~source~~>		</syntaxhighlight>

	That code fails in SMAPI 3.0, because no locations are loaded yet. This code could be rewritten like this:		That code fails in SMAPI 3.0, because no locations are loaded yet. This code could be rewritten like this:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	public override void Entry(IModHelper helper)		public override void Entry(IModHelper helper)
	{		{
Line 70:		Line 69:
	this.VaultRoomID = communityCenter.getAreaNumberFromName("Vault");		this.VaultRoomID = communityCenter.getAreaNumberFromName("Vault");
	}		}
	</~~source~~>		</syntaxhighlight>

	===API changes===		===API changes===
Line 296:		Line 295:
	===Manifest version format===		===Manifest version format===
	The [[Modding:Modder Guide/APIs/Manifest\|<tt>manifest.json</tt>]] no longer allows versions in this form:		The [[Modding:Modder Guide/APIs/Manifest\|<tt>manifest.json</tt>]] no longer allows versions in this form:
	<~~source~~ lang="js">		<syntaxhighlight lang="js">
	"Version": {		"Version": {
	"MajorVersion": 1,		"MajorVersion": 1,
Line 303:		Line 302:
	"Build": "beta"		"Build": "beta"
	}		}
	</~~source~~>		</syntaxhighlight>

	Versions should be written in the standard string form instead:		Versions should be written in the standard string form instead:
	<~~source~~ lang="js">		<syntaxhighlight lang="js">
	"Version": "1.0.0-beta"		"Version": "1.0.0-beta"
	</~~source~~>		</syntaxhighlight>

	===Version format===		===Version format===

imported>Pathoschild: fix tense

2019-11-27T04:39:03Z

fix tense

← Older revision		Revision as of 04:39, 27 November 2019
Line 23:		Line 23:

	===Is this the modapocalypse?===		===Is this the modapocalypse?===
	Nope. Although this is a major change, significant effort ~~will be~~ undertaken to minimise the impact:		Nope. Although this is a major change, significant effort were undertaken to minimise the impact:
	* the old events ~~will be~~ supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal;		* the old events were supported for a long time with increasingly prominent warnings in the SMAPI console about their deprecation and removal;
	* pull requests ~~will be~~ submitted to update affected open-source mods;		* pull requests were submitted to update affected open-source mods;
	* unofficial updates ~~will be~~ created for mods which haven't updated officially by the time SMAPI 3.0 is released;		* unofficial updates were created for mods which haven't updated officially by the time SMAPI 3.0 is released;
	* the changes ~~will be~~ actively communicated and documented to modders.		* the changes was actively communicated and documented to modders.

	In addition, the current target is ''at least'' 95% compatibility for open-source mods before SMAPI 3.0 is released. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.		In addition, the current target is ''at least'' 95% compatibility for open-source mods before SMAPI 3.0 is released. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.
Line 56:		Line 56:
	</source>		</source>

	That code ~~will fail~~ in SMAPI 3.0, because no locations are loaded yet. This code could be rewritten like this:		That code fails in SMAPI 3.0, because no locations are loaded yet. This code could be rewritten like this:
	<source lang="c#">		<source lang="c#">
	public override void Entry(IModHelper helper)		public override void Entry(IModHelper helper)
Line 102:		Line 102:

	===Event changes===		===Event changes===
	The former events ~~will be~~ removed in SMAPI 3.0. Here's how to convert them to the new events under <tt>this.Helper.Events</tt>. This list only shows equivalent events in SMAPI 3.0; see [[Modding:Modder Guide/APIs/Events\|''events'' in the modder guide]] for a full list.		The former events are removed in SMAPI 3.0. Here's how to convert them to the new events under <tt>this.Helper.Events</tt>. This list only shows equivalent events in SMAPI 3.0; see [[Modding:Modder Guide/APIs/Events\|''events'' in the modder guide]] for a full list.

	{\| class="wikitable"		{\| class="wikitable"

imported>Pathoschild: update intro

2019-11-26T18:11:00Z

update intro

← Older revision		Revision as of 18:11, 26 November 2019
Line 3:		Line 3:
	'''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.'''		'''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.'''

	This page explains how to update your mod code for compatibility with SMAPI 3.0~~, which will release at the same time as Stardew Valley in May/June 2019~~. See also [[Modding:Migrate to Stardew Valley 1.4]].		This page explains how to update your mod code for compatibility with SMAPI 3.0. See also [[Modding:Migrate to Stardew Valley 1.4]].

	==Overview==		==Overview==

imported>Pathoschild: /* Version format */ tweak wording

2019-11-04T21:49:23Z

Version format: tweak wording

← Older revision		Revision as of 21:49, 4 November 2019
Line 311:		Line 311:

	===Version format===		===Version format===
	~~Formatting a version~~ no longer omits ~~the~~ patch ~~number~~ when ~~it's zero~~. For example, the console now shows SMAPI 3.0.0 instead of 3.0. (That's more [https://semver.org/ standard], improves compatibility with external tools, and reduces player confusion.)		SMAPI no longer omits <code>.0</code> patch numbers when formatting versions. For example, the console now shows SMAPI 3.0.0 instead of 3.0. That's more [https://semver.org/ standard], improves compatibility with external tools, and reduces player confusion.

	This doesn't affect most mod code. You may need to update your code if you use <tt>ISemanticVersion.ToString()</tt> and compare the output to a hardcoded two-part version string.		This doesn't affect most mod code. You may need to update your code if you use <tt>ISemanticVersion.ToString()</tt> and compare the output to a hardcoded two-part version string.

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

imported>Pathoschild: /* Changes */ + Version format

2019-11-04T21:27:30Z

Changes: + Version format

← Older revision		Revision as of 21:27, 4 November 2019
Line 309:		Line 309:
	"Version": "1.0.0-beta"		"Version": "1.0.0-beta"
	</source>		</source>

			===Version format===
			Formatting a version no longer omits the patch number when it's zero. For example, the console now shows SMAPI 3.0.0 instead of 3.0. (That's more [https://semver.org/ standard], improves compatibility with external tools, and reduces player confusion.)

			This doesn't affect most mod code. You may need to update your code if you use <tt>ISemanticVersion.ToString()</tt> and compare the output to a hardcoded two-part version string.

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