migrate more internal code to IAssetName (#766)

8 files changed, 131 insertions, 149 deletions

diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 0cdc0736..b255dae1 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -136,7 +136,7 @@ namespace StardewModdingAPI.Framework
             );
             this.ContentManagers.Add(contentManagerForAssetPropagation);
             this.VanillaContentManager = new LocalizedContentManager(serviceProvider, rootDirectory);
-            this.CoreAssets = new CoreAssetPropagator(this.MainContentManager, contentManagerForAssetPropagation, this.Monitor, reflection, aggressiveMemoryOptimizations);
+            this.CoreAssets = new CoreAssetPropagator(this.MainContentManager, contentManagerForAssetPropagation, this.Monitor, reflection, aggressiveMemoryOptimizations, this.ParseAssetName);
             this.LocaleCodes = new Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>>(() => this.GetLocaleCodes(customLanguages: Enumerable.Empty<ModLanguage>()));
         }
 
@@ -260,8 +260,8 @@ namespace StardewModdingAPI.Framework
         }
 
         /// <summary>Get whether this asset is mapped to a mod folder.</summary>
-        /// <param name="key">The asset key.</param>
-        public bool IsManagedAssetKey(string key)
+        /// <param name="key">The asset name.</param>
+        public bool IsManagedAssetKey(IAssetName key)
         {
             return key.StartsWith(this.ManagedPrefix);
         }
@@ -269,9 +269,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>Parse a managed SMAPI asset key which maps to a mod folder.</summary>
         /// <param name="key">The asset key.</param>
         /// <param name="contentManagerID">The unique name for the content manager which should load this asset.</param>
-        /// <param name="relativePath">The relative path within the mod folder.</param>
+        /// <param name="relativePath">The asset name within the mod folder.</param>
         /// <returns>Returns whether the asset was parsed successfully.</returns>
-        public bool TryParseManagedAssetKey(string key, out string contentManagerID, out string relativePath)
+        public bool TryParseManagedAssetKey(string key, out string contentManagerID, out IAssetName relativePath)
         {
             contentManagerID = null;
             relativePath = null;
@@ -285,7 +285,7 @@ namespace StardewModdingAPI.Framework
             if (parts.Length != 3) // managed key prefix, mod id, relative path
                 return false;
             contentManagerID = Path.Combine(parts[0], parts[1]);
-            relativePath = parts[2];
+            relativePath = this.ParseAssetName(parts[2]);
             return true;
         }
 
@@ -299,8 +299,8 @@ namespace StardewModdingAPI.Framework
         /// <summary>Get a copy of an asset from a mod folder.</summary>
         /// <typeparam name="T">The asset type.</typeparam>
         /// <param name="contentManagerID">The unique name for the content manager which should load this asset.</param>
-        /// <param name="relativePath">The internal SMAPI asset key.</param>
-        public T LoadManagedAsset<T>(string contentManagerID, string relativePath)
+        /// <param name="relativePath">The asset name within the mod folder.</param>
+        public T LoadManagedAsset<T>(string contentManagerID, IAssetName relativePath)
         {
             // get content manager
             IContentManager contentManager = this.ContentManagerLock.InReadLock(() =>
@@ -404,7 +404,7 @@ namespace StardewModdingAPI.Framework
         /// <summary>Get all loaded instances of an asset name.</summary>
         /// <param name="assetName">The asset name.</param>
         [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This method is provided for Content Patcher.")]
-        public IEnumerable<object> GetLoadedValues(string assetName)
+        public IEnumerable<object> GetLoadedValues(IAssetName assetName)
         {
             return this.ContentManagerLock.InReadLock(() =>
             {
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 26f0921d..3efc33bb 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -93,36 +93,30 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName)
+        [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)
         {
-            return this.Load<T>(assetName, this.Language, useCache: true);
+            return this.Load<T>(assetName, LanguageCode.en);
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LanguageCode language)
+        public override T Load<T>(string assetName)
         {
-            return this.Load<T>(assetName, language, useCache: true);
+            return this.Load<T>(assetName, this.Language);
         }
 
         /// <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 override T Load<T>(string assetName, LanguageCode language)
         {
-            return this.Load<T>(assetName, LanguageCode.en, useCache: true);
+            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
+            return this.Load<T>(parsedName, language, useCache: true);
         }
 
         /// <inheritdoc />
-        public virtual void OnLocaleChanged() { }
+        public abstract T Load<T>(IAssetName assetName, LanguageCode language, bool useCache);
 
         /// <inheritdoc />
-        [Pure]
-        public string NormalizePathSeparators(string path)
-        {
-            return this.Cache.NormalizePathSeparators(path);
-        }
+        public virtual void OnLocaleChanged() { }
 
         /// <inheritdoc />
         [SuppressMessage("ReSharper", "ParameterOnlyUsedForPreconditionCheck.Local", Justification = "Parameter is only used for assertion checks by design.")]
@@ -154,11 +148,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public bool IsLoaded(string assetName, LanguageCode language)
-        {
-            assetName = this.Cache.NormalizeKey(assetName);
-            return this.IsNormalizedKeyLoaded(assetName, language);
-        }
+        public abstract bool IsLoaded(IAssetName assetName, LanguageCode language);
 
         /****
         ** Cache invalidation
@@ -233,6 +223,14 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /*********
         ** Private methods
         *********/
+        /// <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]
+        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>
@@ -250,26 +248,18 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <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, LanguageCode language, bool useCache)
         {
             // track asset key
             if (value is Texture2D texture)
-                texture.Name = assetName;
+                texture.Name = assetName.Name;
 
             // cache asset
             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>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);
     }
 }
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 0ca9e277..9f686f97 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -63,7 +63,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LocalizedContentManager.LanguageCode language, bool useCache)
+        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
         {
             // raise first-load callback
             if (GameContentManager.IsFirstLoad)
@@ -73,50 +73,63 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
 
             // normalize asset name
-            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
-            if (parsedName.LanguageCode.HasValue)
-                return this.Load<T>(parsedName.BaseName, parsedName.LanguageCode.Value, useCache);
+            if (assetName.LanguageCode.HasValue)
+                return this.Load<T>(this.Coordinator.ParseAssetName(assetName.BaseName), assetName.LanguageCode.Value, useCache);
 
             // get from cache
-            if (useCache && this.IsLoaded(parsedName.Name, language))
-                return this.RawLoad<T>(parsedName.Name, language, useCache: true);
+            if (useCache && this.IsLoaded(assetName, language))
+                return this.RawLoad<T>(assetName, language, useCache: true);
 
             // get managed asset
-            if (this.Coordinator.TryParseManagedAssetKey(parsedName.Name, 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(parsedName.Name, managedAsset, language, useCache);
+                this.TrackAsset(assetName, managedAsset, language, useCache);
                 return managedAsset;
             }
 
             // load asset
             T data;
-            if (this.AssetsBeingLoaded.Contains(parsedName.Name))
+            if (this.AssetsBeingLoaded.Contains(assetName.Name))
             {
-                this.Monitor.Log($"Broke loop while loading asset '{parsedName.Name}'.", LogLevel.Warn);
+                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>(parsedName.Name, language, useCache);
+                data = this.RawLoad<T>(assetName, language, useCache);
             }
             else
             {
-                data = this.AssetsBeingLoaded.Track(parsedName.Name, () =>
+                data = this.AssetsBeingLoaded.Track(assetName.Name, () =>
                 {
                     string locale = this.GetLocale(language);
-                    IAssetInfo info = new AssetInfo(locale, parsedName, typeof(T), this.AssertAndNormalizeAssetName);
+                    IAssetInfo info = new AssetInfo(locale, assetName, typeof(T), this.AssertAndNormalizeAssetName);
                     IAssetData asset =
                         this.ApplyLoader<T>(info)
-                        ?? new AssetDataForObject(info, this.RawLoad<T>(parsedName.Name, language, useCache), this.AssertAndNormalizeAssetName);
+                        ?? new AssetDataForObject(info, this.RawLoad<T>(assetName, language, useCache), this.AssertAndNormalizeAssetName);
                     asset = this.ApplyEditors<T>(info, asset);
                     return (T)asset.Data;
                 });
             }
 
             // update cache & return data
-            this.TrackAsset(parsedName.Name, data, language, useCache);
+            this.TrackAsset(assetName, data, language, useCache);
             return data;
         }
 
         /// <inheritdoc />
+        public override bool IsLoaded(IAssetName assetName, LanguageCode language)
+        {
+            string cachedKey = null;
+            bool localized =
+                language != LanguageCode.en
+                && !this.Coordinator.IsManagedAssetKey(assetName)
+                && this.LocalizedAssetNames.TryGetValue(assetName.Name, out cachedKey);
+
+            return localized
+                ? this.Cache.ContainsKey(cachedKey)
+                : this.Cache.ContainsKey(assetName.Name);
+        }
+
+        /// <inheritdoc />
         public override void OnLocaleChanged()
         {
             base.OnLocaleChanged();
@@ -153,28 +166,13 @@ 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)
+        protected override void TrackAsset<T>(IAssetName assetName, T value, LanguageCode language, bool useCache)
         {
             // handle explicit language in asset name
             {
-                IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
-                if (parsedName.LanguageCode.HasValue)
+                if (assetName.LanguageCode.HasValue)
                 {
-                    this.TrackAsset(parsedName.BaseName, value, parsedName.LanguageCode.Value, useCache);
+                    this.TrackAsset(this.Coordinator.ParseAssetName(assetName.BaseName), value, assetName.LanguageCode.Value, useCache);
                     return;
                 }
             }
@@ -188,16 +186,16 @@ namespace StardewModdingAPI.Framework.ContentManagers
             //      doesn't change the instance stored in the cache, e.g. using `asset.ReplaceWith`.
             if (useCache)
             {
-                string translatedKey = $"{assetName}.{this.GetLocale(language)}";
+                IAssetName translatedKey = new AssetName(assetName.Name, this.GetLocale(language), language);
                 base.TrackAsset(assetName, value, language, useCache: true);
-                if (this.Cache.ContainsKey(translatedKey))
+                if (this.Cache.ContainsKey(translatedKey.Name))
                     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;
+                if (this.Cache.ContainsKey(translatedKey.Name))
+                    this.LocalizedAssetNames[assetName.Name] = translatedKey.Name;
+                else if (this.Cache.ContainsKey(assetName.Name))
+                    this.LocalizedAssetNames[assetName.Name] = assetName.Name;
                 else
                     this.Monitor.Log($"Asset '{assetName}' could not be found in the cache immediately after injection.", LogLevel.Error);
             }
@@ -209,32 +207,32 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <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)
+        private T RawLoad<T>(IAssetName assetName, LanguageCode language, bool useCache)
         {
             try
             {
                 // use cached key
-                if (language == this.Language && this.LocalizedAssetNames.TryGetValue(assetName, out string cachedKey))
+                if (language == this.Language && this.LocalizedAssetNames.TryGetValue(assetName.Name, out string cachedKey))
                     return base.RawLoad<T>(cachedKey, useCache);
 
                 // try translated key
-                if (language != LocalizedContentManager.LanguageCode.en)
+                if (language != LanguageCode.en)
                 {
                     string translatedKey = $"{assetName}.{this.GetLocale(language)}";
                     try
                     {
                         T obj = base.RawLoad<T>(translatedKey, useCache);
-                        this.LocalizedAssetNames[assetName] = translatedKey;
+                        this.LocalizedAssetNames[assetName.Name] = translatedKey;
                         return obj;
                     }
                     catch (ContentLoadException)
                     {
-                        this.LocalizedAssetNames[assetName] = assetName;
+                        this.LocalizedAssetNames[assetName.Name] = assetName.Name;
                     }
                 }
 
                 // try base asset
-                return base.RawLoad<T>(assetName, useCache);
+                return base.RawLoad<T>(assetName.Name, useCache);
             }
             catch (ContentLoadException ex) when (ex.InnerException is FileNotFoundException innerEx && innerEx.InnerException == null)
             {
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs b/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
index 61683ce6..206ece30 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
@@ -25,7 +25,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             : base(name, serviceProvider, rootDirectory, currentCulture, coordinator, monitor, reflection, onDisposing, onLoadingFirstAsset, aggressiveMemoryOptimizations) { }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LanguageCode language, bool useCache)
+        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
         {
             T data = base.Load<T>(assetName, language, useCache);
 
diff --git a/src/SMAPI/Framework/ContentManagers/IContentManager.cs b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
index ba7dbc06..fe0519b6 100644
--- a/src/SMAPI/Framework/ContentManagers/IContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
@@ -1,6 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.Diagnostics.Contracts;
 using Microsoft.Xna.Framework.Content;
 using StardewModdingAPI.Framework.Exceptions;
 using StardewValley;
@@ -31,15 +30,10 @@ namespace StardewModdingAPI.Framework.ContentManagers
         *********/
         /// <summary>Load an asset that has been processed by the content pipeline.</summary>
         /// <typeparam name="T">The type of asset to load.</typeparam>
-        /// <param name="assetName">The asset path relative to the loader root directory, not including the <c>.xnb</c> extension.</param>
+        /// <param name="assetName">The asset name relative to the loader root directory.</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>
-        T Load<T>(string assetName, LocalizedContentManager.LanguageCode language, bool useCache);
-
-        /// <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]
-        string NormalizePathSeparators(string path);
+        T Load<T>(IAssetName assetName, LocalizedContentManager.LanguageCode language, bool useCache);
 
         /// <summary>Assert that the given key has a valid format and return a normalized form consistent with the underlying cache.</summary>
         /// <param name="assetName">The asset key to check.</param>
@@ -56,7 +50,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>Get whether the content manager has already loaded and cached the given asset.</summary>
         /// <param name="assetName">The asset path relative to the loader root directory, not including the <c>.xnb</c> extension.</param>
         /// <param name="language">The language.</param>
-        bool IsLoaded(string assetName, LocalizedContentManager.LanguageCode language);
+        bool IsLoaded(IAssetName assetName, LocalizedContentManager.LanguageCode language);
 
         /// <summary>Purge matched assets from the cache.</summary>
         /// <param name="predicate">Matches the asset keys to invalidate.</param>
diff --git a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
index 2c47f14c..267146ad 100644
--- a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
@@ -66,21 +66,19 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <inheritdoc />
         public override T Load<T>(string assetName)
         {
-            return this.Load<T>(assetName, this.DefaultLanguage, useCache: false);
+            return this.Load<T>(assetName, this.DefaultLanguage);
         }
 
         /// <inheritdoc />
         public override T Load<T>(string assetName, LanguageCode language)
         {
-            return this.Load<T>(assetName, language, useCache: false);
+            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
+            return this.Load<T>(parsedName, language, useCache: false);
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LanguageCode language, bool useCache)
+        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
         {
-            // normalize key
-            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
-
             // disable caching
             // This is necessary to avoid assets being shared between content managers, which can
             // cause changes to an asset through one content manager affecting the same asset in
@@ -96,21 +94,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
 
             // resolve managed asset key
             {
-                if (this.Coordinator.TryParseManagedAssetKey(parsedName.Name, out string contentManagerID, out string relativePath))
+                if (this.Coordinator.TryParseManagedAssetKey(assetName.Name, out string contentManagerID, out IAssetName relativePath))
                 {
                     if (contentManagerID != this.Name)
-                        throw new SContentLoadException($"Can't load managed asset key '{parsedName}' through content manager '{this.Name}' for a different mod.");
-                    parsedName = this.Coordinator.ParseAssetName(relativePath);
+                        throw new SContentLoadException($"Can't load managed asset key '{assetName}' through content manager '{this.Name}' for a different mod.");
+                    assetName = relativePath;
                 }
             }
 
             // get local asset
-            SContentLoadException GetContentError(string reasonPhrase) => new SContentLoadException($"Failed loading asset '{parsedName}' from {this.Name}: {reasonPhrase}");
+            SContentLoadException GetContentError(string reasonPhrase) => new($"Failed loading asset '{assetName}' from {this.Name}: {reasonPhrase}");
             T asset;
             try
             {
                 // get file
-                FileInfo file = this.GetModFile(parsedName.Name);
+                FileInfo file = this.GetModFile(assetName.Name);
                 if (!file.Exists)
                     throw GetContentError("the specified path doesn't exist.");
 
@@ -122,7 +120,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                         {
                             // 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.
-                            string loadName = parsedName.Name[..^".xnb".Length];
+                            string loadName = assetName.Name[..^".xnb".Length];
 
                             // load asset
                             asset = this.RawLoad<T>(loadName, useCache: false);
@@ -177,8 +175,8 @@ namespace StardewModdingAPI.Framework.ContentManagers
                             // fetch & cache
                             FormatManager formatManager = FormatManager.Instance;
                             Map map = formatManager.LoadMap(file.FullName);
-                            map.assetPath = parsedName.Name;
-                            this.FixTilesheetPaths(map, relativeMapPath: parsedName.Name, fixEagerPathPrefixes: false);
+                            map.assetPath = assetName.Name;
+                            this.FixTilesheetPaths(map, relativeMapPath: assetName.Name, fixEagerPathPrefixes: false);
                             asset = (T)(object)map;
                         }
                         break;
@@ -189,15 +187,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
             catch (Exception ex) when (!(ex is SContentLoadException))
             {
-                throw new SContentLoadException($"The content manager failed loading content asset '{parsedName}' from {this.Name}.", ex);
+                throw new SContentLoadException($"The content manager failed loading content asset '{assetName}' from {this.Name}.", ex);
             }
 
             // track & return asset
-            this.TrackAsset(parsedName.Name, asset, language, useCache);
+            this.TrackAsset(assetName, asset, language, useCache);
             return asset;
         }
 
         /// <inheritdoc />
+        public override bool IsLoaded(IAssetName assetName, LanguageCode language)
+        {
+            return this.Cache.ContainsKey(assetName.Name);
+        }
+
+        /// <inheritdoc />
         public override LocalizedContentManager CreateTemporary()
         {
             throw new NotSupportedException("Can't create a temporary mod content manager.");
@@ -206,23 +210,19 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>Get the underlying key in the game's content cache for an asset. This does not validate whether the asset exists.</summary>
         /// <param name="key">The local path to a content file relative to the mod folder.</param>
         /// <exception cref="ArgumentException">The <paramref name="key"/> is empty or contains invalid characters.</exception>
-        public string GetInternalAssetKey(string key)
+        public IAssetName GetInternalAssetKey(string key)
         {
             FileInfo file = this.GetModFile(key);
             string relativePath = PathUtilities.GetRelativePath(this.RootDirectory, file.FullName);
-            return Path.Combine(this.Name, relativePath);
+            string internalKey = Path.Combine(this.Name, relativePath);
+
+            return this.Coordinator.ParseAssetName(internalKey);
         }
 
 
         /*********
         ** Private methods
         *********/
-        /// <inheritdoc />
-        protected override bool IsNormalizedKeyLoaded(string normalizedAssetName, LanguageCode language)
-        {
-            return this.Cache.ContainsKey(normalizedAssetName);
-        }
-
         /// <summary>Get a file from the mod folder.</summary>
         /// <param name="path">The asset path relative to the content folder.</param>
         private FileInfo GetModFile(string path)
@@ -304,15 +304,15 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 // load best match
                 try
                 {
-                    if (!this.TryGetTilesheetAssetName(relativeMapFolder, imageSource, out string assetName, out string error))
+                    if (!this.TryGetTilesheetAssetName(relativeMapFolder, imageSource, out IAssetName assetName, out string error))
                         throw new SContentLoadException($"{errorPrefix} {error}");
 
-                    if (assetName != tilesheet.ImageSource)
+                    if (!assetName.IsEquivalentTo(tilesheet.ImageSource))
                         this.Monitor.VerboseLog($"   Mapped tilesheet '{tilesheet.ImageSource}' to '{assetName}'.");
 
-                    tilesheet.ImageSource = assetName;
+                    tilesheet.ImageSource = assetName.Name;
                 }
-                catch (Exception ex) when (!(ex is SContentLoadException))
+                catch (Exception ex) when (ex is not SContentLoadException)
                 {
                     throw new SContentLoadException($"{errorPrefix} The tilesheet couldn't be loaded.", ex);
                 }
@@ -326,7 +326,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="error">A message indicating why the file couldn't be loaded.</param>
         /// <returns>Returns whether the asset name was found.</returns>
         /// <remarks>See remarks on <see cref="FixTilesheetPaths"/>.</remarks>
-        private bool TryGetTilesheetAssetName(string modRelativeMapFolder, string relativePath, out string assetName, out string error)
+        private bool TryGetTilesheetAssetName(string modRelativeMapFolder, string relativePath, out IAssetName assetName, out string error)
         {
             assetName = null;
             error = null;
@@ -334,7 +334,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             // nothing to do
             if (string.IsNullOrWhiteSpace(relativePath))
             {
-                assetName = relativePath;
+                assetName = null;
                 return true;
             }
 
@@ -358,7 +358,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
 
             // get from game assets
-            string contentKey = this.GetContentKeyForTilesheetImageSource(relativePath);
+            IAssetName contentKey = this.Coordinator.ParseAssetName(this.GetContentKeyForTilesheetImageSource(relativePath));
             try
             {
                 this.GameContentManager.Load<Texture2D>(contentKey, this.Language, useCache: true); // no need to bypass cache here, since we're not storing the asset
@@ -374,7 +374,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 // if the content file doesn't exist, that doesn't mean the error here is a
                 // content-not-found error. Unfortunately XNA doesn't provide a good way to
                 // detect the error type.
-                if (this.GetContentFolderFileExists(contentKey))
+                if (this.GetContentFolderFileExists(contentKey.Name))
                     throw;
             }
 
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index a01248a8..4e522c8d 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -80,16 +80,18 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <inheritdoc />
         public T Load<T>(string key, ContentSource source = ContentSource.ModFolder)
         {
+            IAssetName assetName = this.ContentCore.ParseAssetName(key);
+
             try
             {
                 this.AssertAndNormalizeAssetName(key);
                 switch (source)
                 {
                     case ContentSource.GameContent:
-                        return this.GameContentManager.Load<T>(key, this.CurrentLocaleConstant, useCache: false);
+                        return this.GameContentManager.Load<T>(assetName, this.CurrentLocaleConstant, useCache: false);
 
                     case ContentSource.ModFolder:
-                        return this.ModContentManager.Load<T>(key, Constants.DefaultLanguage, useCache: false);
+                        return this.ModContentManager.Load<T>(assetName, Constants.DefaultLanguage, useCache: false);
 
                     default:
                         throw new SContentLoadException($"{this.ModName} failed loading content asset '{key}' from {source}: unknown content source '{source}'.");
@@ -117,7 +119,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
                     return this.GameContentManager.AssertAndNormalizeAssetName(key);
 
                 case ContentSource.ModFolder:
-                    return this.ModContentManager.GetInternalAssetKey(key);
+                    return this.ModContentManager.GetInternalAssetKey(key).Name;
 
                 default:
                     throw new NotSupportedException($"Unknown content source '{source}'.");
diff --git a/src/SMAPI/Metadata/CoreAssetPropagator.cs b/src/SMAPI/Metadata/CoreAssetPropagator.cs
index e7fac578..f645470e 100644
--- a/src/SMAPI/Metadata/CoreAssetPropagator.cs
+++ b/src/SMAPI/Metadata/CoreAssetPropagator.cs
@@ -45,8 +45,8 @@ namespace StardewModdingAPI.Metadata
         /// <summary>Whether to enable more aggressive memory optimizations.</summary>
         private readonly bool AggressiveMemoryOptimizations;
 
-        /// <summary>Normalizes an asset key to match the cache key and assert that it's valid.</summary>
-        private readonly Func<string, string> AssertAndNormalizeAssetName;
+        /// <summary>Parse a raw asset name.</summary>
+        private readonly Func<string, IAssetName> ParseAssetName;
 
         /// <summary>Optimized bucket categories for batch reloading assets.</summary>
         private enum AssetBucket
@@ -71,15 +71,15 @@ namespace StardewModdingAPI.Metadata
         /// <param name="monitor">Writes messages to the console.</param>
         /// <param name="reflection">Simplifies access to private code.</param>
         /// <param name="aggressiveMemoryOptimizations">Whether to enable more aggressive memory optimizations.</param>
-        public CoreAssetPropagator(LocalizedContentManager mainContent, GameContentManagerForAssetPropagation disposableContent, IMonitor monitor, Reflector reflection, bool aggressiveMemoryOptimizations)
+        /// <param name="parseAssetName">Parse a raw asset name.</param>
+        public CoreAssetPropagator(LocalizedContentManager mainContent, GameContentManagerForAssetPropagation disposableContent, IMonitor monitor, Reflector reflection, bool aggressiveMemoryOptimizations, Func<string, IAssetName> parseAssetName)
         {
             this.MainContentManager = mainContent;
             this.DisposableContentManager = disposableContent;
             this.Monitor = monitor;
             this.Reflection = reflection;
             this.AggressiveMemoryOptimizations = aggressiveMemoryOptimizations;
-
-            this.AssertAndNormalizeAssetName = disposableContent.AssertAndNormalizeAssetName;
+            this.ParseAssetName = parseAssetName;
         }
 
         /// <summary>Reload one of the game's core assets (if applicable).</summary>
@@ -955,13 +955,12 @@ namespace StardewModdingAPI.Metadata
         private void ReloadNpcSprites(IEnumerable<IAssetName> keys, IDictionary<IAssetName, bool> propagated)
         {
             // get NPCs
-            IDictionary<string, IAssetName> lookup = keys.ToDictionary(p => p.Name, StringComparer.OrdinalIgnoreCase);
             var characters =
                 (
                     from npc in this.GetCharacters()
-                    let key = this.NormalizeAssetNameIgnoringEmpty(npc.Sprite?.Texture?.Name)
-                    where key != null && lookup.ContainsKey(key)
-                    select new { Npc = npc, AssetName = lookup[key] }
+                    let key = this.ParseAssetNameOrNull(npc.Sprite?.Texture?.Name)
+                    where key != null && propagated.ContainsKey(key)
+                    select new { Npc = npc, AssetName = key }
                 )
                 .ToArray();
             if (!characters.Any())
@@ -981,26 +980,25 @@ namespace StardewModdingAPI.Metadata
         private void ReloadNpcPortraits(IEnumerable<IAssetName> keys, IDictionary<IAssetName, bool> propagated)
         {
             // get NPCs
-            IDictionary<string, IAssetName> lookup = keys.ToDictionary(p => p.Name, StringComparer.OrdinalIgnoreCase);
             var characters =
                 (
                     from npc in this.GetCharacters()
                     where npc.isVillager()
 
-                    let key = this.NormalizeAssetNameIgnoringEmpty(npc.Portrait?.Name)
-                    where key != null && lookup.ContainsKey(key)
-                    select new { Npc = npc, AssetName = lookup[key] }
+                    let key = this.ParseAssetNameOrNull(npc.Portrait?.Name)
+                    where key != null && propagated.ContainsKey(key)
+                    select new { Npc = npc, AssetName = key }
                 )
                 .ToList();
 
             // special case: Gil is a private NPC field on the AdventureGuild class (only used for the portrait)
             {
-                string gilKey = this.NormalizeAssetNameIgnoringEmpty("Portraits/Gil");
-                if (lookup.TryGetValue(gilKey, out IAssetName assetName))
+                IAssetName gilKey = this.ParseAssetName("Portraits/Gil");
+                if (propagated.ContainsKey(gilKey))
                 {
                     GameLocation adventureGuild = Game1.getLocationFromName("AdventureGuild");
                     if (adventureGuild != null)
-                        characters.Add(new { Npc = this.Reflection.GetField<NPC>(adventureGuild, "Gil").GetValue(), AssetName = assetName });
+                        characters.Add(new { Npc = this.Reflection.GetField<NPC>(adventureGuild, "Gil").GetValue(), AssetName = gilKey });
                 }
             }
 
@@ -1234,12 +1232,12 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Normalize an asset key to match the cache key and assert that it's valid, but don't raise an error for null or empty values.</summary>
         /// <param name="path">The asset key to normalize.</param>
-        private string NormalizeAssetNameIgnoringEmpty(string path)
+        private IAssetName ParseAssetNameOrNull(string path)
         {
             if (string.IsNullOrWhiteSpace(path))
                 return null;
 
-            return this.AssertAndNormalizeAssetName(path);
+            return this.ParseAssetName(path);
         }
 
         /// <summary>Get the segments in a path (e.g. 'a/b' is 'a' and 'b').</summary>