Merge branch 'develop' into stable

1 files changed, 31 insertions, 6 deletions

diff --git a/src/SMAPI/Utilities/PerScreen.cs b/src/SMAPI/Utilities/PerScreen.cs
index 20b8fbce..1c4c56fe 100644
--- a/src/SMAPI/Utilities/PerScreen.cs
+++ b/src/SMAPI/Utilities/PerScreen.cs
@@ -1,6 +1,8 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using StardewModdingAPI.Framework;
+using StardewModdingAPI.Framework.Deprecations;
 
 namespace StardewModdingAPI.Utilities
 {
@@ -37,15 +39,14 @@ namespace StardewModdingAPI.Utilities
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <remarks><strong>Limitation with nullable reference types:</strong> when the underlying type <typeparamref name="T"/> is nullable, this sets the default value to null regardless of whether you marked the type parameter nullable. To avoid that, set the default value with the 'createNewState' argument instead.</remarks>
         public PerScreen()
-            : this(null) { }
+            : this(null, nullExpected: true) { }
 
         /// <summary>Construct an instance.</summary>
         /// <param name="createNewState">Create the initial state for a screen.</param>
         public PerScreen(Func<T> createNewState)
-        {
-            this.CreateNewState = createNewState ?? (() => default);
-        }
+            : this(createNewState, nullExpected: false) { }
 
         /// <summary>Get all active values by screen ID. This doesn't initialize the value for a screen ID if it's not created yet.</summary>
         public IEnumerable<KeyValuePair<int, T>> GetActiveValues()
@@ -59,7 +60,7 @@ namespace StardewModdingAPI.Utilities
         public T GetValueForScreen(int screenId)
         {
             this.RemoveDeadScreens();
-            return this.States.TryGetValue(screenId, out T state)
+            return this.States.TryGetValue(screenId, out T? state)
                 ? state
                 : this.States[screenId] = this.CreateNewState();
         }
@@ -76,13 +77,37 @@ namespace StardewModdingAPI.Utilities
         /// <summary>Remove all active values.</summary>
         public void ResetAllScreens()
         {
-            this.RemoveScreens(p => true);
+            this.RemoveScreens(_ => true);
         }
 
 
         /*********
         ** Private methods
         *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="createNewState">Create the initial state for a screen.</param>
+        /// <param name="nullExpected">Whether a null <paramref name="createNewState"/> value is expected.</param>
+        /// <remarks>This constructor only exists to maintain backwards compatibility. In SMAPI 4.0.0, the overload that passes <c>nullExpected: false</c> should throw an exception instead.</remarks>
+        private PerScreen(Func<T>? createNewState, bool nullExpected)
+        {
+            if (createNewState is null)
+            {
+                createNewState = (() => default!);
+
+                if (!nullExpected)
+                {
+                    SCore.DeprecationManager.Warn(
+                        SCore.DeprecationManager.GetModFromStack(),
+                        $"calling the {nameof(PerScreen<T>)} constructor with null",
+                        "3.14.0",
+                        DeprecationLevel.Notice
+                    );
+                }
+            }
+
+            this.CreateNewState = createNewState;
+        }
+
         /// <summary>Remove screens which are no longer active.</summary>
         private void RemoveDeadScreens()
         {