Merge branch 'develop' into stable

5 files changed, 464 insertions, 453 deletions

diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 5645c0fa..b2e3ec0f 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -5,6 +5,7 @@ using System.Diagnostics.Contracts;
 using System.Globalization;
 using System.IO;
 using System.Linq;
+using Microsoft.Xna.Framework.Content;
 using Microsoft.Xna.Framework.Graphics;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.Exceptions;
@@ -29,9 +30,15 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>Encapsulates monitoring and logging.</summary>
         protected readonly IMonitor Monitor;
 
+        /// <summary>Simplifies access to private code.</summary>
+        protected readonly Reflector Reflection;
+
         /// <summary>Whether to enable more aggressive memory optimizations.</summary>
         protected readonly bool AggressiveMemoryOptimizations;
 
+        /// <summary>Whether to automatically try resolving keys to a localized form if available.</summary>
+        protected bool TryLocalizeKeys = true;
+
         /// <summary>Whether the content coordinator has been disposed.</summary>
         private bool IsDisposed;
 
@@ -39,7 +46,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         private readonly Action<BaseContentManager> OnDisposing;
 
         /// <summary>A list of disposable assets.</summary>
-        private readonly List<WeakReference<IDisposable>> Disposables = new List<WeakReference<IDisposable>>();
+        private readonly List<WeakReference<IDisposable>> Disposables = new();
 
         /// <summary>The disposable assets tracked by the base content manager.</summary>
         /// <remarks>This should be kept empty to avoid keeping disposable assets referenced forever, which prevents garbage collection when they're unused. Disposable assets are tracked by <see cref="Disposables"/> instead, which avoids a hard reference.</remarks>
@@ -56,7 +63,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         public LanguageCode Language => this.GetCurrentLanguage();
 
         /// <inheritdoc />
-        public string FullRootDirectory => Path.Combine(Constants.ExecutionPath, this.RootDirectory);
+        public string FullRootDirectory => Path.Combine(Constants.GamePath, this.RootDirectory);
 
         /// <inheritdoc />
         public bool IsNamespaced { get; }
@@ -82,51 +89,97 @@ namespace StardewModdingAPI.Framework.ContentManagers
             // init
             this.Name = name;
             this.Coordinator = coordinator ?? throw new ArgumentNullException(nameof(coordinator));
-            this.Cache = new ContentCache(this, reflection);
+            // ReSharper disable once VirtualMemberCallInConstructor -- LoadedAssets isn't overridden by SMAPI or Stardew Valley
+            this.Cache = new ContentCache(this.LoadedAssets);
             this.Monitor = monitor ?? throw new ArgumentNullException(nameof(monitor));
+            this.Reflection = reflection;
             this.OnDisposing = onDisposing;
             this.IsNamespaced = isNamespaced;
             this.AggressiveMemoryOptimizations = aggressiveMemoryOptimizations;
 
             // get asset data
-            this.BaseDisposableReferences = reflection.GetField<List<IDisposable>>(this, "disposableAssets").GetValue();
+            this.BaseDisposableReferences = reflection.GetField<List<IDisposable>?>(this, "disposableAssets").GetValue()
+                ?? throw new InvalidOperationException("Can't initialize content manager: the required 'disposableAssets' field wasn't found.");
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName)
+        public virtual bool DoesAssetExist<T>(IAssetName assetName)
+            where T : notnull
         {
-            return this.Load<T>(assetName, this.Language, useCache: true);
+            return this.Cache.ContainsKey(assetName.Name);
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LanguageCode language)
+        [Obsolete("This method is implemented for the base game and should not be used directly. To load an asset from the underlying content manager directly, use " + nameof(BaseContentManager.RawLoad) + " instead.")]
+        public sealed override T LoadBase<T>(string assetName)
         {
-            return this.Load<T>(assetName, language, useCache: true);
+            return this.Load<T>(assetName, LanguageCode.en);
         }
 
         /// <inheritdoc />
-        public abstract T Load<T>(string assetName, LocalizedContentManager.LanguageCode language, bool useCache);
-
-        /// <inheritdoc />
-        [Obsolete("This method is implemented for the base game and should not be used directly. To load an asset from the underlying content manager directly, use " + nameof(BaseContentManager.RawLoad) + " instead.")]
-        public override T LoadBase<T>(string assetName)
+        public sealed override T Load<T>(string assetName)
         {
-            return this.Load<T>(assetName, LanguageCode.en, useCache: true);
+            return this.Load<T>(assetName, this.Language);
         }
 
         /// <inheritdoc />
-        public virtual void OnLocaleChanged() { }
+        public sealed override T Load<T>(string assetName, LanguageCode language)
+        {
+            assetName = this.PrenormalizeRawAssetName(assetName);
+            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName, allowLocales: this.TryLocalizeKeys);
+            return this.LoadLocalized<T>(parsedName, language, useCache: true);
+        }
 
         /// <inheritdoc />
-        [Pure]
-        public string NormalizePathSeparators(string path)
+        public T LoadLocalized<T>(IAssetName assetName, LanguageCode language, bool useCache)
+            where T : notnull
         {
-            return this.Cache.NormalizePathSeparators(path);
+            // ignore locale in English (or if disabled)
+            if (!this.TryLocalizeKeys || language == LocalizedContentManager.LanguageCode.en)
+                return this.LoadExact<T>(assetName, useCache: useCache);
+
+            // check for localized asset
+            if (!LocalizedContentManager.localizedAssetNames.TryGetValue(assetName.Name, out _))
+            {
+                string localeCode = this.LanguageCodeString(language);
+                IAssetName localizedName = new AssetName(baseName: assetName.BaseName, localeCode: localeCode, languageCode: language);
+
+                try
+                {
+                    T data = this.LoadExact<T>(localizedName, useCache: useCache);
+                    LocalizedContentManager.localizedAssetNames[assetName.Name] = localizedName.Name;
+                    return data;
+                }
+                catch (ContentLoadException)
+                {
+                    localizedName = new AssetName(assetName.BaseName + "_international", null, null);
+                    try
+                    {
+                        T data = this.LoadExact<T>(localizedName, useCache: useCache);
+                        LocalizedContentManager.localizedAssetNames[assetName.Name] = localizedName.Name;
+                        return data;
+                    }
+                    catch (ContentLoadException)
+                    {
+                        LocalizedContentManager.localizedAssetNames[assetName.Name] = assetName.Name;
+                    }
+                }
+            }
+
+            // use cached key
+            string rawName = LocalizedContentManager.localizedAssetNames[assetName.Name];
+            if (assetName.Name != rawName)
+                assetName = this.Coordinator.ParseAssetName(rawName, allowLocales: this.TryLocalizeKeys);
+            return this.LoadExact<T>(assetName, useCache: useCache);
         }
 
         /// <inheritdoc />
+        public abstract T LoadExact<T>(IAssetName assetName, bool useCache)
+            where T : notnull;
+
+        /// <inheritdoc />
         [SuppressMessage("ReSharper", "ParameterOnlyUsedForPreconditionCheck.Local", Justification = "Parameter is only used for assertion checks by design.")]
-        public string AssertAndNormalizeAssetName(string assetName)
+        public string AssertAndNormalizeAssetName(string? assetName)
         {
             // NOTE: the game checks for ContentLoadException to handle invalid keys, so avoid
             // throwing other types like ArgumentException here.
@@ -154,19 +207,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public bool IsLoaded(string assetName, LanguageCode language)
+        public bool IsLoaded(IAssetName assetName)
         {
-            assetName = this.Cache.NormalizeKey(assetName);
-            return this.IsNormalizedKeyLoaded(assetName, language);
+            return this.Cache.ContainsKey(assetName.Name);
         }
 
-        /// <inheritdoc />
-        public IEnumerable<string> GetAssetKeys()
-        {
-            return this.Cache.Keys
-                .Select(this.GetAssetName)
-                .Distinct();
-        }
 
         /****
         ** Cache invalidation
@@ -177,13 +222,13 @@ namespace StardewModdingAPI.Framework.ContentManagers
             IDictionary<string, object> removeAssets = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
             this.Cache.Remove((key, asset) =>
             {
-                this.ParseCacheKey(key, out string assetName, out _);
+                string baseAssetName = this.Coordinator.ParseAssetName(key, allowLocales: this.TryLocalizeKeys).BaseName;
 
                 // check if asset should be removed
-                bool remove = removeAssets.ContainsKey(assetName);
-                if (!remove && predicate(assetName, asset.GetType()))
+                bool remove = removeAssets.ContainsKey(baseAssetName);
+                if (!remove && predicate(baseAssetName, asset.GetType()))
                 {
-                    removeAssets[assetName] = asset;
+                    removeAssets[baseAssetName] = asset;
                     remove = true;
                 }
 
@@ -211,7 +256,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             // dispose uncached assets
             foreach (WeakReference<IDisposable> reference in this.Disposables)
             {
-                if (reference.TryGetTarget(out IDisposable disposable))
+                if (reference.TryGetTarget(out IDisposable? disposable))
                 {
                     try
                     {
@@ -241,78 +286,64 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /*********
         ** Private methods
         *********/
+        /// <summary>Apply initial normalization to a raw asset name before it's parsed.</summary>
+        /// <param name="assetName">The asset name to normalize.</param>
+        [return: NotNullIfNotNull("assetName")]
+        private string? PrenormalizeRawAssetName(string? assetName)
+        {
+            // trim
+            assetName = assetName?.Trim();
+
+            // For legacy reasons, mods can pass .xnb file extensions to the content pipeline which
+            // are then stripped. This will be re-added as needed when reading from raw files.
+            if (assetName?.EndsWith(".xnb") == true)
+                assetName = assetName[..^".xnb".Length];
+
+            return assetName;
+        }
+
+        /// <summary>Normalize path separators in a file path. For asset keys, see <see cref="AssertAndNormalizeAssetName"/> instead.</summary>
+        /// <param name="path">The file path to normalize.</param>
+        [Pure]
+        [return: NotNullIfNotNull("path")]
+        protected string? NormalizePathSeparators(string? path)
+        {
+            return this.Cache.NormalizePathSeparators(path);
+        }
+
         /// <summary>Load an asset file directly from the underlying content manager.</summary>
         /// <typeparam name="T">The type of asset to load.</typeparam>
         /// <param name="assetName">The normalized asset key.</param>
         /// <param name="useCache">Whether to read/write the loaded asset to the asset cache.</param>
-        protected virtual T RawLoad<T>(string assetName, bool useCache)
+        protected virtual T RawLoad<T>(IAssetName assetName, bool useCache)
         {
             return useCache
-                ? base.LoadBase<T>(assetName)
-                : base.ReadAsset<T>(assetName, disposable => this.Disposables.Add(new WeakReference<IDisposable>(disposable)));
+                ? base.LoadBase<T>(assetName.Name)
+                : this.ReadAsset<T>(assetName.Name, disposable => this.Disposables.Add(new WeakReference<IDisposable>(disposable)));
         }
 
         /// <summary>Add tracking data to an asset and add it to the cache.</summary>
         /// <typeparam name="T">The type of asset to inject.</typeparam>
         /// <param name="assetName">The asset path relative to the loader root directory, not including the <c>.xnb</c> extension.</param>
         /// <param name="value">The asset value.</param>
-        /// <param name="language">The language code for which to inject the asset.</param>
         /// <param name="useCache">Whether to save the asset to the asset cache.</param>
-        protected virtual void TrackAsset<T>(string assetName, T value, LanguageCode language, bool useCache)
+        protected virtual void TrackAsset<T>(IAssetName assetName, T value, bool useCache)
+            where T : notnull
         {
             // track asset key
             if (value is Texture2D texture)
-                texture.Name = assetName;
+                texture.Name = assetName.Name;
 
-            // cache asset
+            // save to cache
+            // Note: even if the asset was loaded and cached right before this method was called,
+            // we need to fully re-inject it because a mod editor may have changed the asset in a
+            // way that doesn't change the instance stored in the cache, e.g. using
+            // `asset.ReplaceWith`.
             if (useCache)
-            {
-                assetName = this.AssertAndNormalizeAssetName(assetName);
-                this.Cache[assetName] = value;
-            }
+                this.Cache[assetName.Name] = value;
 
             // avoid hard disposable references; see remarks on the field
             this.BaseDisposableReferences.Clear();
         }
-
-        /// <summary>Parse a cache key into its component parts.</summary>
-        /// <param name="cacheKey">The input cache key.</param>
-        /// <param name="assetName">The original asset name.</param>
-        /// <param name="localeCode">The asset locale code (or <c>null</c> if not localized).</param>
-        protected void ParseCacheKey(string cacheKey, out string assetName, out string localeCode)
-        {
-            // handle localized key
-            if (!string.IsNullOrWhiteSpace(cacheKey))
-            {
-                int lastSepIndex = cacheKey.LastIndexOf(".", StringComparison.Ordinal);
-                if (lastSepIndex >= 0)
-                {
-                    string suffix = cacheKey.Substring(lastSepIndex + 1, cacheKey.Length - lastSepIndex - 1);
-                    if (this.Coordinator.TryGetLanguageEnum(suffix, out _))
-                    {
-                        assetName = cacheKey.Substring(0, lastSepIndex);
-                        localeCode = cacheKey.Substring(lastSepIndex + 1, cacheKey.Length - lastSepIndex - 1);
-                        return;
-                    }
-                }
-            }
-
-            // handle simple key
-            assetName = cacheKey;
-            localeCode = null;
-        }
-
-        /// <summary>Get whether an asset has already been loaded.</summary>
-        /// <param name="normalizedAssetName">The normalized asset name.</param>
-        /// <param name="language">The language to check.</param>
-        protected abstract bool IsNormalizedKeyLoaded(string normalizedAssetName, LanguageCode language);
-
-        /// <summary>Get the asset name from a cache key.</summary>
-        /// <param name="cacheKey">The input cache key.</param>
-        private string GetAssetName(string cacheKey)
-        {
-            this.ParseCacheKey(cacheKey, out string assetName, out string _);
-            return assetName;
-        }
     }
 }
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index ab198076..083df454 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -1,13 +1,14 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.IO;
 using System.Linq;
 using System.Reflection;
-using Microsoft.Xna.Framework.Content;
 using Microsoft.Xna.Framework.Graphics;
+using StardewModdingAPI.Events;
 using StardewModdingAPI.Framework.Content;
-using StardewModdingAPI.Framework.Exceptions;
+using StardewModdingAPI.Framework.Deprecations;
 using StardewModdingAPI.Framework.Reflection;
 using StardewModdingAPI.Framework.Utilities;
 using StardewModdingAPI.Internal;
@@ -24,16 +25,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         ** Fields
         *********/
         /// <summary>The assets currently being intercepted by <see cref="IAssetLoader"/> instances. This is used to prevent infinite loops when a loader loads a new asset.</summary>
-        private readonly ContextHash<string> AssetsBeingLoaded = new ContextHash<string>();
-
-        /// <summary>Interceptors which provide the initial versions of matching assets.</summary>
-        private IList<ModLinked<IAssetLoader>> Loaders => this.Coordinator.Loaders;
-
-        /// <summary>Interceptors which edit matching assets after they're loaded.</summary>
-        private IList<ModLinked<IAssetEditor>> Editors => this.Coordinator.Editors;
-
-        /// <summary>Maps asset names to their localized form, like <c>LooseSprites\Billboard => LooseSprites\Billboard.fr-FR</c> (localized) or <c>Maps\AnimalShop => Maps\AnimalShop</c> (not localized).</summary>
-        private IDictionary<string, string> LocalizedAssetNames => LocalizedContentManager.localizedAssetNames;
+        private readonly ContextHash<string> AssetsBeingLoaded = new();
 
         /// <summary>Whether the next load is the first for any game content manager.</summary>
         private static bool IsFirstLoad = true;
@@ -41,6 +33,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>A callback to invoke the first time *any* game content manager loads an asset.</summary>
         private readonly Action OnLoadingFirstAsset;
 
+        /// <summary>A callback to invoke when an asset is fully loaded.</summary>
+        private readonly Action<BaseContentManager, IAssetName> OnAssetLoaded;
+
 
         /*********
         ** Public methods
@@ -55,15 +50,45 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="reflection">Simplifies access to private code.</param>
         /// <param name="onDisposing">A callback to invoke when the content manager is being disposed.</param>
         /// <param name="onLoadingFirstAsset">A callback to invoke the first time *any* game content manager loads an asset.</param>
+        /// <param name="onAssetLoaded">A callback to invoke when an asset is fully loaded.</param>
         /// <param name="aggressiveMemoryOptimizations">Whether to enable more aggressive memory optimizations.</param>
-        public GameContentManager(string name, IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, Action<BaseContentManager> onDisposing, Action onLoadingFirstAsset, bool aggressiveMemoryOptimizations)
+        public GameContentManager(string name, IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, Action<BaseContentManager> onDisposing, Action onLoadingFirstAsset, Action<BaseContentManager, IAssetName> onAssetLoaded, bool aggressiveMemoryOptimizations)
             : base(name, serviceProvider, rootDirectory, currentCulture, coordinator, monitor, reflection, onDisposing, isNamespaced: false, aggressiveMemoryOptimizations: aggressiveMemoryOptimizations)
         {
             this.OnLoadingFirstAsset = onLoadingFirstAsset;
+            this.OnAssetLoaded = onAssetLoaded;
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LocalizedContentManager.LanguageCode language, bool useCache)
+        public override bool DoesAssetExist<T>(IAssetName assetName)
+        {
+            if (base.DoesAssetExist<T>(assetName))
+                return true;
+
+            // vanilla asset
+            if (File.Exists(Path.Combine(this.RootDirectory, $"{assetName.Name}.xnb")))
+                return true;
+
+            // managed asset
+            if (this.Coordinator.TryParseManagedAssetKey(assetName.Name, out string? contentManagerID, out IAssetName? relativePath))
+                return this.Coordinator.DoesManagedAssetExist<T>(contentManagerID, relativePath);
+
+            // custom asset from a loader
+            string locale = this.GetLocale();
+            IAssetInfo info = new AssetInfo(locale, assetName, typeof(T), this.AssertAndNormalizeAssetName);
+            AssetLoadOperation[] loaders = this.GetLoaders<object>(info).ToArray();
+
+            if (!this.AssertMaxOneRequiredLoader(info, loaders, out string? error))
+            {
+                this.Monitor.Log(error, LogLevel.Warn);
+                return false;
+            }
+
+            return loaders.Any();
+        }
+
+        /// <inheritdoc />
+        public override T LoadExact<T>(IAssetName assetName, bool useCache)
         {
             // raise first-load callback
             if (GameContentManager.IsFirstLoad)
@@ -72,71 +97,45 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 this.OnLoadingFirstAsset();
             }
 
-            // normalize asset name
-            assetName = this.AssertAndNormalizeAssetName(assetName);
-            if (this.TryParseExplicitLanguageAssetKey(assetName, out string newAssetName, out LanguageCode newLanguage))
-                return this.Load<T>(newAssetName, newLanguage, useCache);
-
             // get from cache
-            if (useCache && this.IsLoaded(assetName, language))
-                return this.RawLoad<T>(assetName, language, useCache: true);
+            if (useCache && this.IsLoaded(assetName))
+                return this.RawLoad<T>(assetName, useCache: true);
 
             // get managed asset
-            if (this.Coordinator.TryParseManagedAssetKey(assetName, out string contentManagerID, out string relativePath))
+            if (this.Coordinator.TryParseManagedAssetKey(assetName.Name, out string? contentManagerID, out IAssetName? relativePath))
             {
                 T managedAsset = this.Coordinator.LoadManagedAsset<T>(contentManagerID, relativePath);
-                this.TrackAsset(assetName, managedAsset, language, useCache);
+                this.TrackAsset(assetName, managedAsset, useCache);
                 return managedAsset;
             }
 
             // load asset
             T data;
-            if (this.AssetsBeingLoaded.Contains(assetName))
+            if (this.AssetsBeingLoaded.Contains(assetName.Name))
             {
                 this.Monitor.Log($"Broke loop while loading asset '{assetName}'.", LogLevel.Warn);
                 this.Monitor.Log($"Bypassing mod loaders for this asset. Stack trace:\n{Environment.StackTrace}");
-                data = this.RawLoad<T>(assetName, language, useCache);
+                data = this.RawLoad<T>(assetName, useCache);
             }
             else
             {
-                data = this.AssetsBeingLoaded.Track(assetName, () =>
+                data = this.AssetsBeingLoaded.Track(assetName.Name, () =>
                 {
-                    string locale = this.GetLocale(language);
-                    IAssetInfo info = new AssetInfo(locale, assetName, typeof(T), this.AssertAndNormalizeAssetName);
+                    IAssetInfo info = new AssetInfo(assetName.LocaleCode, assetName, typeof(T), this.AssertAndNormalizeAssetName);
                     IAssetData asset =
                         this.ApplyLoader<T>(info)
-                        ?? new AssetDataForObject(info, this.RawLoad<T>(assetName, language, useCache), this.AssertAndNormalizeAssetName);
+                        ?? new AssetDataForObject(info, this.RawLoad<T>(assetName, useCache), this.AssertAndNormalizeAssetName, this.Reflection);
                     asset = this.ApplyEditors<T>(info, asset);
                     return (T)asset.Data;
                 });
             }
 
-            // update cache & return data
-            this.TrackAsset(assetName, data, language, useCache);
-            return data;
-        }
+            // update cache
+            this.TrackAsset(assetName, data, useCache);
 
-        /// <inheritdoc />
-        public override void OnLocaleChanged()
-        {
-            base.OnLocaleChanged();
-
-            // find assets for which a translatable version was loaded
-            HashSet<string> removeAssetNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-            foreach (string key in this.LocalizedAssetNames.Where(p => p.Key != p.Value).Select(p => p.Key))
-                removeAssetNames.Add(this.TryParseExplicitLanguageAssetKey(key, out string assetName, out _) ? assetName : key);
-
-            // invalidate translatable assets
-            string[] invalidated = this
-                .InvalidateCache((key, type) =>
-                    removeAssetNames.Contains(key)
-                    || (this.TryParseExplicitLanguageAssetKey(key, out string assetName, out _) && removeAssetNames.Contains(assetName))
-                )
-                .Select(p => p.Key)
-                .OrderBy(p => p, StringComparer.OrdinalIgnoreCase)
-                .ToArray();
-            if (invalidated.Any())
-                this.Monitor.Log($"Invalidated {invalidated.Length} asset names: {string.Join(", ", invalidated)} for locale change.");
+            // raise event & return data
+            this.OnAssetLoaded(this, assetName);
+            return data;
         }
 
         /// <inheritdoc />
@@ -149,231 +148,101 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /*********
         ** Private methods
         *********/
-        /// <inheritdoc />
-        protected override bool IsNormalizedKeyLoaded(string normalizedAssetName, LanguageCode language)
-        {
-            string cachedKey = null;
-            bool localized =
-                language != LocalizedContentManager.LanguageCode.en
-                && !this.Coordinator.IsManagedAssetKey(normalizedAssetName)
-                && this.LocalizedAssetNames.TryGetValue(normalizedAssetName, out cachedKey);
-
-            return localized
-                ? this.Cache.ContainsKey(cachedKey)
-                : this.Cache.ContainsKey(normalizedAssetName);
-        }
-
-        /// <inheritdoc />
-        protected override void TrackAsset<T>(string assetName, T value, LanguageCode language, bool useCache)
-        {
-            // handle explicit language in asset name
-            {
-                if (this.TryParseExplicitLanguageAssetKey(assetName, out string newAssetName, out LanguageCode newLanguage))
-                {
-                    this.TrackAsset(newAssetName, value, newLanguage, useCache);
-                    return;
-                }
-            }
-
-            // save to cache
-            // Note: even if the asset was loaded and cached right before this method was called,
-            // we need to fully re-inject it here for two reasons:
-            //   1. So we can look up an asset by its base or localized key (the game/XNA logic
-            //      only caches by the most specific key).
-            //   2. Because a mod asset loader/editor may have changed the asset in a way that
-            //      doesn't change the instance stored in the cache, e.g. using `asset.ReplaceWith`.
-            if (useCache)
-            {
-                string translatedKey = $"{assetName}.{this.GetLocale(language)}";
-                base.TrackAsset(assetName, value, language, useCache: true);
-                if (this.Cache.ContainsKey(translatedKey))
-                    base.TrackAsset(translatedKey, value, language, useCache: true);
-
-                // track whether the injected asset is translatable for is-loaded lookups
-                if (this.Cache.ContainsKey(translatedKey))
-                    this.LocalizedAssetNames[assetName] = translatedKey;
-                else if (this.Cache.ContainsKey(assetName))
-                    this.LocalizedAssetNames[assetName] = assetName;
-                else
-                    this.Monitor.Log($"Asset '{assetName}' could not be found in the cache immediately after injection.", LogLevel.Error);
-            }
-        }
-
-        /// <summary>Load an asset file directly from the underlying content manager.</summary>
-        /// <typeparam name="T">The type of asset to load.</typeparam>
-        /// <param name="assetName">The normalized asset key.</param>
-        /// <param name="language">The language code for which to load content.</param>
-        /// <param name="useCache">Whether to read/write the loaded asset to the asset cache.</param>
-        /// <remarks>Derived from <see cref="LocalizedContentManager.Load{T}(string, LocalizedContentManager.LanguageCode)"/>.</remarks>
-        private T RawLoad<T>(string assetName, LanguageCode language, bool useCache)
+        /// <summary>Load the initial asset from the registered loaders.</summary>
+        /// <param name="info">The basic asset metadata.</param>
+        /// <returns>Returns the loaded asset metadata, or <c>null</c> if no loader matched.</returns>
+        private IAssetData? ApplyLoader<T>(IAssetInfo info)
+            where T : notnull
         {
-            try
+            // find matching loader
+            AssetLoadOperation? loader;
             {
-                // use cached key
-                if (language == this.Language && this.LocalizedAssetNames.TryGetValue(assetName, out string cachedKey))
-                    return base.RawLoad<T>(cachedKey, useCache);
+                AssetLoadOperation[] loaders = this.GetLoaders<T>(info).OrderByDescending(p => p.Priority).ToArray();
 
-                // try translated key
-                if (language != LocalizedContentManager.LanguageCode.en)
+                if (!this.AssertMaxOneRequiredLoader(info, loaders, out string? error))
                 {
-                    string translatedKey = $"{assetName}.{this.GetLocale(language)}";
-                    try
-                    {
-                        T obj = base.RawLoad<T>(translatedKey, useCache);
-                        this.LocalizedAssetNames[assetName] = translatedKey;
-                        return obj;
-                    }
-                    catch (ContentLoadException)
-                    {
-                        this.LocalizedAssetNames[assetName] = assetName;
-                    }
+                    this.Monitor.Log(error, LogLevel.Warn);
+                    return null;
                 }
 
-                // try base asset
-                return base.RawLoad<T>(assetName, useCache);
+                loader = loaders.FirstOrDefault();
             }
-            catch (ContentLoadException ex) when (ex.InnerException is FileNotFoundException innerEx && innerEx.InnerException == null)
-            {
-                throw new SContentLoadException($"Error loading \"{assetName}\": it isn't in the Content folder and no mod provided it.");
-            }
-        }
 
-        /// <summary>Parse an asset key that contains an explicit language into its asset name and language, if applicable.</summary>
-        /// <param name="rawAsset">The asset key to parse.</param>
-        /// <param name="assetName">The asset name without the language code.</param>
-        /// <param name="language">The language code removed from the asset name.</param>
-        /// <returns>Returns whether the asset key contains an explicit language and was successfully parsed.</returns>
-        private bool TryParseExplicitLanguageAssetKey(string rawAsset, out string assetName, out LanguageCode language)
-        {
-            if (string.IsNullOrWhiteSpace(rawAsset))
-                throw new SContentLoadException("The asset key is empty.");
-
-            // extract language code
-            int splitIndex = rawAsset.LastIndexOf('.');
-            if (splitIndex != -1 && this.Coordinator.TryGetLanguageEnum(rawAsset.Substring(splitIndex + 1), out language))
-            {
-                assetName = rawAsset.Substring(0, splitIndex);
-                return true;
-            }
-
-            // no explicit language code found
-            assetName = rawAsset;
-            language = this.Language;
-            return false;
-        }
-
-        /// <summary>Load the initial asset from the registered <see cref="Loaders"/>.</summary>
-        /// <param name="info">The basic asset metadata.</param>
-        /// <returns>Returns the loaded asset metadata, or <c>null</c> if no loader matched.</returns>
-        private IAssetData ApplyLoader<T>(IAssetInfo info)
-        {
-            // find matching loaders
-            var loaders = this.Loaders
-                .Where(entry =>
-                {
-                    try
-                    {
-                        return entry.Data.CanLoad<T>(info);
-                    }
-                    catch (Exception ex)
-                    {
-                        entry.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{info.AssetName}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
-                        return false;
-                    }
-                })
-                .ToArray();
-
-            // validate loaders
-            if (!loaders.Any())
+            // no loader found
+            if (loader == null)
                 return null;
-            if (loaders.Length > 1)
-            {
-                string[] loaderNames = loaders.Select(p => p.Mod.DisplayName).ToArray();
-                this.Monitor.Log($"Multiple mods want to provide the '{info.AssetName}' asset ({string.Join(", ", loaderNames)}), but an asset can't be loaded multiple times. SMAPI will use the default asset instead; uninstall one of the mods to fix this. (Message for modders: you should usually use {typeof(IAssetEditor)} instead to avoid conflicts.)", LogLevel.Warn);
-                return null;
-            }
 
             // fetch asset from loader
-            IModMetadata mod = loaders[0].Mod;
-            IAssetLoader loader = loaders[0].Data;
+            IModMetadata mod = loader.Mod;
             T data;
             try
             {
-                data = loader.Load<T>(info);
-                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.AssetName}'.", LogLevel.Trace);
+                data = (T)loader.GetData(info);
+                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.Name}'{this.GetOnBehalfOfLabel(loader.OnBehalfOf)}.");
             }
             catch (Exception ex)
             {
-                mod.LogAsMod($"Mod crashed when loading asset '{info.AssetName}'. SMAPI will use the default asset instead. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                mod.LogAsMod($"Mod crashed when loading asset '{info.Name}'{this.GetOnBehalfOfLabel(loader.OnBehalfOf)}. SMAPI will use the default asset instead. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 return null;
             }
 
             // return matched asset
-            return this.TryFixAndValidateLoadedAsset(info, data, mod)
-                ? new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName)
+            return this.TryFixAndValidateLoadedAsset(info, data, loader)
+                ? new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName, this.Reflection)
                 : null;
         }
 
-        /// <summary>Apply any <see cref="Editors"/> to a loaded asset.</summary>
+        /// <summary>Apply any editors to a loaded asset.</summary>
         /// <typeparam name="T">The asset type.</typeparam>
         /// <param name="info">The basic asset metadata.</param>
         /// <param name="asset">The loaded asset.</param>
         private IAssetData ApplyEditors<T>(IAssetInfo info, IAssetData asset)
+            where T : notnull
         {
-            IAssetData GetNewData(object data) => new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName);
+            IAssetData GetNewData(object data) => new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName, this.Reflection);
 
             // special case: if the asset was loaded with a more general type like 'object', call editors with the actual type instead.
             {
                 Type actualType = asset.Data.GetType();
-                Type actualOpenType = actualType.IsGenericType ? actualType.GetGenericTypeDefinition() : null;
+                Type?