add AssetName to encapsulate asset name handling (#766)

19 files changed, 736 insertions, 316 deletions

diff --git a/docs/release-notes.md b/docs/release-notes.md
index d549b99c..b84f8a06 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -6,6 +6,8 @@
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
 
 * For mod authors:
+  * Added `IAssetName` field to the asset info received by `IAssetEditor` and `IAssetLoader` methods.  
+    _This provides utility methods for working with asset names, parsed locales, etc. The `asset.AssetNameEquals` method is now deprecated in favor of `asset.Name.IsEquivalentTo`_.
   * The `SDate` constructor is no longer case-sensitive for season names.
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
diff --git a/src/SMAPI.Tests/Core/AssetNameTests.cs b/src/SMAPI.Tests/Core/AssetNameTests.cs
new file mode 100644
index 00000000..8785aab8
--- /dev/null
+++ b/src/SMAPI.Tests/Core/AssetNameTests.cs
@@ -0,0 +1,295 @@
+using System;
+using System.Collections.Generic;
+using FluentAssertions;
+using NUnit.Framework;
+using StardewModdingAPI;
+using StardewModdingAPI.Framework.Content;
+using StardewModdingAPI.Toolkit.Utilities;
+using StardewValley;
+
+namespace SMAPI.Tests.Core
+{
+    /// <summary>Unit tests for <see cref="AssetName"/>.</summary>
+    [TestFixture]
+    internal class AssetNameTests
+    {
+        /*********
+        ** Unit tests
+        *********/
+        /****
+        ** Constructor
+        ****/
+        [Test(Description = $"Assert that the {nameof(AssetName)} constructor creates an instance with the expected values.")]
+        [TestCase("SimpleName", "SimpleName", null, null)]
+        [TestCase("Data/Achievements", "Data/Achievements", null, null)]
+        [TestCase("Characters/Dialogue/Abigail", "Characters/Dialogue/Abigail", null, null)]
+        [TestCase("Characters/Dialogue/Abigail.fr-FR", "Characters/Dialogue/Abigail", "fr-FR", LocalizedContentManager.LanguageCode.fr)]
+        [TestCase("Characters/Dialogue\\Abigail.fr-FR", "Characters/Dialogue/Abigail.fr-FR", null, null)]
+        [TestCase("Characters/Dialogue/Abigail.fr-FR", "Characters/Dialogue/Abigail", "fr-FR", LocalizedContentManager.LanguageCode.fr)]
+        public void Constructor_Valid(string name, string expectedBaseName, string expectedLocale, LocalizedContentManager.LanguageCode? expectedLanguageCode)
+        {
+            // arrange
+            name = PathUtilities.NormalizeAssetName(name);
+
+            // act
+            string calledWithLocale = null;
+            IAssetName assetName = AssetName.Parse(name, parseLocale: locale => expectedLanguageCode);
+
+            // assert
+            assetName.Name.Should()
+                .NotBeNull()
+                .And.Be(name.Replace("\\", "/"));
+            assetName.BaseName.Should()
+                .NotBeNull()
+                .And.Be(expectedBaseName);
+            assetName.LocaleCode.Should()
+                .Be(expectedLocale);
+            assetName.LanguageCode.Should()
+                .Be(expectedLanguageCode);
+        }
+
+        [Test(Description = $"Assert that the {nameof(AssetName)} constructor throws an exception if the value is invalid.")]
+        [TestCase(null)]
+        [TestCase("")]
+        [TestCase(" ")]
+        [TestCase("\t")]
+        [TestCase("  \t   ")]
+        public void Constructor_NullOrWhitespace(string name)
+        {
+            // act
+            ArgumentException exception = Assert.Throws<ArgumentException>(() => _ = AssetName.Parse(name, null));
+
+            // assert
+            exception!.ParamName.Should().Be("rawName");
+            exception.Message.Should().Be("The asset name can't be null or empty. (Parameter 'rawName')");
+        }
+
+
+        /****
+        ** IsEquivalentTo
+        ****/
+        [Test(Description = $"Assert that {nameof(AssetName.IsEquivalentTo)} compares names as expected when the locale is included.")]
+
+        // exact match (ignore case)
+        [TestCase("Data/Achievements", "Data/Achievements", ExpectedResult = true)]
+        [TestCase("DATA/achievements", "data/ACHIEVEMENTS", ExpectedResult = true)]
+
+        // exact match (ignore formatting)
+        [TestCase("Data/Achievements", "Data\\Achievements", ExpectedResult = true)]
+        [TestCase("DATA\\achievements", "data/ACHIEVEMENTS", ExpectedResult = true)]
+        [TestCase("DATA\\\\achievements", "data////ACHIEVEMENTS", ExpectedResult = true)]
+
+        // whitespace-sensitive
+        [TestCase("Data/Achievements", " Data/Achievements ", ExpectedResult = false)]
+        [TestCase(" Data/Achievements ", "Data/Achievements", ExpectedResult = false)]
+
+        // other is null or whitespace
+        [TestCase("Data/Achievements", null, ExpectedResult = false)]
+        [TestCase("Data/Achievements", "", ExpectedResult = false)]
+        [TestCase("Data/Achievements", "   ", ExpectedResult = false)]
+
+        // with locale codes
+        [TestCase("Data/Achievements", "Data/Achievements.fr-FR", ExpectedResult = false)]
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements", ExpectedResult = false)]
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements.fr-FR", ExpectedResult = true)]
+        public bool IsEquivalentTo_Name(string mainAssetName, string otherAssetName)
+        {
+            // arrange
+            mainAssetName = PathUtilities.NormalizeAssetName(mainAssetName);
+
+            // act
+            AssetName name = AssetName.Parse(mainAssetName, _ => LocalizedContentManager.LanguageCode.fr);
+
+            // assert
+            return name.IsEquivalentTo(otherAssetName);
+        }
+
+        [Test(Description = $"Assert that {nameof(AssetName.IsEquivalentTo)} compares names as expected when the locale is excluded.")]
+
+        // a few samples from previous test to make sure
+        [TestCase("Data/Achievements", "Data/Achievements", ExpectedResult = true)]
+        [TestCase("DATA/achievements", "data/ACHIEVEMENTS", ExpectedResult = true)]
+        [TestCase("DATA\\\\achievements", "data////ACHIEVEMENTS", ExpectedResult = true)]
+        [TestCase(" Data/Achievements ", "Data/Achievements", ExpectedResult = false)]
+        [TestCase("Data/Achievements", "   ", ExpectedResult = false)]
+
+        // with locale codes
+        [TestCase("Data/Achievements", "Data/Achievements.fr-FR", ExpectedResult = false)]
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements", ExpectedResult = true)]
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements.fr-FR", ExpectedResult = false)]
+        public bool IsEquivalentTo_BaseName(string mainAssetName, string otherAssetName)
+        {
+            // arrange
+            mainAssetName = PathUtilities.NormalizeAssetName(mainAssetName);
+
+            // act
+            AssetName name = AssetName.Parse(mainAssetName, _ => LocalizedContentManager.LanguageCode.fr);
+
+            // assert
+            return name.IsEquivalentTo(otherAssetName, useBaseName: true);
+        }
+
+
+        /****
+        ** StartsWith
+        ****/
+        [Test(Description = $"Assert that {nameof(AssetName.StartsWith)} compares names as expected for inputs that aren't affected by the input options.")]
+
+        // exact match (ignore case and formatting)
+        [TestCase("Data/Achievements", "Data/Achievements", ExpectedResult = true)]
+        [TestCase("DATA/achievements", "data/ACHIEVEMENTS", ExpectedResult = true)]
+        [TestCase("Data/Achievements", "Data\\Achievements", ExpectedResult = true)]
+        [TestCase("DATA\\achievements", "data/ACHIEVEMENTS", ExpectedResult = true)]
+        [TestCase("DATA\\\\achievements", "data////ACHIEVEMENTS", ExpectedResult = true)]
+
+        // leading-whitespace-sensitive
+        [TestCase("Data/Achievements", " Data/Achievements", ExpectedResult = false)]
+        [TestCase(" Data/Achievements ", "Data/Achievements", ExpectedResult = false)]
+
+        // invalid prefixes
+        [TestCase("Data/Achievements", null, ExpectedResult = false)]
+        [TestCase("Data/Achievements", "   ", ExpectedResult = false)]
+
+        // with locale codes
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements", ExpectedResult = true)]
+        public bool StartsWith_SimpleCases(string mainAssetName, string prefix)
+        {
+            // arrange
+            mainAssetName = PathUtilities.NormalizeAssetName(mainAssetName);
+
+            // act
+            AssetName name = AssetName.Parse(mainAssetName, _ => null);
+
+            // assert value is the same for any combination of options
+            bool result = name.StartsWith(prefix, true, true);
+            foreach (bool allowPartialWord in new[] { true, false })
+            {
+                foreach (bool allowSubfolder in new[] { true, true })
+                {
+                    if (allowPartialWord && allowSubfolder)
+                        continue;
+
+                    name.StartsWith(prefix, allowPartialWord, allowSubfolder)
+                        .Should().Be(result, $"the value returned for options ({nameof(allowPartialWord)}: {allowPartialWord}, {nameof(allowSubfolder)}: {allowSubfolder}) should match the base case");
+                }
+            }
+
+            // assert value
+            return result;
+        }
+
+        [Test(Description = $"Assert that {nameof(AssetName.StartsWith)} compares names as expected for the 'allowPartialWord' option.")]
+        [TestCase("Data/AchievementsToIgnore", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/AchievementsToIgnore", "Data/Achievements", false, ExpectedResult = false)]
+        [TestCase("Data/Achievements X", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements X", "Data/Achievements", false, ExpectedResult = true)]
+        [TestCase("Data/Achievements.X", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements.X", "Data/Achievements", false, ExpectedResult = true)]
+
+        // with locale codes
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements.fr-FR", "Data/Achievements", false, ExpectedResult = true)]
+        public bool StartsWith_PartialWord(string mainAssetName, string prefix, bool allowPartialWord)
+        {
+            // arrange
+            mainAssetName = PathUtilities.NormalizeAssetName(mainAssetName);
+
+            // act
+            AssetName name = AssetName.Parse(mainAssetName, _ => null);
+
+            // assert value is the same for any combination of options
+            bool result = name.StartsWith(prefix, allowPartialWord: allowPartialWord, allowSubfolder: true);
+            name.StartsWith(prefix, allowPartialWord, allowSubfolder: false)
+                .Should().Be(result, "specifying allowSubfolder should have no effect for these inputs");
+
+            // assert value
+            return result;
+        }
+
+        [Test(Description = $"Assert that {nameof(AssetName.StartsWith)} compares names as expected for the 'allowSubfolder' option.")]
+
+        // simple cases
+        [TestCase("Data/Achievements/Path", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path", "Data/Achievements", false, ExpectedResult = false)]
+        [TestCase("Data/Achievements/Path", "Data\\Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path", "Data\\Achievements", false, ExpectedResult = false)]
+
+        // trailing slash
+        [TestCase("Data/Achievements/Path", "Data/", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path", "Data/", false, ExpectedResult = false)]
+
+        // normalize slash style
+        [TestCase("Data/Achievements/Path", "Data\\", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path", "Data\\", false, ExpectedResult = false)]
+        [TestCase("Data/Achievements/Path", "Data/\\/", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path", "Data/\\/", false, ExpectedResult = false)]
+
+        // with locale code
+        [TestCase("Data/Achievements/Path.fr-FR", "Data/Achievements", true, ExpectedResult = true)]
+        [TestCase("Data/Achievements/Path.fr-FR", "Data/Achievements", false, ExpectedResult = false)]
+        public bool StartsWith_Subfolder(string mainAssetName, string otherAssetName, bool allowSubfolder)
+        {
+            // arrange
+            mainAssetName = PathUtilities.NormalizeAssetName(mainAssetName);
+
+            // act
+            AssetName name = AssetName.Parse(mainAssetName, _ => null);
+
+            // assert value is the same for any combination of options
+            bool result = name.StartsWith(otherAssetName, allowPartialWord: true, allowSubfolder: allowSubfolder);
+            name.StartsWith(otherAssetName, allowPartialWord: false, allowSubfolder: allowSubfolder)
+                .Should().Be(result, "specifying allowPartialWord should have no effect for these inputs");
+
+            // assert value
+            return result;
+        }
+
+
+        /****
+        ** GetHashCode
+        ****/
+        [Test(Description = $"Assert that {nameof(AssetName.GetHashCode)} generates the same hash code for two asset names which differ only by capitalization.")]
+        public void GetHashCode_IsCaseInsensitive()
+        {
+            // arrange
+            string left = "data/ACHIEVEMENTS";
+            string right = "DATA/achievements";
+
+            // act
+            int leftHash = AssetName.Parse(left, _ => null).GetHashCode();
+            int rightHash = AssetName.Parse(right, _ => null).GetHashCode();
+
+            // assert
+            leftHash.Should().Be(rightHash, "two asset names which differ only by capitalization should produce the same hash code");
+        }
+
+        [Test(Description = $"Assert that {nameof(AssetName.GetHashCode)} generates few hash code collisions for an arbitrary set of asset names.")]
+        public void GetHashCode_HasFewCollisions()
+        {
+            // generate list of names
+            List<string> names = new();
+            {
+                Random random = new();
+                string characters = "abcdefghijklmnopqrstuvwxyz1234567890/";
+
+                while (names.Count < 1000)
+                {
+                    char[] name = new char[random.Next(5, 20)];
+                    for (int i = 0; i < name.Length; i++)
+                        name[i] = characters[random.Next(0, characters.Length)];
+
+                    names.Add(new string(name));
+                }
+            }
+
+            // get distinct hash codes
+            HashSet<int> hashCodes = new();
+            foreach (string name in names)
+                hashCodes.Add(AssetName.Parse(name, _ => null).GetHashCode());
+
+            // assert a collision frequency under 0.1%
+            float collisionFrequency = 1 - (hashCodes.Count / (names.Count * 1f));
+            collisionFrequency.Should().BeLessOrEqualTo(0.001f, "hash codes should be relatively distinct with a collision rate under 0.1% for a small sample set");
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/Content/AssetData.cs b/src/SMAPI/Framework/Content/AssetData.cs
index 5c90d83b..05be8a3b 100644
--- a/src/SMAPI/Framework/Content/AssetData.cs
+++ b/src/SMAPI/Framework/Content/AssetData.cs
@@ -25,11 +25,11 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
         /// <param name="onDataReplaced">A callback to invoke when the data is replaced (if any).</param>
-        public AssetData(string locale, string assetName, TValue data, Func<string, string> getNormalizedPath, Action<TValue> onDataReplaced)
+        public AssetData(string locale, IAssetName assetName, TValue data, Func<string, string> getNormalizedPath, Action<TValue> onDataReplaced)
             : base(locale, assetName, data.GetType(), getNormalizedPath)
         {
             this.Data = data;
diff --git a/src/SMAPI/Framework/Content/AssetDataForDictionary.cs b/src/SMAPI/Framework/Content/AssetDataForDictionary.cs
index 26cbff5a..735b651c 100644
--- a/src/SMAPI/Framework/Content/AssetDataForDictionary.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForDictionary.cs
@@ -11,11 +11,11 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
         /// <param name="onDataReplaced">A callback to invoke when the data is replaced (if any).</param>
-        public AssetDataForDictionary(string locale, string assetName, IDictionary<TKey, TValue> data, Func<string, string> getNormalizedPath, Action<IDictionary<TKey, TValue>> onDataReplaced)
+        public AssetDataForDictionary(string locale, IAssetName assetName, IDictionary<TKey, TValue> data, Func<string, string> getNormalizedPath, Action<IDictionary<TKey, TValue>> onDataReplaced)
             : base(locale, assetName, data, getNormalizedPath, onDataReplaced) { }
     }
 }
diff --git a/src/SMAPI/Framework/Content/AssetDataForImage.cs b/src/SMAPI/Framework/Content/AssetDataForImage.cs
index c75514bc..b0f1b5c7 100644
--- a/src/SMAPI/Framework/Content/AssetDataForImage.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForImage.cs
@@ -21,11 +21,11 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
         /// <param name="onDataReplaced">A callback to invoke when the data is replaced (if any).</param>
-        public AssetDataForImage(string locale, string assetName, Texture2D data, Func<string, string> getNormalizedPath, Action<Texture2D> onDataReplaced)
+        public AssetDataForImage(string locale, IAssetName assetName, Texture2D data, Func<string, string> getNormalizedPath, Action<Texture2D> onDataReplaced)
             : base(locale, assetName, data, getNormalizedPath, onDataReplaced) { }
 
         /// <inheritdoc />
diff --git a/src/SMAPI/Framework/Content/AssetDataForMap.cs b/src/SMAPI/Framework/Content/AssetDataForMap.cs
index 0a5fa7e7..26e4986e 100644
--- a/src/SMAPI/Framework/Content/AssetDataForMap.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForMap.cs
@@ -18,11 +18,11 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
         /// <param name="onDataReplaced">A callback to invoke when the data is replaced (if any).</param>
-        public AssetDataForMap(string locale, string assetName, Map data, Func<string, string> getNormalizedPath, Action<Map> onDataReplaced)
+        public AssetDataForMap(string locale, IAssetName assetName, Map data, Func<string, string> getNormalizedPath, Action<Map> onDataReplaced)
             : base(locale, assetName, data, getNormalizedPath, onDataReplaced) { }
 
         /// <inheritdoc />
diff --git a/src/SMAPI/Framework/Content/AssetDataForObject.cs b/src/SMAPI/Framework/Content/AssetDataForObject.cs
index b7e8dfeb..d91873ae 100644
--- a/src/SMAPI/Framework/Content/AssetDataForObject.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForObject.cs
@@ -13,10 +13,10 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
-        public AssetDataForObject(string locale, string assetName, object data, Func<string, string> getNormalizedPath)
+        public AssetDataForObject(string locale, IAssetName assetName, object data, Func<string, string> getNormalizedPath)
             : base(locale, assetName, data, getNormalizedPath, onDataReplaced: null) { }
 
         /// <summary>Construct an instance.</summary>
@@ -24,24 +24,24 @@ namespace StardewModdingAPI.Framework.Content
         /// <param name="data">The content data being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
         public AssetDataForObject(IAssetInfo info, object data, Func<string, string> getNormalizedPath)
-            : this(info.Locale, info.AssetName, data, getNormalizedPath) { }
+            : this(info.Locale, info.Name, data, getNormalizedPath) { }
 
         /// <inheritdoc />
         public IAssetDataForDictionary<TKey, TValue> AsDictionary<TKey, TValue>()
         {
-            return new AssetDataForDictionary<TKey, TValue>(this.Locale, this.AssetName, this.GetData<IDictionary<TKey, TValue>>(), this.GetNormalizedPath, this.ReplaceWith);
+            return new AssetDataForDictionary<TKey, TValue>(this.Locale, this.Name, this.GetData<IDictionary<TKey, TValue>>(), this.GetNormalizedPath, this.ReplaceWith);
         }
 
         /// <inheritdoc />
         public IAssetDataForImage AsImage()
         {
-            return new AssetDataForImage(this.Locale, this.AssetName, this.GetData<Texture2D>(), this.GetNormalizedPath, this.ReplaceWith);
+            return new AssetDataForImage(this.Locale, this.Name, this.GetData<Texture2D>(), this.GetNormalizedPath, this.ReplaceWith);
         }
 
         /// <inheritdoc />
         public IAssetDataForMap AsMap()
         {
-            return new AssetDataForMap(this.Locale, this.AssetName, this.GetData<Map>(), this.GetNormalizedPath, this.ReplaceWith);
+            return new AssetDataForMap(this.Locale, this.Name, this.GetData<Map>(), this.GetNormalizedPath, this.ReplaceWith);
         }
 
         /// <inheritdoc />
diff --git a/src/SMAPI/Framework/Content/AssetInfo.cs b/src/SMAPI/Framework/Content/AssetInfo.cs
index d8106439..6a5b4f31 100644
--- a/src/SMAPI/Framework/Content/AssetInfo.cs
+++ b/src/SMAPI/Framework/Content/AssetInfo.cs
@@ -20,7 +20,11 @@ namespace StardewModdingAPI.Framework.Content
         public string Locale { get; }
 
         /// <inheritdoc />
-        public string AssetName { get; }
+        public IAssetName Name { get; }
+
+        /// <inheritdoc />
+        [Obsolete($"Use {nameof(Name)} instead.")]
+        public string AssetName => this.Name.Name;
 
         /// <inheritdoc />
         public Type DataType { get; }
@@ -31,22 +35,22 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="locale">The content's locale code, if the content is localized.</param>
-        /// <param name="assetName">The normalized asset name being read.</param>
+        /// <param name="assetName">The asset name being read.</param>
         /// <param name="type">The content type being read.</param>
         /// <param name="getNormalizedPath">Normalizes an asset key to match the cache key.</param>
-        public AssetInfo(string locale, string assetName, Type type, Func<string, string> getNormalizedPath)
+        public AssetInfo(string locale, IAssetName assetName, Type type, Func<string, string> getNormalizedPath)
         {
             this.Locale = locale;
-            this.AssetName = assetName;
+            this.Name = assetName;
             this.DataType = type;
             this.GetNormalizedPath = getNormalizedPath;
         }
 
         /// <inheritdoc />
+        [Obsolete($"Use {nameof(Name)}.{nameof(IAssetName.IsEquivalentTo)} instead.")]
         public bool AssetNameEquals(string path)
         {
-            path = this.GetNormalizedPath(path);
-            return this.AssetName.Equals(path, StringComparison.OrdinalIgnoreCase);
+            return this.Name.IsEquivalentTo(path);
         }
 
 
diff --git a/src/SMAPI/Framework/Content/AssetInterceptorChange.cs b/src/SMAPI/Framework/Content/AssetInterceptorChange.cs
index 10488b84..981eed40 100644
--- a/src/SMAPI/Framework/Content/AssetInterceptorChange.cs
+++ b/src/SMAPI/Framework/Content/AssetInterceptorChange.cs
@@ -70,7 +70,7 @@ namespace StardewModdingAPI.Framework.Content
                 }
                 catch (Exception ex)
                 {
-                    this.Mod.LogAsMod($"Mod failed when checking whether it could edit asset '{asset.AssetName}'. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    this.Mod.LogAsMod($"Mod failed when checking whether it could edit asset '{asset.Name}'. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 }
             }
 
@@ -84,7 +84,7 @@ namespace StardewModdingAPI.Framework.Content
                 }
                 catch (Exception ex)
                 {
-                    this.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{asset.AssetName}'. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    this.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{asset.Name}'. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 }
             }
 
diff --git a/src/SMAPI/Framework/Content/AssetName.cs b/src/SMAPI/Framework/Content/AssetName.cs
new file mode 100644
index 00000000..992647f8
--- /dev/null
+++ b/src/SMAPI/Framework/Content/AssetName.cs
@@ -0,0 +1,173 @@
+using System;
+using StardewModdingAPI.Toolkit.Utilities;
+using StardewValley;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>An asset name that can be loaded through the content pipeline.</summary>
+    internal class AssetName : IAssetName
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>A lowercase version of <see cref="Name"/> used for consistent hash codes and equality checks.</summary>
+        private readonly string ComparableName;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
+        /// <inheritdoc />
+        public string BaseName { get; }
+
+        /// <inheritdoc />
+        public string LocaleCode { get; }
+
+        /// <inheritdoc />
+        public LocalizedContentManager.LanguageCode? LanguageCode { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="baseName">The base asset name without the locale code.</param>
+        /// <param name="localeCode">The locale code specified in the <see cref="Name"/>, if it's a valid code recognized by the game content.</param>
+        /// <param name="languageCode">The language code matching the <see cref="LocaleCode"/>, if applicable.</param>
+        public AssetName(string baseName, string localeCode, LocalizedContentManager.LanguageCode? languageCode)
+        {
+            // validate
+            if (string.IsNullOrWhiteSpace(baseName))
+                throw new ArgumentException("The asset name can't be null or empty.", nameof(baseName));
+            if (string.IsNullOrWhiteSpace(localeCode))
+                localeCode = null;
+
+            // set base values
+            this.BaseName = PathUtilities.NormalizeAssetName(baseName);
+            this.LocaleCode = localeCode;
+            this.LanguageCode = languageCode;
+
+            // set derived values
+            this.Name = localeCode != null
+                ? string.Concat(this.BaseName, '.', this.LocaleCode)
+                : this.BaseName;
+            this.ComparableName = this.Name.ToLowerInvariant();
+        }
+
+        /// <summary>Parse a raw asset name into an instance.</summary>
+        /// <param name="rawName">The raw asset name to parse.</param>
+        /// <param name="parseLocale">Get the language code for a given locale, if it's valid.</param>
+        /// <exception cref="ArgumentException">The <paramref name="rawName"/> is null or empty.</exception>
+        public static AssetName Parse(string rawName, Func<string, LocalizedContentManager.LanguageCode?> parseLocale)
+        {
+            if (string.IsNullOrWhiteSpace(rawName))
+                throw new ArgumentException("The asset name can't be null or empty.", nameof(rawName));
+
+            string baseName = rawName;
+            string localeCode = null;
+            LocalizedContentManager.LanguageCode? languageCode = null;
+
+            int lastPeriodIndex = rawName.LastIndexOf('.');
+            if (lastPeriodIndex > 0 && rawName.Length > lastPeriodIndex + 1)
+            {
+                string possibleLocaleCode = rawName[(lastPeriodIndex + 1)..];
+                LocalizedContentManager.LanguageCode? possibleLanguageCode = parseLocale(possibleLocaleCode);
+
+                if (possibleLanguageCode != null)
+                {
+                    baseName = rawName[..lastPeriodIndex];
+                    localeCode = possibleLocaleCode;
+                    languageCode = possibleLanguageCode;
+                }
+            }
+
+            return new AssetName(baseName, localeCode, languageCode);
+        }
+
+        /// <inheritdoc />
+        public bool IsEquivalentTo(string assetName, bool useBaseName = false)
+        {
+            // empty asset key is never equivalent
+            if (string.IsNullOrWhiteSpace(assetName))
+                return false;
+
+            assetName = PathUtilities.NormalizeAssetName(assetName);
+
+            string compareTo = useBaseName ? this.BaseName : this.Name;
+            return compareTo.Equals(assetName, StringComparison.OrdinalIgnoreCase);
+        }
+
+        /// <inheritdoc />
+        public bool StartsWith(string prefix, bool allowPartialWord = true, bool allowSubfolder = true)
+        {
+            // asset keys never start with null
+            if (prefix is null)
+                return false;
+
+            // asset keys can't have a leading slash, but NormalizeAssetName will trim them
+            {
+                string trimmed = prefix.TrimStart();
+                if (trimmed.StartsWith('/') || trimmed.StartsWith('\\'))
+                    return false;
+            }
+
+            // normalize prefix
+            {
+                string normalized = PathUtilities.NormalizeAssetName(prefix);
+
+                string trimmed = prefix.TrimEnd();
+                if (trimmed.EndsWith('/') || trimmed.EndsWith('\\'))
+                    normalized += PathUtilities.PreferredAssetSeparator;
+
+                prefix = normalized;
+            }
+
+            // compare
+            return
+                this.Name.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)
+                && (
+                    allowPartialWord
+                    || this.Name.Length == prefix.Length
+                    || !char.IsLetterOrDigit(prefix[^1]) // last character in suffix is word separator
+                    || !char.IsLetterOrDigit(this.Name[prefix.Length]) // or first character after it is
+                )
+                && (
+                    allowSubfolder
+                    || this.Name.Length == prefix.Length
+                    || !this.Name[prefix.Length..].Contains(PathUtilities.PreferredAssetSeparator)
+                );
+        }
+
+
+        public bool IsDirectlyUnderPath(string assetFolder)
+        {
+            return this.StartsWith(assetFolder + "/", allowPartialWord: false, allowSubfolder: false);
+        }
+
+        /// <inheritdoc />
+        public bool Equals(IAssetName other)
+        {
+            return other switch
+            {
+                null => false,
+                AssetName otherImpl => this.ComparableName == otherImpl.ComparableName,
+                _ => StringComparer.Or