Protected, translators
5,421
edits
This wiki is a read-only version of the Stardew Valley Wiki. The official editable wiki maintained by ConcernedApe can be found at stardewvalleywiki.com
Changes
initial draft
←[[Modding:Index|Index]]
<div style="border: 1px solid red; background: #FCC; padding: 1em;">'''This is an internal draft page. SMAPI 3.0 is not ready and modders don't need to do anything yet.</div>
'''This page is for modders. Players: see [[Modding:SMAPI compatibility]] instead.'''
This page explains how to update your mod code for compatibility with SMAPI 3.0 (release TBD).
==Overview==
===What's changing?===
[[File:SMAPI compatibility.png|thumb|SMAPI compatibility over time. The SMAPI 2.0 release in October 2017 appears as a small bump. The Stardew Valley 1.3 release in May 2018 appears as a sudden cliff.]]
Events are arguably the most important and most visible part of SMAPI, but they've stayed essentially unchanged since SMAPI 0.40. New events have been added organically since then, but the event system has always been separate from the rest of SMAPI — they're inconsistent, have some weird behaviours (like <tt>MenuEvents.MenuChanged</tt> not being raised when a menu is closed), aren't available through the same helper as every other API, and there are some glaring omissions in the available events.
SMAPI 3.0 is the release that fixes all that. This release...
* Completely rewrites the event engine to make events more efficient and enable events that weren't possible before.
* Makes events much more consistent: they're now fully compliant with the [https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/event .NET design guidelines], have predictable and descriptive names, have consistent event handler signatures, and have clear documentation.
* All events are now accessible through <code>helper.Events</code>, so they're discoverable like any other SMAPI API.
* Weird behaviours and overlapping events have been eliminated.
* Many new events have been added.
* Every event now has relevant event arguments.
===Is this the modapocalypse?===
Nope. Although this is a major change, significant effort will be 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;
* pull requests will be 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;
* the changes will be 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 release. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.
===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:
# 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]]
# 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]]
# You can refer to the following sections on how to replace specific interfaces.
==Major changes==
===Removed APIs===
The following APIs were removed in SMAPI 1.9 and 2.0.
''TODO''
===Event changes===
''TODO''
[[Category:Modding]]
<div style="border: 1px solid red; background: #FCC; padding: 1em;">'''This is an internal draft page. SMAPI 3.0 is not ready and modders don't need to do anything yet.</div>
'''This page is for modders. Players: see [[Modding:SMAPI compatibility]] instead.'''
This page explains how to update your mod code for compatibility with SMAPI 3.0 (release TBD).
==Overview==
===What's changing?===
[[File:SMAPI compatibility.png|thumb|SMAPI compatibility over time. The SMAPI 2.0 release in October 2017 appears as a small bump. The Stardew Valley 1.3 release in May 2018 appears as a sudden cliff.]]
Events are arguably the most important and most visible part of SMAPI, but they've stayed essentially unchanged since SMAPI 0.40. New events have been added organically since then, but the event system has always been separate from the rest of SMAPI — they're inconsistent, have some weird behaviours (like <tt>MenuEvents.MenuChanged</tt> not being raised when a menu is closed), aren't available through the same helper as every other API, and there are some glaring omissions in the available events.
SMAPI 3.0 is the release that fixes all that. This release...
* Completely rewrites the event engine to make events more efficient and enable events that weren't possible before.
* Makes events much more consistent: they're now fully compliant with the [https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/event .NET design guidelines], have predictable and descriptive names, have consistent event handler signatures, and have clear documentation.
* All events are now accessible through <code>helper.Events</code>, so they're discoverable like any other SMAPI API.
* Weird behaviours and overlapping events have been eliminated.
* Many new events have been added.
* Every event now has relevant event arguments.
===Is this the modapocalypse?===
Nope. Although this is a major change, significant effort will be 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;
* pull requests will be 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;
* the changes will be 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 release. All of this means that the 3.0 release should have minimal impact on mod compatibility, despite the scope of the changes.
===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:
# 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]]
# 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]]
# You can refer to the following sections on how to replace specific interfaces.
==Major changes==
===Removed APIs===
The following APIs were removed in SMAPI 1.9 and 2.0.
''TODO''
===Event changes===
''TODO''
[[Category:Modding]]
