Stardew Valley Wiki

Changes

Modding:Migrate to SMAPI 2.0 (view source)

Revision as of 21:10, 7 May 2018

594 bytes removed ,  21:10, 7 May 2018
expand & rewrite into migration guide
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===
Pathoschild
translators
8,404

edits

Retrieved from "https://stardewvalleywiki.com/Special:MobileDiff/69746"