Merge branch 'develop' into stable

21 files changed, 377 insertions, 194 deletions

diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index 493aebd9..31dafa8e 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -52,7 +52,7 @@ namespace StardewModdingAPI
         internal static int? LogScreenId { get; set; }
 
         /// <summary>SMAPI's current raw semantic version.</summary>
-        internal static string RawApiVersion = "3.16.2";
+        internal static string RawApiVersion = "3.17.0";
     }
 
     /// <summary>Contains SMAPI's constants and assumptions.</summary>
diff --git a/src/SMAPI/Framework/Content/AssetDataForImage.cs b/src/SMAPI/Framework/Content/AssetDataForImage.cs
index 3393b22f..241c09a8 100644
--- a/src/SMAPI/Framework/Content/AssetDataForImage.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForImage.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Buffers;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.Xna.Framework;
 using Microsoft.Xna.Framework.Graphics;
@@ -32,59 +33,70 @@ namespace StardewModdingAPI.Framework.Content
         /// <inheritdoc />
         public void PatchImage(IRawTextureData source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMode patchMode = PatchMode.Replace)
         {
-            this.GetPatchBounds(ref sourceArea, ref targetArea, source.Width, source.Height);
-
-            // validate source data
             if (source == null)
                 throw new ArgumentNullException(nameof(source), "Can't patch from null source data.");
 
-            // get the pixels for the source area
-            Color[] sourceData;
+            // get normalized bounds
+            this.GetPatchBounds(ref sourceArea, ref targetArea, source.Width, source.Height);
+            if (source.Data.Length < (sourceArea.Value.Bottom - 1) * source.Width + sourceArea.Value.Right)
+                throw new ArgumentException("Can't apply image patch because the source image is smaller than the source area.", nameof(source));
+            int areaX = sourceArea.Value.X;
+            int areaY = sourceArea.Value.Y;
+            int areaWidth = sourceArea.Value.Width;
+            int areaHeight = sourceArea.Value.Height;
+
+            // shortcut: if the area width matches the source image, we can apply the image as-is without needing
+            // to copy the pixels into a smaller subset. It's fine if the source is taller than the area, since we'll
+            // just ignore the extra data at the end of the pixel array.
+            if (areaWidth == source.Width)
+            {
+                this.PatchImageImpl(source.Data, source.Width, source.Height, sourceArea.Value, targetArea.Value, patchMode, areaY);
+                return;
+            }
+
+            // else copy the pixels within the smaller area & apply that
+            int pixelCount = areaWidth * areaHeight;
+            Color[] sourceData = ArrayPool<Color>.Shared.Rent(pixelCount);
+            try
             {
-                int areaX = sourceArea.Value.X;
-                int areaY = sourceArea.Value.Y;
-                int areaWidth = sourceArea.Value.Width;
-                int areaHeight = sourceArea.Value.Height;
-
-                if (areaX == 0 && areaY == 0 && areaWidth == source.Width && areaHeight == source.Height)
-                    sourceData = source.Data;
-                else
+                for (int y = areaY, maxY = areaY + areaHeight; y < maxY; y++)
                 {
-                    sourceData = new Color[areaWidth * areaHeight];
-                    int i = 0;
-                    for (int y = areaY, maxY = areaY + areaHeight - 1; y <= maxY; y++)
-                    {
-                        for (int x = areaX, maxX = areaX + areaWidth - 1; x <= maxX; x++)
-                        {
-                            int targetIndex = (y * source.Width) + x;
-                            sourceData[i++] = source.Data[targetIndex];
-                        }
-                    }
+                    int sourceIndex = (y * source.Width) + areaX;
+                    int targetIndex = (y - areaY) * areaWidth;
+                    Array.Copy(source.Data, sourceIndex, sourceData, targetIndex, areaWidth);
                 }
-            }
 
-            // apply
-            this.PatchImageImpl(sourceData, source.Width, source.Height, sourceArea.Value, targetArea.Value, patchMode);
+                this.PatchImageImpl(sourceData, source.Width, source.Height, sourceArea.Value, targetArea.Value, patchMode);
+            }
+            finally
+            {
+                ArrayPool<Color>.Shared.Return(sourceData);
+            }
         }
 
         /// <inheritdoc />
         public void PatchImage(Texture2D source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMode patchMode = PatchMode.Replace)
         {
-            this.GetPatchBounds(ref sourceArea, ref targetArea, source.Width, source.Height);
-
-            // validate source texture
             if (source == null)
                 throw new ArgumentNullException(nameof(source), "Can't patch from a null source texture.");
+
+            // get normalized bounds
+            this.GetPatchBounds(ref sourceArea, ref targetArea, source.Width, source.Height);
             if (!source.Bounds.Contains(sourceArea.Value))
                 throw new ArgumentOutOfRangeException(nameof(sourceArea), "The source area is outside the bounds of the source texture.");
 
-            // get source data
+            // get source data & apply
             int pixelCount = sourceArea.Value.Width * sourceArea.Value.Height;
-            Color[] sourceData = GC.AllocateUninitializedArray<Color>(pixelCount);
-            source.GetData(0, sourceArea, sourceData, 0, pixelCount);
-
-            // apply
-            this.PatchImageImpl(sourceData, source.Width, source.Height, sourceArea.Value, targetArea.Value, patchMode);
+            Color[] sourceData = ArrayPool<Color>.Shared.Rent(pixelCount);
+            try
+            {
+                source.GetData(0, sourceArea, sourceData, 0, pixelCount);
+                this.PatchImageImpl(sourceData, source.Width, source.Height, sourceArea.Value, targetArea.Value, patchMode);
+            }
+            finally
+            {
+                ArrayPool<Color>.Shared.Return(sourceData);
+            }
         }
 
         /// <inheritdoc />
@@ -94,7 +106,7 @@ namespace StardewModdingAPI.Framework.Content
                 return false;
 
             Texture2D original = this.Data;
-            Texture2D texture = new(Game1.graphics.GraphicsDevice, Math.Max(original.Width, minWidth), Math.Max(original.Height, minHeight));
+            Texture2D texture = new Texture2D(Game1.graphics.GraphicsDevice, Math.Max(original.Width, minWidth), Math.Max(original.Height, minHeight)).SetName(original.Name);
             this.ReplaceWith(texture);
             this.PatchImage(original);
             return true;
@@ -117,15 +129,16 @@ namespace StardewModdingAPI.Framework.Content
 
         /// <summary>Overwrite part of the image.</summary>
         /// <param name="sourceData">The image data to patch into the content.</param>
-        /// <param name="sourceWidth">The pixel width of the source image.</param>
-        /// <param name="sourceHeight">The pixel height of the source image.</param>
+        /// <param name="sourceWidth">The pixel width of the original source image.</param>
+        /// <param name="sourceHeight">The pixel height of the original source image.</param>
         /// <param name="sourceArea">The part of the <paramref name="sourceData"/> to copy (or <c>null</c> to take the whole texture). This must be within the bounds of the <paramref name="sourceData"/> texture.</param>
         /// <param name="targetArea">The part of the content to patch (or <c>null</c> to patch the whole texture). The original content within this area will be erased. This must be within the bounds of the existing spritesheet.</param>
         /// <param name="patchMode">Indicates how an image should be patched.</param>
+        /// <param name="startRow">The row to start on, for the sourceData.</param>
         /// <exception cref="ArgumentNullException">One of the arguments is null.</exception>
         /// <exception cref="ArgumentOutOfRangeException">The <paramref name="targetArea"/> is outside the bounds of the spritesheet.</exception>
         /// <exception cref="InvalidOperationException">The content being read isn't an image.</exception>
-        private void PatchImageImpl(Color[] sourceData, int sourceWidth, int sourceHeight, Rectangle sourceArea, Rectangle targetArea, PatchMode patchMode)
+        private void PatchImageImpl(Color[] sourceData, int sourceWidth, int sourceHeight, Rectangle sourceArea, Rectangle targetArea, PatchMode patchMode, int startRow = 0)
         {
             // get texture
             Texture2D target = this.Data;
@@ -139,24 +152,69 @@ namespace StardewModdingAPI.Framework.Content
             if (sourceArea.Size != targetArea.Size)
                 throw new InvalidOperationException("The source and target areas must be the same size.");
 
-            // merge data
-            if (patchMode == PatchMode.Overlay)
+            // shortcut: replace the entire area
+            if (patchMode == PatchMode.Replace)
+            {
+                target.SetData(0, targetArea, sourceData, startRow * sourceArea.Width, pixelCount);
+                return;
+            }
+
+            // skip transparent pixels at the start & end (e.g. large spritesheet with a few sprites replaced)
+            int startIndex = -1;
+            int endIndex = -1;
+            {
+                for (int i = startRow * sourceArea.Width; i < pixelCount; i++)
+                {
+                    if (sourceData[i].A >= AssetDataForImage.MinOpacity)
+                    {
+                        startIndex = i;
+                        break;
+                    }
+                }
+                if (startIndex == -1)
+                    return; // blank texture
+
+                for (int i = startRow * sourceArea.Width + pixelCount - 1; i >= startIndex; i--)
+                {
+                    if (sourceData[i].A >= AssetDataForImage.MinOpacity)
+                    {
+                        endIndex = i;
+                        break;
+                    }
+                }
+                if (endIndex == -1)
+                    return; // ???
+            }
+
+            // update target rectangle
+            int sourceOffset;
+            {
+                int topOffset = startIndex / sourceArea.Width;
+                int bottomOffset = endIndex / sourceArea.Width;
+
+                targetArea = new(targetArea.X, targetArea.Y + topOffset, targetArea.Width, bottomOffset - topOffset + 1);
+                pixelCount = targetArea.Width * targetArea.Height;
+                sourceOffset = topOffset * sourceArea.Width;
+            }
+
+            // apply
+            Color[] mergedData = ArrayPool<Color>.Shared.Rent(pixelCount);
+            try
             {
-                // get target data
-                Color[] mergedData = GC.AllocateUninitializedArray<Color>(pixelCount);
                 target.GetData(0, targetArea, mergedData, 0, pixelCount);
 
-                // merge pixels
-                for (int i = 0; i < pixelCount; i++)
+                for (int i = startIndex; i <= endIndex; i++)
                 {
+                    int targetIndex = i - sourceOffset;
+
                     Color above = sourceData[i];
-                    Color below = mergedData[i];
+                    Color below = mergedData[targetIndex];
 
                     // shortcut transparency
-                    if (above.A < MinOpacity)
+                    if (above.A < AssetDataForImage.MinOpacity)
                         continue;
-                    if (below.A < MinOpacity)
-                        mergedData[i] = above;
+                    if (below.A < AssetDataForImage.MinOpacity || above.A == byte.MaxValue)
+                        mergedData[targetIndex] = above;
 
                     // merge pixels
                     else
@@ -165,7 +223,7 @@ namespace StardewModdingAPI.Framework.Content
                         // premultiplied by the content pipeline. The formula is derived from
                         // https://blogs.msdn.microsoft.com/shawnhar/2009/11/06/premultiplied-alpha/.
                         float alphaBelow = 1 - (above.A / 255f);
-                        mergedData[i] = new Color(
+                        mergedData[targetIndex] = new Color(
                             r: (int)(above.R + (below.R * alphaBelow)),
                             g: (int)(above.G + (below.G * alphaBelow)),
                             b: (int)(above.B + (below.B * alphaBelow)),
@@ -176,8 +234,10 @@ namespace StardewModdingAPI.Framework.Content
 
                 target.SetData(0, targetArea, mergedData, 0, pixelCount);
             }
-            else
-                target.SetData(0, targetArea, sourceData, 0, pixelCount);
+            finally
+            {
+                ArrayPool<Color>.Shared.Return(mergedData);
+            }
         }
     }
 }
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 9e044b44..cf26307f 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -34,9 +34,6 @@ namespace StardewModdingAPI.Framework
         /// <summary>An asset key prefix for assets from SMAPI mod folders.</summary>
         private readonly string ManagedPrefix = "SMAPI";
 
-        /// <summary>Whether to use raw image data when possible, instead of initializing an XNA Texture2D instance through the GPU.</summary>
-        private readonly bool UseRawImageLoading;
-
         /// <summary>Get a file lookup for the given directory.</summary>
         private readonly Func<string, IFileLookup> GetFileLookup;
 
@@ -139,8 +136,7 @@ namespace StardewModdingAPI.Framework
         /// <param name="getFileLookup">Get a file lookup for the given directory.</param>
         /// <param name="onAssetsInvalidated">A callback to invoke when any asset names have been invalidated from the cache.</param>
         /// <param name="requestAssetOperations">Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</param>
-        /// <param name="useRawImageLoading">Whether to use raw image data when possible, instead of initializing an XNA Texture2D instance through the GPU.</param>
-        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, Action<BaseContentManager, IAssetName> onAssetLoaded, Func<string, IFileLookup> getFileLookup, Action<IList<IAssetName>> onAssetsInvalidated, Func<IAssetInfo, AssetOperationGroup?> requestAssetOperations, bool useRawImageLoading)
+        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, Action<BaseContentManager, IAssetName> onAssetLoaded, Func<string, IFileLookup> getFileLookup, Action<IList<IAssetName>> onAssetsInvalidated, Func<IAssetInfo, AssetOperationGroup?> requestAssetOperations)
         {
             this.GetFileLookup = getFileLookup;
             this.Monitor = monitor ?? throw new ArgumentNullException(nameof(monitor));
@@ -151,7 +147,6 @@ namespace StardewModdingAPI.Framework
             this.OnAssetsInvalidated = onAssetsInvalidated;
             this.RequestAssetOperations = requestAssetOperations;
             this.FullRootDirectory = Path.Combine(Constants.GamePath, rootDirectory);
-            this.UseRawImageLoading = useRawImageLoading;
             this.ContentManagers.Add(
                 this.MainContentManager = new GameContentManager(
                     name: "Game1.content",
@@ -230,8 +225,7 @@ namespace StardewModdingAPI.Framework
                     reflection: this.Reflection,
                     jsonHelper: this.JsonHelper,
                     onDisposing: this.OnDisposing,
-                    fileLookup: this.GetFileLookup(rootDirectory),
-                    useRawImageLoading: this.UseRawImageLoading
+                    fileLookup: this.GetFileLookup(rootDirectory)
                 );
                 this.ContentManagers.Add(manager);
                 return manager;
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 54f8e2a2..1e9f4ffe 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -336,7 +336,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         {
             // track asset key
             if (value is Texture2D texture)
-                texture.Name = assetName.Name;
+                texture.SetName(assetName);
 
             // save to cache
             // Note: even if the asset was loaded and cached right before this method was called,
diff --git a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
index cc6f8372..badbd766 100644
--- a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
@@ -1,9 +1,11 @@
 using System;
+using System.Buffers;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.IO;
 using System.Linq;
+using System.Runtime.CompilerServices;
 using BmFont;
 using Microsoft.Xna.Framework;
 using Microsoft.Xna.Framework.Content;
@@ -28,9 +30,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /*********
         ** Fields
         *********/
-        /// <summary>Whether to use raw image data when possible, instead of initializing an XNA Texture2D instance through the GPU.</summary>
-        private readonly bool UseRawImageLoading;
-
         /// <summary>Encapsulates SMAPI's JSON file parsing.</summary>
         private readonly JsonHelper JsonHelper;
 
@@ -72,15 +71,13 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
         /// <param name="onDisposing">A callback to invoke when the content manager is being disposed.</param>
         /// <param name="fileLookup">A lookup for files within the <paramref name="rootDirectory"/>.</param>
-        /// <param name="useRawImageLoading">Whether to use raw image data when possible, instead of initializing an XNA Texture2D instance through the GPU.</param>
-        public ModContentManager(string name, IContentManager gameContentManager, IServiceProvider serviceProvider, string modName, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action<BaseContentManager> onDisposing, IFileLookup fileLookup, bool useRawImageLoading)
+        public ModContentManager(string name, IContentManager gameContentManager, IServiceProvider serviceProvider, string modName, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action<BaseContentManager> onDisposing, IFileLookup fileLookup)
             : base(name, serviceProvider, rootDirectory, currentCulture, coordinator, monitor, reflection, onDisposing, isNamespaced: true)
         {
             this.GameContentManager = gameContentManager;
             this.FileLookup = fileLookup;
             this.JsonHelper = jsonHelper;
             this.ModName = modName;
-            this.UseRawImageLoading = useRawImageLoading;
 
             this.TryLocalizeKeys = false;
         }
@@ -111,7 +108,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 if (this.Coordinator.TryParseManagedAssetKey(assetName.Name, out string? contentManagerID, out IAssetName? relativePath))
                 {
                     if (contentManagerID != this.Name)
-                        throw this.GetLoadError(assetName, ContentLoadErrorType.AccessDenied, "can't load a different mod's managed asset key through this mod content manager.");
+                        this.ThrowLoadError(assetName, ContentLoadErrorType.AccessDenied, "can't load a different mod's managed asset key through this mod content manager.");
                     assetName = relativePath;
                 }
             }
@@ -123,7 +120,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 // get file
                 FileInfo file = this.GetModFile<T>(assetName.Name);
                 if (!file.Exists)
-                    throw this.GetLoadError(assetName, ContentLoadErrorType.AssetDoesNotExist, "the specified path doesn't exist.");
+                    this.ThrowLoadError(assetName, ContentLoadErrorType.AssetDoesNotExist, "the specified path doesn't exist.");
 
                 // load content
                 asset = file.Extension.ToLower() switch
@@ -141,7 +138,8 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 if (ex is SContentLoadException)
                     throw;
 
-                throw this.GetLoadError(assetName, ContentLoadErrorType.Other, "an unexpected error occurred.", ex);
+                this.ThrowLoadError(assetName, ContentLoadErrorType.Other, "an unexpected error occurred.", ex);
+                return default;
             }
 
             // track & return asset
@@ -189,7 +187,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         private T LoadDataFile<T>(IAssetName assetName, FileInfo file)
         {
             if (!this.JsonHelper.ReadJsonFileIfExists(file.FullName, out T? asset))
-                throw this.GetLoadError(assetName, ContentLoadErrorType.InvalidData, "the JSON file is invalid."); // should never happen since we check for file existence before calling this method
+                this.ThrowLoadError(assetName, ContentLoadErrorType.InvalidData, "the JSON file is invalid."); // should never happen since we check for file existence before calling this method
 
             return asset;
         }
@@ -201,48 +199,52 @@ namespace StardewModdingAPI.Framework.ContentManagers
         private T LoadImageFile<T>(IAssetName assetName, FileInfo file)
         {
             this.AssertValidType<T>(assetName, file, typeof(Texture2D), typeof(IRawTextureData));
-            bool expectsRawData = typeof(T).IsAssignableTo(typeof(IRawTextureData));
-            bool asRawData = expectsRawData || this.UseRawImageLoading;
+            bool returnRawData = typeof(T).IsAssignableTo(typeof(IRawTextureData));
 
 #if SMAPI_DEPRECATED
-            // disable raw data if PyTK will rescale the image (until it supports raw data)
-            if (asRawData && !expectsRawData)
+            if (!returnRawData && this.ShouldDisableIntermediateRawDataLoad<T>(assetName, file))
             {
-                if (ModContentManager.EnablePyTkLegacyMode)
-                {
-                    // PyTK intercepts Texture2D file loads to rescale them (e.g. for HD portraits),
-                    // but doesn't support IRawTextureData loads yet. We can't just check if the
-                    // current file has a '.pytk.json' rescale file though, since PyTK may still
-                    // rescale it if the original asset or another edit gets rescaled.
-                    asRawData = false;
-                    this.Monitor.LogOnce("Enabled compatibility mode for PyTK 1.23.* or earlier. This won't cause any issues, but may impact performance. This will no longer be supported in the upcoming SMAPI 4.0.0.", LogLevel.Warn);
-                }
+                using FileStream stream = File.OpenRead(file.FullName);
+                Texture2D texture = Texture2D.FromStream(Game1.graphics.GraphicsDevice, stream).SetName(assetName);
+                this.PremultiplyTransparency(texture);
+                return (T)(object)texture;
             }
 #endif
 
-            // load
-            if (asRawData)
-            {
-                IRawTextureData raw = this.LoadRawImageData(file, expectsRawData);
+            IRawTextureData raw = this.LoadRawImageData(file, returnRawData);
 
-                if (expectsRawData)
-                    return (T)raw;
-                else
-                {
-                    Texture2D texture = new(Game1.graphics.GraphicsDevice, raw.Width, raw.Height);
-                    texture.SetData(raw.Data);
-                    return (T)(object)texture;
-                }
-            }
+            if (returnRawData)
+                return (T)raw;
             else
             {
-                using FileStream stream = File.OpenRead(file.FullName);
-                Texture2D texture = Texture2D.FromStream(Game1.graphics.GraphicsDevice, stream);
-                texture = this.PremultiplyTransparency(texture);
+                Texture2D texture = new Texture2D(Game1.graphics.GraphicsDevice, raw.Width, raw.Height).SetName(assetName);
+                texture.SetData(raw.Data);
                 return (T)(object)texture;
             }
         }
 
+#if SMAPI_DEPRECATED
+        /// <summary>Get whether to disable loading an image as <see cref="IRawTextureData"/> before building a <see cref="Texture2D"/> instance. This isn't called if the mod requested <see cref="IRawTextureData"/> directly.</summary>
+        /// <typeparam name="T">The type of asset being loaded.</typeparam>
+        /// <param name="assetName">The asset name relative to the loader root directory.</param>
+        /// <param name="file">The file being loaded.</param>
+        private bool ShouldDisableIntermediateRawDataLoad<T>(IAssetName assetName, FileInfo file)
+        {
+            // disable raw data if PyTK will rescale the image (until it supports raw data)
+            if (ModContentManager.EnablePyTkLegacyMode)
+            {
+                // PyTK intercepts Texture2D file loads to rescale them (e.g. for HD portraits),
+                // but doesn't support IRawTextureData loads yet. We can't just check if the
+                // current file has a '.pytk.json' rescale file though, since PyTK may still
+                // rescale it if the original asset or another edit gets rescaled.
+                this.Monitor.LogOnce("Enabled compatibility mode for PyTK 1.23.* or earlier. This won't cause any issues, but may impact performance. This will no longer be supported in the upcoming SMAPI 4.0.0.", LogLevel.Warn);
+                return true;
+            }
+
+            return false;
+        }
+#endif
+
         /// <summary>Load the raw image data from a file on disk.</summary>
         /// <param name="file">The file whose data to load.</param>
         /// <param name="forRawData">Whether the data is being loaded for an <see cref="IRawTextureData"/> (true) or <see cref="Texture2D"/> (false) instance.</param>
@@ -301,7 +303,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         private T LoadXnbFile<T>(IAssetName assetName)
         {
             if (typeof(IRawTextureData).IsAssignableFrom(typeof(T)))
-                throw this.GetLoadError(assetName, ContentLoadErrorType.Other, $"can't read XNB file as type {typeof(IRawTextureData)}; that type can only be read from a PNG file.");
+                this.ThrowLoadError(assetName, ContentLoadErrorType.Other, $"can't read XNB file as type {typeof(IRawTextureData)}; that type can only be read from a PNG file.");
 
             // the underlying content manager adds a .xnb extension implicitly, so
             // we need to strip it here to avoid trying to load a '.xnb.xnb' file.
@@ -326,7 +328,8 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="file">The file to load.</param>
         private T HandleUnknownFileType<T>(IAssetName assetName, FileInfo file)
         {
-            throw this.GetLoadError(assetName, ContentLoadErrorType.InvalidName, $"unknown file extension '{file.Extension}'; must be one of '.fnt', '.json', '.png', '.tbin', '.tmx', or '.xnb'.");
+            this.ThrowLoadError(assetName, ContentLoadErrorType.InvalidName, $"unknown file extension '{file.Extension}'; must be one of '.fnt', '.json', '.png', '.tbin', '.tmx', or '.xnb'.");
+            return default;
         }
 
         /// <summary>Assert that the asset type is compatible with one of the allowed types.</summary>
@@ -338,18 +341,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
         private void AssertValidType<TAsset>(IAssetName assetName, FileInfo file, params Type[] validTypes)
         {
             if (!validTypes.Any(validType => validType.IsAssignableFrom(typeof(TAsset))))
-                throw this.GetLoadError(assetName, ContentLoadErrorType.InvalidData, $"can't read file with extension '{file.Extension}' as type '{typeof(TAsset)}'; must be type '{string.Join("' or '", validTypes.Select(p => p.FullName))}'.");
+                this.ThrowLoadError(assetName, ContentLoadErrorType.InvalidData, $"can't read file with extension '{file.Extension}' as type '{typeof(TAsset)}'; must be type '{string.Join("' or '", validTypes.Select(p => p.FullName))}'.");
         }
 
-        /// <summary>Get an error which indicates that an asset couldn't be loaded.</summary>
+        /// <summary>Throw an error which indicates that an asset couldn't be loaded.</summary>
         /// <param name="errorType">Why loading an asset through the content pipeline failed.</param>
         /// <param name="assetName">The asset name that failed to load.</param>
         /// <param name="reasonPhrase">The reason the file couldn't be loaded.</param>
         /// <param name="exception">The underlying exception, if applicable.</param>
+        /// <exception cref="SContentLoadException" />
+        [DoesNotReturn]
         [DebuggerStepThrough, DebuggerHidden]
-        private SContentLoadException GetLoadError(IAssetName assetName, ContentLoadErrorType errorType, string reasonPhrase, Exception? exception = null)
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        private void ThrowLoadError(IAssetName assetName, ContentLoadErrorType errorType, string reasonPhrase, Exception? exception = null)
         {
-            return new(errorType, $"Failed loading asset '{assetName}' from {this.Name}: {reasonPhrase}", exception);
+            throw new SContentLoadException(errorType, $"Failed loading asset '{assetName}' from {this.Name}: {reasonPhrase}", exception);
         }
 
         /// <summary>Get a file from the mod folder.</summary>
@@ -381,26 +387,32 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="texture">The texture to premultiply.</param>
         /// <returns>Returns a premultiplied texture.</returns>
         /// <remarks>Based on <a href="https://gamedev.stackexchange.com/a/26037">code by David Gouveia</a>.</remarks>
-        private Texture2D PremultiplyTransparency(Texture2D texture)
+        private void PremultiplyTransparency(Texture2D texture)
         {
-            // premultiply pixels
-            Color[] data = GC.AllocateUninitializedArray<Color>(texture.Width * texture.Height);
-            texture.GetData(data);
-            bool changed = false;
-            for (int i = 0; i < data.Length; i++)
+            int count = texture.Width * texture.Height;
+            Color[] data = ArrayPool<Color>.Shared.Rent(count);
+            try
             {
-                Color pixel = data[i];
-                if (pixel.A is (byte.MinValue or byte.MaxValue))
-                    continue; // no need to change fully transparent/opaque pixels
+                texture.GetData(data, 0, count);
 
-                data[i] = new Color(pixel.R * pixel.A / byte.MaxValue, pixel.G * pixel.A / byte.MaxValue, pixel.B * pixel.A / byte.MaxValue, pixel.A); // slower version: Color.FromNonPremultiplied(data[i].ToVector4())
-                changed = true;
-            }
+                bool changed = false;
+                for (int i = 0; i < count; i++)
+                {
+                    ref Color pixel = ref data[i];
+                    if (pixel.A is (byte.MinValue or byte.MaxValue))
+                        continue; // no need to change fully transparent/opaque pixels
 
-            if (changed)
-                texture.SetData(data);
+                    data[i] = new Color(pixel.R * pixel.A / byte.MaxValue, pixel.G * pixel.A / byte.MaxValue, pixel.B * pixel.A / byte.MaxValue, pixel.A); // slower version: Color.FromNonPremultiplied(data[i].ToVector4())
+                    changed = true;
+                }
 
-            return texture;
+                if (changed)
+                    texture.SetData(data, 0, count);
+            }
+            finally
+            {
+                ArrayPool<Color>.Shared.Return(data);
+            }
         }
 
         /// <summary>Fix custom map tilesheet paths so they can be found by the content manager.</summary>
diff --git a/src/SMAPI/Framework/Deprecations/DeprecationManager.cs b/src/SMAPI/Framework/Deprecations/DeprecationManager.cs
index f58f085e..5a5850d1 100644
--- a/src/SMAPI/Framework/Deprecations/DeprecationManager.cs
+++ b/src/SMAPI/Framework/Deprecations/DeprecationManager.cs
@@ -101,7 +101,7 @@ namespace StardewModdingAPI.Framework.Deprecations
             foreach (DeprecationWarning warning in this.QueuedWarnings.OrderBy(p => p.ModName).ThenBy(p => p.NounPhrase))
             {
                 // build message
-                string message = $"{warning.ModName} uses deprecated code ({warning.NounPhrase} is deprecated since SMAPI {warning.Version}).";
+                string message = $"{warning.ModName} uses deprecated code ({warning.NounPhrase}) and will break in the upcoming SMAPI 4.0.0.";
 
                 // get log level
                 LogLevel level;
diff --git a/src/SMAPI/Framework/InternalExtensions.cs b/src/SMAPI/Framework/InternalExtension