From 53ed5f4faaffad212a753b33db2106470f48b6b5 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Mon, 24 Jan 2022 21:55:30 -0500
Subject: update release notes

---
 docs/release-notes.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 05ab58a3..f45df4bd 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,6 +1,9 @@
 ← [README](README.md)
 
 # Release notes
+## Upcoming release
+* Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
 
-- 
cgit 


From 6dd4a8a12b25d349b18609132dade14da6ec3cf9 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 29 Jan 2022 17:46:45 -0500
Subject: fix item repo's handling of Journal Scraps and Secret Notes

---
 docs/release-notes.md                              |  6 ++-
 .../Framework/ItemRepository.cs                    | 62 ++++++++++++++++------
 2 files changed, 52 insertions(+), 16 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index f45df4bd..f1911716 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -2,7 +2,11 @@
 
 # Release notes
 ## Upcoming release
-* Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+* For players:
+  * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+
+* For console commands:
+  * Fixed `player_add` with Journal Scraps and Secret Notes.
 
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
diff --git a/src/SMAPI.Mods.ConsoleCommands/Framework/ItemRepository.cs b/src/SMAPI.Mods.ConsoleCommands/Framework/ItemRepository.cs
index 4a57ba5a..8704a403 100644
--- a/src/SMAPI.Mods.ConsoleCommands/Framework/ItemRepository.cs
+++ b/src/SMAPI.Mods.ConsoleCommands/Framework/ItemRepository.cs
@@ -134,24 +134,34 @@ namespace StardewModdingAPI.Mods.ConsoleCommands.Framework
                     {
                         string[] fields = Game1.objectInformation[id]?.Split('/');
 
-                        // secret notes
-                        if (id == 79)
+                        // ring
+                        if (id != 801 && fields?.Length >= 4 && fields[3] == "Ring") // 801 = wedding ring, which isn't an equippable ring
+                        {
+                            if (ShouldGet(ItemType.Ring))
+                                yield return this.TryCreate(ItemType.Ring, id, p => new Ring(p.ID));
+                        }
+
+                        // journal scrap
+                        else if (id == 842)
                         {
                             if (ShouldGet(ItemType.Object))
                             {
-                                foreach (SearchableItem secretNote in this.GetSecretNotes())
-                                    yield return secretNote;
+                                foreach (SearchableItem journalScrap in this.GetSecretNotes(isJournalScrap: true))
+                                    yield return journalScrap;
                             }
                         }
 
-                        // ring
-                        else if (id != 801 && fields?.Length >= 4 && fields[3] == "Ring") // 801 = wedding ring, which isn't an equippable ring
+                        // secret notes
+                        else if (id == 79)
                         {
-                            if (ShouldGet(ItemType.Ring))
-                                yield return this.TryCreate(ItemType.Ring, id, p => new Ring(p.ID));
+                            if (ShouldGet(ItemType.Object))
+                            {
+                                foreach (SearchableItem secretNote in this.GetSecretNotes(isJournalScrap: false))
+                                    yield return secretNote;
+                            }
                         }
 
-                        // item
+                        // object
                         else if (ShouldGet(ItemType.Object))
                         {
                             // spawn main item
@@ -184,16 +194,38 @@ namespace StardewModdingAPI.Mods.ConsoleCommands.Framework
         /*********
         ** Private methods
         *********/
-        /// <summary>Get the individual secret note items, if any.</summary>
+        /// <summary>Get the individual secret note or journal scrap items.</summary>
+        /// <param name="isJournalScrap">Whether to get journal scraps.</param>
         /// <remarks>Derived from <see cref="GameLocation.tryToCreateUnseenSecretNote"/>.</remarks>
-        private IEnumerable<SearchableItem> GetSecretNotes()
+        private IEnumerable<SearchableItem> GetSecretNotes(bool isJournalScrap)
         {
-            foreach (int secretNoteId in this.TryLoad<int, string>("Data\\SecretNotes").Keys)
+            // get base item ID
+            int baseId = isJournalScrap ? 842 : 79;
+
+            // get secret note IDs
+            var ids = this
+                .TryLoad<int, string>("Data\\SecretNotes")
+                .Keys
+                .Where(isJournalScrap
+                    ? id => (id >= GameLocation.JOURNAL_INDEX)
+                    : id => (id < GameLocation.JOURNAL_INDEX)
+                )
+                .Select<int, int>(isJournalScrap
+                    ? id => (id - GameLocation.JOURNAL_INDEX)
+                    : id => id
+                );
+
+            // build items
+            foreach (int id in ids)
             {
-                yield return this.TryCreate(ItemType.Object, this.CustomIDOffset + secretNoteId, _ =>
+                int fakeId = this.CustomIDOffset * 8 + id;
+                if (isJournalScrap)
+                    fakeId += GameLocation.JOURNAL_INDEX;
+
+                yield return this.TryCreate(ItemType.Object, fakeId, _ =>
                 {
-                    SObject note = new(79, 1);
-                    note.name = $"{note.name} #{secretNoteId}";
+                    SObject note = new(baseId, 1);
+                    note.Name = $"{note.Name} #{id}";
                     return note;
                 });
             }
-- 
cgit 


From 3431f486a2ef93e86d8923c1a4651644110df81b Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 29 Jan 2022 18:15:42 -0500
Subject: normalize season names in SDate constructor

---
 docs/release-notes.md                   |  3 +++
 src/SMAPI.Tests/Utilities/SDateTests.cs | 10 ++++++----
 src/SMAPI/Utilities/SDate.cs            |  4 +++-
 3 files changed, 12 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index f1911716..4ca11f01 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -5,6 +5,9 @@
 * For players:
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
 
+* For mod authors:
+  * The `SDate` constructor is no longer case-sensitive for season names.
+
 * For console commands:
   * Fixed `player_add` with Journal Scraps and Secret Notes.
 
diff --git a/src/SMAPI.Tests/Utilities/SDateTests.cs b/src/SMAPI.Tests/Utilities/SDateTests.cs
index 0461952e..374f4921 100644
--- a/src/SMAPI.Tests/Utilities/SDateTests.cs
+++ b/src/SMAPI.Tests/Utilities/SDateTests.cs
@@ -16,9 +16,12 @@ namespace SMAPI.Tests.Utilities
         /*********
         ** Fields
         *********/
-        /// <summary>All valid seasons.</summary>
+        /// <summary>The valid seasons.</summary>
         private static readonly string[] ValidSeasons = { "spring", "summer", "fall", "winter" };
 
+        /// <summary>Sample user inputs for season names.</summary>
+        private static readonly string[] SampleSeasonValues = SDateTests.ValidSeasons.Concat(new[] { "  WIntEr  " }).ToArray();
+
         /// <summary>All valid days of a month.</summary>
         private static readonly int[] ValidDays = Enumerable.Range(1, 28).ToArray();
 
@@ -55,19 +58,18 @@ namespace SMAPI.Tests.Utilities
         ** Constructor
         ****/
         [Test(Description = "Assert that the constructor sets the expected values for all valid dates.")]
-        public void Constructor_SetsExpectedValues([ValueSource(nameof(SDateTests.ValidSeasons))] string season, [ValueSource(nameof(SDateTests.ValidDays))] int day, [Values(1, 2, 100)] int year)
+        public void Constructor_SetsExpectedValues([ValueSource(nameof(SDateTests.SampleSeasonValues))] string season, [ValueSource(nameof(SDateTests.ValidDays))] int day, [Values(1, 2, 100)] int year)
         {
             // act
             SDate date = new SDate(day, season, year);
 
             // assert
             Assert.AreEqual(day, date.Day);
-            Assert.AreEqual(season, date.Season);
+            Assert.AreEqual(season.Trim().ToLowerInvariant(), date.Season);
             Assert.AreEqual(year, date.Year);
         }
 
         [Test(Description = "Assert that the constructor throws an exception if the values are invalid.")]
-        [TestCase(01, "Spring", 1)] // seasons are case-sensitive
         [TestCase(01, "springs", 1)] // invalid season name
         [TestCase(-1, "spring", 1)] // day < 0
         [TestCase(0, "spring", 1)] // day zero
diff --git a/src/SMAPI/Utilities/SDate.cs b/src/SMAPI/Utilities/SDate.cs
index cd075dcc..e10a59f8 100644
--- a/src/SMAPI/Utilities/SDate.cs
+++ b/src/SMAPI/Utilities/SDate.cs
@@ -250,6 +250,8 @@ namespace StardewModdingAPI.Utilities
         /// <exception cref="ArgumentException">One of the arguments has an invalid value (like day 35).</exception>
         private SDate(int day, string season, int year, bool allowDayZero)
         {
+            season = season?.Trim().ToLowerInvariant();
+
             // validate
             if (season == null)
                 throw new ArgumentNullException(nameof(season));
@@ -277,7 +279,7 @@ namespace StardewModdingAPI.Utilities
         /// <param name="year">The year.</param>
         private bool IsDayZero(int day, string season, int year)
         {
-            return day == 0 && season == "spring" && year == 1;
+            return day == 0 && season?.Trim().ToLower() == "spring" && year == 1;
         }
 
         /// <summary>Get the day of week for a given date.</summary>
-- 
cgit 


From 25a9f54ecfdaf6c4ad67dfb46c3f8c556d15d949 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 29 Jan 2022 20:43:45 -0500
Subject: fix manifest JSON schema's update key pattern

---
 docs/release-notes.md                       | 3 +++
 src/SMAPI.Web/wwwroot/schemas/manifest.json | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 4ca11f01..585644ef 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -11,6 +11,9 @@
 * For console commands:
   * Fixed `player_add` with Journal Scraps and Secret Notes.
 
+* For the web UI:
+  * Fixed JSON validator warning for update keys without a subkey.
+
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
 
diff --git a/src/SMAPI.Web/wwwroot/schemas/manifest.json b/src/SMAPI.Web/wwwroot/schemas/manifest.json
index b6722347..7457b993 100644
--- a/src/SMAPI.Web/wwwroot/schemas/manifest.json
+++ b/src/SMAPI.Web/wwwroot/schemas/manifest.json
@@ -103,7 +103,7 @@
             "type": "array",
             "items": {
                 "type": "string",
-                "pattern": "^(?i)(Chucklefish:\\d+|Nexus:\\d+|GitHub:[A-Za-z0-9_\\-]+/[A-Za-z0-9_\\-]+|ModDrop:\\d+)(?: *@ *[a-zA-Z0-9_]+ *)$",
+                "pattern": "^(?i)(Chucklefish:\\d+|Nexus:\\d+|GitHub:[A-Za-z0-9_\\-]+/[A-Za-z0-9_\\-]+|ModDrop:\\d+)(?: *@ *[a-zA-Z0-9_]+ *)?$",
                 "@errorMessages": {
                     "pattern": "Invalid update key; see https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest#Update_checks for more info."
                 }
-- 
cgit 


From 4a1174cd5086ac615b9218384853a6ad2831b603 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 11 Feb 2022 20:56:25 -0500
Subject: fix thumbstick input overrides

---
 docs/release-notes.md                            | 1 +
 src/SMAPI/Framework/Input/GamePadStateBuilder.cs | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 585644ef..18187e49 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -7,6 +7,7 @@
 
 * For mod authors:
   * 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.
 
 * For console commands:
   * Fixed `player_add` with Journal Scraps and Secret Notes.
diff --git a/src/SMAPI/Framework/Input/GamePadStateBuilder.cs b/src/SMAPI/Framework/Input/GamePadStateBuilder.cs
index b0bb7f80..3a99214f 100644
--- a/src/SMAPI/Framework/Input/GamePadStateBuilder.cs
+++ b/src/SMAPI/Framework/Input/GamePadStateBuilder.cs
@@ -104,10 +104,10 @@ namespace StardewModdingAPI.Framework.Input
                         this.LeftStickPos.Y = isDown ? 1 : 0;
                         break;
                     case SButton.LeftThumbstickDown:
-                        this.LeftStickPos.Y = isDown ? 1 : 0;
+                        this.LeftStickPos.Y = isDown ? -1 : 0;
                         break;
                     case SButton.LeftThumbstickLeft:
-                        this.LeftStickPos.X = isDown ? 1 : 0;
+                        this.LeftStickPos.X = isDown ? -1 : 0;
                         break;
                     case SButton.LeftThumbstickRight:
                         this.LeftStickPos.X = isDown ? 1 : 0;
@@ -118,10 +118,10 @@ namespace StardewModdingAPI.Framework.Input
                         this.RightStickPos.Y = isDown ? 1 : 0;
                         break;
                     case SButton.RightThumbstickDown:
-                        this.RightStickPos.Y = isDown ? 1 : 0;
+                        this.RightStickPos.Y = isDown ? -1 : 0;
                         break;
                     case SButton.RightThumbstickLeft:
-                        this.RightStickPos.X = isDown ? 1 : 0;
+                        this.RightStickPos.X = isDown ? -1 : 0;
                         break;
                     case SButton.RightThumbstickRight:
                         this.RightStickPos.X = isDown ? 1 : 0;
-- 
cgit 


From b0cc403098161ad82b858008e2523e1d2496fc41 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 12 Feb 2022 12:07:13 -0500
Subject: add data-* attributes to log parser for external tools

---
 docs/release-notes.md                              |  1 +
 .../Framework/LogParsing/Models/LogModInfo.cs      |  3 ++
 src/SMAPI.Web/ViewModels/LogParserModel.cs         |  2 +-
 src/SMAPI.Web/Views/LogParser/Index.cshtml         | 53 ++++++++++++++--------
 4 files changed, 38 insertions(+), 21 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 18187e49..5e004227 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -13,6 +13,7 @@
   * Fixed `player_add` with Journal Scraps and Secret Notes.
 
 * For the web UI:
+  * Added `data-*` attributes to log parser page for external tools.
   * Fixed JSON validator warning for update keys without a subkey.
 
 ## 3.13.4
diff --git a/src/SMAPI.Web/Framework/LogParsing/Models/LogModInfo.cs b/src/SMAPI.Web/Framework/LogParsing/Models/LogModInfo.cs
index 067e4df4..92bfe5c7 100644
--- a/src/SMAPI.Web/Framework/LogParsing/Models/LogModInfo.cs
+++ b/src/SMAPI.Web/Framework/LogParsing/Models/LogModInfo.cs
@@ -35,5 +35,8 @@ namespace StardewModdingAPI.Web.Framework.LogParsing.Models
 
         /// <summary>Whether the mod has an update available.</summary>
         public bool HasUpdate => this.UpdateVersion != null && this.Version != this.UpdateVersion;
+
+        /// <summary>Whether the mod is a content pack for another mod.</summary>
+        public bool IsContentPack => !string.IsNullOrWhiteSpace(this.ContentPackFor);
     }
 }
diff --git a/src/SMAPI.Web/ViewModels/LogParserModel.cs b/src/SMAPI.Web/ViewModels/LogParserModel.cs
index bea79eae..0b6d7722 100644
--- a/src/SMAPI.Web/ViewModels/LogParserModel.cs
+++ b/src/SMAPI.Web/ViewModels/LogParserModel.cs
@@ -83,7 +83,7 @@ namespace StardewModdingAPI.Web.ViewModels
 
             // group by mod
             return mods
-                .Where(mod => mod.ContentPackFor != null)
+                .Where(mod => mod.IsContentPack)
                 .GroupBy(mod => mod.ContentPackFor)
                 .ToDictionary(group => group.Key, group => group.ToArray());
         }
diff --git a/src/SMAPI.Web/Views/LogParser/Index.cshtml b/src/SMAPI.Web/Views/LogParser/Index.cshtml
index 993e7244..b54867b1 100644
--- a/src/SMAPI.Web/Views/LogParser/Index.cshtml
+++ b/src/SMAPI.Web/Views/LogParser/Index.cshtml
@@ -7,6 +7,9 @@
 
 @{
     ViewData["Title"] = "SMAPI log parser";
+
+    ParsedLog log = Model!.ParsedLog;
+
     IDictionary<string, LogModInfo[]> contentPacks = Model.GetContentPacksByMod();
     IDictionary<string, bool> defaultFilters = Enum
         .GetValues(typeof(LogLevel))
@@ -15,7 +18,7 @@
 
     string curPageUrl = this.Url.PlainAction("Index", "LogParser", new { id = Model.PasteID }, absoluteUrl: true);
 
-    ISet<int> screenIds = new HashSet<int>(Model.ParsedLog?.Messages?.Select(p => p.ScreenId) ?? Array.Empty<int>());
+    ISet<int> screenIds = new HashSet<int>(log?.Messages?.Select(p => p.ScreenId) ?? Array.Empty<int>());
 }
 
 @section Head {
@@ -35,9 +38,9 @@
     <script>
         $(function() {
             smapi.logParser({
-                logStarted: new Date(@this.ForJson(Model.ParsedLog?.Timestamp)),
-                showPopup: @this.ForJson(Model.ParsedLog == null),
-                showMods: @this.ForJson(Model.ParsedLog?.Mods?.Select(p => Model.GetSlug(p.Name)).Distinct().ToDictionary(slug => slug, slug => true)),
+                logStarted: new Date(@this.ForJson(log?.Timestamp)),
+                showPopup: @this.ForJson(log == null),
+                showMods: @this.ForJson(log?.Mods?.Select(p => Model.GetSlug(p.Name)).Distinct().ToDictionary(slug => slug, slug => true)),
                 showSections: @this.ForJson(Enum.GetNames(typeof(LogSection)).ToDictionary(section => section, section => false)),
                 showLevels: @this.ForJson(defaultFilters),
                 enableFilters: @this.ForJson(!Model.ShowRaw),
@@ -67,7 +70,7 @@ else if (Model.ParseError != null)
         <small v-pre>Error details: @Model.ParseError</small>
     </div>
 }
-else if (Model.ParsedLog?.IsValid == true)
+else if (log?.IsValid == true)
 {
     <div class="banner success" v-pre>
         <strong>Share this link to let someone else see the log:</strong> <code>@curPageUrl</code><br />
@@ -92,7 +95,7 @@ else if (Model.ParsedLog?.IsValid == true)
 }
 
 @* upload new log *@
-@if (Model.ParsedLog == null)
+@if (log == null)
 {
     <h2>Where do I find my SMAPI log?</h2>
     <div id="os-instructions">
@@ -157,7 +160,7 @@ else if (Model.ParsedLog?.IsValid == true)
     </div>
 
     <h2>How do I share my log?</h2>
-    <form action="@this.Url.PlainAction("PostAsync", "LogParser")" method="post">
+    <form action="@this.Url.PlainAction("Post", "LogParser")" method="post">
         <input id="inputFile" type="file" />
         <ol>
             <li>
@@ -174,10 +177,10 @@ else if (Model.ParsedLog?.IsValid == true)
 }
 
 @* parsed log *@
-@if (Model.ParsedLog?.IsValid == true)
+@if (log?.IsValid == true)
 {
     <div id="output">
-        @if (Model.ParsedLog.Mods.Any(mod => mod.HasUpdate))
+        @if (log.Mods.Any(mod => mod.HasUpdate))
         {
             <h2>Suggested fixes</h2>
             <ul id="fix-list">
@@ -185,7 +188,7 @@ else if (Model.ParsedLog?.IsValid == true)
                     Consider updating these mods to fix problems:
 
                     <table id="updates" class="table">
-                        @foreach (LogModInfo mod in Model.ParsedLog.Mods.Where(mod => (mod.HasUpdate && mod.ContentPackFor == null) || (contentPacks != null && contentPacks.TryGetValue(mod.Name, out LogModInfo[] contentPackList) && contentPackList.Any(pack => pack.HasUpdate))))
+                        @foreach (LogModInfo mod in log.Mods.Where(mod => (mod.HasUpdate && !mod.IsContentPack) || (contentPacks.TryGetValue(mod.Name, out LogModInfo[] contentPackList) && contentPackList.Any(pack => pack.HasUpdate))))
                         {
                             <tr class="mod-entry">
                                 <td>
@@ -230,23 +233,33 @@ else if (Model.ParsedLog?.IsValid == true)
         }
 
         <h2>Log info</h2>
-        <table id="metadata" class="table">
+        <table
+            id="metadata"
+            class="table"
+            data-code-mods="@log.Mods.Count(p => !p.IsContentPack)"
+            data-content-packs="@log.Mods.Count(p => p.IsContentPack)"
+            data-os="@log.OperatingSystem"
+            data-game-version="@log.GameVersion"
+            data-game-path="@log.GamePath"
+            data-smapi-version="@log.ApiVersion"
+            data-log-started="@log.Timestamp.UtcDateTime.ToString("O")"
+        >
             <caption>Game info:</caption>
             <tr>
                 <th>Stardew Valley:</th>
-                <td v-pre>@Model.ParsedLog.GameVersion on @Model.ParsedLog.OperatingSystem</td>
+                <td v-pre>@log.GameVersion on @log.OperatingSystem</td>
             </tr>
             <tr>
                 <th>SMAPI:</th>
-                <td v-pre>@Model.ParsedLog.ApiVersion</td>
+                <td v-pre>@log.ApiVersion</td>
             </tr>
             <tr>
                 <th>Folder:</th>
-                <td v-pre>@Model.ParsedLog.GamePath</td>
+                <td v-pre>@log.GamePath</td>
             </tr>
             <tr>
                 <th>Log started:</th>
-                <td>@Model.ParsedLog.Timestamp.UtcDateTime.ToString("yyyy-MM-dd HH:mm") UTC ({{localTimeStarted}} your time)</td>
+                <td>@log.Timestamp.UtcDateTime.ToString("yyyy-MM-dd HH:mm") UTC ({{localTimeStarted}} your time)</td>
             </tr>
         </table>
         <br />
@@ -260,7 +273,7 @@ else if (Model.ParsedLog?.IsValid == true)
                     <span class="notice btn txt" v-on:click="hideAllMods" v-bind:class="{ invisible: !anyModsShown || !anyModsHidden }">hide all</span>
                 }
             </caption>
-            @foreach (var mod in Model.ParsedLog.Mods.Where(p => p.Loaded && p.ContentPackFor == null))
+            @foreach (var mod in log.Mods.Where(p => p.Loaded && !p.IsContentPack))
             {
                 <tr v-on:click="toggleMod('@Model.GetSlug(mod.Name)')" class="mod-entry" v-bind:class="{ hidden: !showMods['@Model.GetSlug(mod.Name)'] }">
                     <td><input type="checkbox" v-bind:checked="showMods['@Model.GetSlug(mod.Name)']" v-bind:class="{ invisible: !anyModsHidden }" /></td>
@@ -317,7 +330,7 @@ else if (Model.ParsedLog?.IsValid == true)
             </div>
 
             <table id="log">
-                @foreach (var message in Model.ParsedLog.Messages)
+                @foreach (var message in log.Messages)
                 {
                     string levelStr = message.Level.ToString().ToLower();
                     string sectionStartClass = message.IsStartOfSection ? "section-start" : null;
@@ -360,7 +373,7 @@ else if (Model.ParsedLog?.IsValid == true)
         }
         else
         {
-            <pre v-pre>@Model.ParsedLog.RawText</pre>
+            <pre v-pre>@log.RawText</pre>
         }
 
         <small>
@@ -377,8 +390,8 @@ else if (Model.ParsedLog?.IsValid == true)
         </small>
     </div>
 }
-else if (Model.ParsedLog?.IsValid == false)
+else if (log?.IsValid == false)
 {
     <h3>Raw log</h3>
-    <pre v-pre>@Model.ParsedLog.RawText</pre>
+    <pre v-pre>@log.RawText</pre>
 }
-- 
cgit 


From 065859408f4e88ea1154b1fc76f7df5288e51b53 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 18 Feb 2022 12:31:14 -0500
Subject: Fix support for custom locale codes in asset names (#766)

---
 docs/release-notes.md                     |  1 +
 src/SMAPI/Framework/ContentCoordinator.cs | 33 ++++++++++++++++++++++++-------
 src/SMAPI/Framework/SCore.cs              | 11 +++++++++++
 3 files changed, 38 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 5e004227..d549b99c 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -8,6 +8,7 @@
 * For mod authors:
   * 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`).
 
 * For console commands:
   * Fixed `player_add` with Journal Scraps and Secret Notes.
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 49578046..61cefd12 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -14,6 +14,7 @@ using StardewModdingAPI.Metadata;
 using StardewModdingAPI.Toolkit.Serialization;
 using StardewModdingAPI.Toolkit.Utilities;
 using StardewValley;
+using StardewValley.GameData;
 using xTile;
 
 namespace StardewModdingAPI.Framework
@@ -136,7 +137,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.LocaleCodes = new Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>>(this.GetLocaleCodes);
+            this.LocaleCodes = new Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>>(() => this.GetLocaleCodes(includeCustomLanguages: false));
         }
 
         /// <summary>Get a new content manager which handles reading files from the game content folder with support for interception.</summary>
@@ -196,12 +197,17 @@ namespace StardewModdingAPI.Framework
             return this.MainContentManager.GetLocale(LocalizedContentManager.CurrentLanguageCode);
         }
 
-        /// <summary>Perform any cleanup needed when the locale changes.</summary>
-        public void OnLocaleChanged()
+        /// <summary>Perform any updates needed when the game loads custom languages from <c>Data/AdditionalLanguages</c>.</summary>
+        public void OnAdditionalLanguagesInitialized()
         {
-            // rebuild locale cache (which may change due to custom mod languages)
-            this.LocaleCodes = new Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>>(this.GetLocaleCodes);
+            // update locale cache for custom languages, and load it now (since languages added later won't work)
+            this.LocaleCodes = new Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>>(() => this.GetLocaleCodes(includeCustomLanguages: true));
+            _ = this.LocaleCodes.Value;
+        }
 
+        /// <summary>Perform any updates needed when the locale changes.</summary>
+        public void OnLocaleChanged()
+        {
             // reload affected content
             this.ContentManagerLock.InReadLock(() =>
             {
@@ -486,9 +492,22 @@ namespace StardewModdingAPI.Framework
         }
 
         /// <summary>Get the language enums (like <see cref="LocalizedContentManager.LanguageCode.ja"/>) indexed by locale code (like <c>ja-JP</c>).</summary>
-        private Dictionary<string, LocalizedContentManager.LanguageCode> GetLocaleCodes()
+        /// <param name="includeCustomLanguages">Whether to read custom languages from <c>Data/AdditionalLanguages</c>.</param>
+        private Dictionary<string, LocalizedContentManager.LanguageCode> GetLocaleCodes(bool includeCustomLanguages)
         {
-            var map = new Dictionary<string, LocalizedContentManager.LanguageCode>();
+            var map = new Dictionary<string, LocalizedContentManager.LanguageCode>(StringComparer.OrdinalIgnoreCase);
+
+            // custom languages
+            if (includeCustomLanguages)
+            {
+                foreach (ModLanguage language in Game1.content.Load<List<ModLanguage>>("Data/AdditionalLanguages"))
+                {
+                    if (!string.IsNullOrWhiteSpace(language?.LanguageCode))
+                        map[language.LanguageCode] = LocalizedContentManager.LanguageCode.mod;
+                }
+            }
+
+            // vanilla languages (override custom language if they conflict)
             foreach (LocalizedContentManager.LanguageCode code in Enum.GetValues(typeof(LocalizedContentManager.LanguageCode)))
             {
                 string locale = this.GetLocaleCode(code);
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index ef1f12fd..bfbd64ca 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -43,6 +43,7 @@ using StardewModdingAPI.Toolkit.Serialization;
 using StardewModdingAPI.Toolkit.Utilities;
 using StardewModdingAPI.Utilities;
 using StardewValley;
+using StardewValley.Menus;
 using xTile.Display;
 using MiniMonoModHotfix = MonoMod.Utils.MiniMonoModHotfix;
 using PathUtilities = StardewModdingAPI.Toolkit.Utilities.PathUtilities;
@@ -121,6 +122,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>Whether post-game-startup initialization has been performed.</summary>
         private bool IsInitialized;
 
+        /// <summary>Whether the game has initialized for any custom languages from <c>Data/AdditionalLanguages</c>.</summary>
+        private bool AreCustomLanguagesInitialized;
+
         /// <summary>Whether the player just returned to the title screen.</summary>
         public bool JustReturnedToTitle { get; set; }
 
@@ -986,6 +990,13 @@ namespace StardewModdingAPI.Framework
                     // preloaded
                     if (Context.IsSaveLoaded && Context.LoadStage != LoadStage.Loaded && Context.LoadStage != LoadStage.Ready && Game1.dayOfMonth != 0)
                         this.OnLoadStageChanged(LoadStage.Loaded);
+
+                    // additional languages initialized
+                    if (!this.AreCustomLanguagesInitialized && TitleMenu.ticksUntilLanguageLoad < 0)
+                    {
+                        this.AreCustomLanguagesInitialized = true;
+                        this.ContentCore.OnAdditionalLanguagesInitialized();
+                    }
                 }
 
                 /*********
-- 
cgit 


From a2190df08cc3f1b4a8dcb394056d65921d10702e Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 18 Feb 2022 15:39:49 -0500
Subject: add AssetName to encapsulate asset name handling (#766)

---
 docs/release-notes.md                              |   2 +
 src/SMAPI.Tests/Core/AssetNameTests.cs             | 295 +++++++++++++++++++++
 src/SMAPI/Framework/Content/AssetData.cs           |   4 +-
 .../Framework/Content/AssetDataForDictionary.cs    |   4 +-
 src/SMAPI/Framework/Content/AssetDataForImage.cs   |   4 +-
 src/SMAPI/Framework/Content/AssetDataForMap.cs     |   4 +-
 src/SMAPI/Framework/Content/AssetDataForObject.cs  |  12 +-
 src/SMAPI/Framework/Content/AssetInfo.cs           |  16 +-
 .../Framework/Content/AssetInterceptorChange.cs    |   4 +-
 src/SMAPI/Framework/Content/AssetName.cs           | 173 ++++++++++++
 src/SMAPI/Framework/ContentCoordinator.cs          |  45 ++--
 .../ContentManagers/BaseContentManager.cs          |  51 +---
 .../ContentManagers/GameContentManager.cs          |  94 +++----
 .../Framework/ContentManagers/IContentManager.cs   |   3 -
 .../Framework/ContentManagers/ModContentManager.cs |  26 +-
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs    |   5 +-
 src/SMAPI/IAssetInfo.cs                            |   5 +
 src/SMAPI/IAssetName.cs                            |  44 +++
 src/SMAPI/Metadata/CoreAssetPropagator.cs          | 261 ++++++++----------
 19 files changed, 736 insertions(+), 316 deletions(-)
 create mode 100644 src/SMAPI.Tests/Core/AssetNameTests.cs
 create mode 100644 src/SMAPI/Framework/Content/AssetName.cs
 create mode 100644 src/SMAPI/IAssetName.cs

(limited to 'docs')

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.OrdinalIgnoreCase.Equals(this.Name, other.Name)
+            };
+        }
+
+        /// <inheritdoc />
+        public override int GetHashCode()
+        {
+            return this.ComparableName.GetHashCode();
+        }
+
+        /// <inheritdoc />
+        public override string ToString()
+        {
+            return this.Name;
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 61cefd12..97a37b3f 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -248,6 +248,16 @@ namespace StardewModdingAPI.Framework
                 this.InvalidateCache((contentManager, key, type) => contentManager is GameContentManager);
         }
 
+        /// <summary>Parse a raw asset name.</summary>
+        /// <param name="rawName">The raw asset name to parse.</param>
+        /// <exception cref="ArgumentException">The <paramref name="rawName"/> is null or empty.</exception>
+        public AssetName ParseAssetName(string rawName)
+        {
+            return !string.IsNullOrWhiteSpace(rawName)
+                ? AssetName.Parse(rawName, parseLocale: locale => this.LocaleCodes.Value.TryGetValue(locale, out LocalizedContentManager.LanguageCode langCode) ? langCode : null)
+                : throw new ArgumentException("The asset name can't be null or empty.", nameof(rawName));
+        }
+
         /// <summary>Get whether this asset is mapped to a mod folder.</summary>
         /// <param name="key">The asset key.</param>
         public bool IsManagedAssetKey(string key)
@@ -306,11 +316,12 @@ namespace StardewModdingAPI.Framework
         /// <param name="predicate">Matches the asset keys to invalidate.</param>
         /// <param name="dispose">Whether to dispose invalidated assets. This should only be <c>true</c> when they're being invalidated as part of a dispose, to avoid crashing the game.</param>
         /// <returns>Returns the invalidated asset keys.</returns>
-        public IEnumerable<string> InvalidateCache(Func<IAssetInfo, bool> predicate, bool dispose = false)
+        public IEnumerable<IAssetName> InvalidateCache(Func<IAssetInfo, bool> predicate, bool dispose = false)
         {
             string locale = this.GetLocale();
-            return this.InvalidateCache((contentManager, assetName, type) =>
+            return this.InvalidateCache((contentManager, rawName, type) =>
             {
+                IAssetName assetName = this.ParseAssetName(rawName);
                 IAssetInfo info = new AssetInfo(locale, assetName, type, this.MainContentManager.AssertAndNormalizeAssetName);
                 return predicate(info);
             }, dispose);
@@ -320,10 +331,10 @@ namespace StardewModdingAPI.Framework
         /// <param name="predicate">Matches the asset keys to invalidate.</param>
         /// <param name="dispose">Whether to dispose invalidated assets. This should only be <c>true</c> when they're being invalidated as part of a dispose, to avoid crashing the game.</param>
         /// <returns>Returns the invalidated asset names.</returns>
-        public IEnumerable<string> InvalidateCache(Func<IContentManager, string, Type, bool> predicate, bool dispose = false)
+        public IEnumerable<IAssetName> InvalidateCache(Func<IContentManager, string, Type, bool> predicate, bool dispose = false)
         {
             // invalidate cache & track removed assets
-            IDictionary<string, Type> removedAssets = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase);
+            IDictionary<IAssetName, Type> removedAssets = new Dictionary<IAssetName, Type>();
             this.ContentManagerLock.InReadLock(() =>
             {
                 // cached assets
@@ -331,8 +342,9 @@ namespace StardewModdingAPI.Framework
                 {
                     foreach (var entry in contentManager.InvalidateCache((key, type) => predicate(contentManager, key, type), dispose))
                     {
-                        if (!removedAssets.ContainsKey(entry.Key))
-                            removedAssets[entry.Key] = entry.Value.GetType();
+                        AssetName assetName = this.ParseAssetName(entry.Key);
+                        if (!removedAssets.ContainsKey(assetName))
+                            removedAssets[assetName] = entry.Value.GetType();
                     }
                 }
 
@@ -346,8 +358,8 @@ namespace StardewModdingAPI.Framework
                             continue;
 
                         // get map path
-                        string mapPath = this.MainContentManager.AssertAndNormalizeAssetName(location.mapPath.Value);
-                        if (!removedAssets.ContainsKey(mapPath) && predicate(this.MainContentManager, mapPath, typeof(Map)))
+                        AssetName mapPath = this.ParseAssetName(this.MainContentManager.AssertAndNormalizeAssetName(location.mapPath.Value));
+                        if (!removedAssets.ContainsKey(mapPath) && predicate(this.MainContentManager, mapPath.Name, typeof(Map)))
                             removedAssets[mapPath] = typeof(Map);
                     }
                 }
@@ -360,17 +372,17 @@ namespace StardewModdingAPI.Framework
                 this.CoreAssets.Propagate(
                     assets: removedAssets.ToDictionary(p => p.Key, p => p.Value),
                     ignoreWorld: Context.IsWorldFullyUnloaded,
-                    out IDictionary<string, bool> propagated,
+                    out IDictionary<IAssetName, bool> propagated,
                     out bool updatedNpcWarps
                 );
 
                 // log summary
                 StringBuilder report = new();
                 {
-                    string[] invalidatedKeys = removedAssets.Keys.ToArray();
-                    string[] propagatedKeys = propagated.Where(p => p.Value).Select(p => p.Key).ToArray();
+                    IAssetName[] invalidatedKeys = removedAssets.Keys.ToArray();
+                    IAssetName[] propagatedKeys = propagated.Where(p => p.Value).Select(p => p.Key).ToArray();
 
-                    string FormatKeyList(IEnumerable<string> keys) => string.Join(", ", keys.OrderBy(p => p, StringComparer.OrdinalIgnoreCase));
+                    string FormatKeyList(IEnumerable<IAssetName> keys) => string.Join(", ", keys.Select(p => p.Name).OrderBy(p => p, StringComparer.OrdinalIgnoreCase));
 
                     report.AppendLine($"Invalidated {invalidatedKeys.Length} asset names ({FormatKeyList(invalidatedKeys)}).");
                     report.AppendLine(propagated.Count > 0
@@ -422,15 +434,6 @@ namespace StardewModdingAPI.Framework
             return tilesheets ?? Array.Empty<TilesheetReference>();
         }
 
-        /// <summary>Get the language enum which corresponds to a locale code (e.g. <see cref="LocalizedContentManager.LanguageCode.fr"/> given <c>fr-FR</c>).</summary>
-        /// <param name="locale">The locale code to search. This must exactly match the language; no fallback is performed.</param>
-        /// <param name="language">The matched language enum, if any.</param>
-        /// <returns>Returns whether a valid language was found.</returns>
-        public bool TryGetLanguageEnum(string locale, out LocalizedContentManager.LanguageCode language)
-        {
-            return this.LocaleCodes.Value.TryGetValue(locale, out language);
-        }
-
         /// <summary>Get the locale code which corresponds to a language enum (e.g. <c>fr-FR</c> given <see cref="LocalizedContentManager.LanguageCode.fr"/>).</summary>
         /// <param name="language">The language enum to search.</param>
         public string GetLocaleCode(LocalizedContentManager.LanguageCode language)
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 5645c0fa..be892b33 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -160,14 +160,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
             return this.IsNormalizedKeyLoaded(assetName, language);
         }
 
-        /// <inheritdoc />
-        public IEnumerable<string> GetAssetKeys()
-        {
-            return this.Cache.Keys
-                .Select(this.GetAssetName)
-                .Distinct();
-        }
-
         /****
         ** Cache invalidation
         ****/
@@ -177,13 +169,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).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;
                 }
 
@@ -275,44 +267,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
             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..0ca9e277 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -73,46 +73,46 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
 
             // normalize asset name
-            assetName = this.AssertAndNormalizeAssetName(assetName);
-            if (this.TryParseExplicitLanguageAssetKey(assetName, out string newAssetName, out LanguageCode newLanguage))
-                return this.Load<T>(newAssetName, newLanguage, useCache);
+            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
+            if (parsedName.LanguageCode.HasValue)
+                return this.Load<T>(parsedName.BaseName, parsedName.LanguageCode.Value, useCache);
 
             // get from cache
-            if (useCache && this.IsLoaded(assetName, language))
-                return this.RawLoad<T>(assetName, language, useCache: true);
+            if (useCache && this.IsLoaded(parsedName.Name, language))
+                return this.RawLoad<T>(parsedName.Name, language, useCache: true);
 
             // get managed asset
-            if (this.Coordinator.TryParseManagedAssetKey(assetName, out string contentManagerID, out string relativePath))
+            if (this.Coordinator.TryParseManagedAssetKey(parsedName.Name, out string contentManagerID, out string relativePath))
             {
                 T managedAsset = this.Coordinator.LoadManagedAsset<T>(contentManagerID, relativePath);
-                this.TrackAsset(assetName, managedAsset, language, useCache);
+                this.TrackAsset(parsedName.Name, managedAsset, language, useCache);
                 return managedAsset;
             }
 
             // load asset
             T data;
-            if (this.AssetsBeingLoaded.Contains(assetName))
+            if (this.AssetsBeingLoaded.Contains(parsedName.Name))
             {
-                this.Monitor.Log($"Broke loop while loading asset '{assetName}'.", LogLevel.Warn);
+                this.Monitor.Log($"Broke loop while loading asset '{parsedName.Name}'.", 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>(parsedName.Name, language, useCache);
             }
             else
             {
-                data = this.AssetsBeingLoaded.Track(assetName, () =>
+                data = this.AssetsBeingLoaded.Track(parsedName.Name, () =>
                 {
                     string locale = this.GetLocale(language);
-                    IAssetInfo info = new AssetInfo(locale, assetName, typeof(T), this.AssertAndNormalizeAssetName);
+                    IAssetInfo info = new AssetInfo(locale, parsedName, 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>(parsedName.Name, language, useCache), this.AssertAndNormalizeAssetName);
                     asset = this.ApplyEditors<T>(info, asset);
                     return (T)asset.Data;
                 });
             }
 
             // update cache & return data
-            this.TrackAsset(assetName, data, language, useCache);
+            this.TrackAsset(parsedName.Name, data, language, useCache);
             return data;
         }
 
@@ -124,13 +124,16 @@ namespace StardewModdingAPI.Framework.ContentManagers
             // 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);
+            {
+                IAssetName assetName = this.Coordinator.ParseAssetName(key);
+                removeAssetNames.Add(assetName.BaseName);
+            }
 
             // invalidate translatable assets
             string[] invalidated = this
                 .InvalidateCache((key, type) =>
                     removeAssetNames.Contains(key)
-                    || (this.TryParseExplicitLanguageAssetKey(key, out string assetName, out _) && removeAssetNames.Contains(assetName))
+                    || removeAssetNames.Contains(this.Coordinator.ParseAssetName(key).BaseName)
                 )
                 .Select(p => p.Key)
                 .OrderBy(p => p, StringComparer.OrdinalIgnoreCase)
@@ -168,9 +171,10 @@ namespace StardewModdingAPI.Framework.ContentManagers
         {
             // handle explicit language in asset name
             {
-                if (this.TryParseExplicitLanguageAssetKey(assetName, out string newAssetName, out LanguageCode newLanguage))
+                IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
+                if (parsedName.LanguageCode.HasValue)
                 {
-                    this.TrackAsset(newAssetName, value, newLanguage, useCache);
+                    this.TrackAsset(parsedName.BaseName, value, parsedName.LanguageCode.Value, useCache);
                     return;
                 }
             }
@@ -238,30 +242,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
         }
 
-        /// <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>
@@ -277,7 +257,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                     }
                     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);
+                        entry.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                         return false;
                     }
                 })
@@ -289,7 +269,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             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);
+                this.Monitor.Log($"Multiple mods want to provide the '{info.Name}' 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;
             }
 
@@ -300,11 +280,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
             try
             {
                 data = loader.Load<T>(info);
-                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.AssetName}'.", LogLevel.Trace);
+                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.Name}'.", LogLevel.Trace);
             }
             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}'. SMAPI will use the default asset instead. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 return null;
             }
 
@@ -349,7 +329,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 }
                 catch (Exception ex)
                 {
-                    mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{info.AssetName}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                     continue;
                 }
 
@@ -358,22 +338,22 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 try
                 {
                     editor.Edit<T>(asset);
-                    this.Monitor.Log($"{mod.DisplayName} edited {info.AssetName}.");
+                    this.Monitor.Log($"{mod.DisplayName} edited {info.Name}.");
                 }
                 catch (Exception ex)
                 {
-                    mod.LogAsMod($"Mod crashed when editing asset '{info.AssetName}', which may cause errors in-game. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    mod.LogAsMod($"Mod crashed when editing asset '{info.Name}', which may cause errors in-game. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 }
 
                 // validate edit
                 if (asset.Data == null)
                 {
-                    mod.LogAsMod($"Mod incorrectly set asset '{info.AssetName}' to a null value; ignoring override.", LogLevel.Warn);
+                    mod.LogAsMod($"Mod incorrectly set asset '{info.Name}' to a null value; ignoring override.", LogLevel.Warn);
                     asset = GetNewData(prevAsset);
                 }
                 else if (!(asset.Data is T))
                 {
-                    mod.LogAsMod($"Mod incorrectly set asset '{asset.AssetName}' to incompatible type '{asset.Data.GetType()}', expected '{typeof(T)}'; ignoring override.", LogLevel.Warn);
+                    mod.LogAsMod($"Mod incorrectly set asset '{asset.Name}' to incompatible type '{asset.Data.GetType()}', expected '{typeof(T)}'; ignoring override.", LogLevel.Warn);
                     asset = GetNewData(prevAsset);
                 }
             }
@@ -393,21 +373,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
             // can't load a null asset
             if (data == null)
             {
-                mod.LogAsMod($"SMAPI blocked asset replacement for '{info.AssetName}': mod incorrectly set asset to a null value.", LogLevel.Error);
+                mod.LogAsMod($"SMAPI blocked asset replacement for '{info.Name}': mod incorrectly set asset to a null value.", LogLevel.Error);
                 return false;
             }
 
             // when replacing a map, the vanilla tilesheets must have the same order and IDs
             if (data is Map loadedMap)
             {
-                TilesheetReference[] vanillaTilesheetRefs = this.Coordinator.GetVanillaTilesheetIds(info.AssetName);
+                TilesheetReference[] vanillaTilesheetRefs = this.Coordinator.GetVanillaTilesheetIds(info.Name.Name);
                 foreach (TilesheetReference vanillaSheet in vanillaTilesheetRefs)
                 {
                     // add missing tilesheet
                     if (loadedMap.GetTileSheet(vanillaSheet.Id) == null)
                     {
                         mod.Monitor.LogOnce("SMAPI fixed maps loaded by this mod to prevent errors. See the log file for details.", LogLevel.Warn);
-                        this.Monitor.Log($"Fixed broken map replacement: {mod.DisplayName} loaded '{info.AssetName}' without a required tilesheet (id: {vanillaSheet.Id}, source: {vanillaSheet.ImageSource}).");
+                        this.Monitor.Log($"Fixed broken map replacement: {mod.DisplayName} loaded '{info.Name}' without a required tilesheet (id: {vanillaSheet.Id}, source: {vanillaSheet.ImageSource}).");
 
                         loadedMap.AddTileSheet(new TileSheet(vanillaSheet.Id, loadedMap, vanillaSheet.ImageSource, vanillaSheet.SheetSize, vanillaSheet.TileSize));
                     }
@@ -417,17 +397,17 @@ namespace StardewModdingAPI.Framework.ContentManagers
                     {
                         // only show warning if not farm map
                         // This is temporary: mods shouldn't do this for any vanilla map, but these are the ones we know will crash. Showing a warning for others instead gives modders time to update their mods, while still simplifying troubleshooting.
-                        bool isFarmMap = info.AssetNameEquals("Maps/Farm") || info.AssetNameEquals("Maps/Farm_Combat") || info.AssetNameEquals("Maps/Farm_Fishing") || info.AssetNameEquals("Maps/Farm_Foraging") || info.AssetNameEquals("Maps/Farm_FourCorners") || info.AssetNameEquals("Maps/Farm_Island") || info.AssetNameEquals("Maps/Farm_Mining");
+                        bool isFarmMap = info.Name.IsEquivalentTo("Maps/Farm") || info.Name.IsEquivalentTo("Maps/Farm_Combat") || info.Name.IsEquivalentTo("Maps/Farm_Fishing") || info.Name.IsEquivalentTo("Maps/Farm_Foraging") || info.Name.IsEquivalentTo("Maps/Farm_FourCorners") || info.Name.IsEquivalentTo("Maps/Farm_Island") || info.Name.IsEquivalentTo("Maps/Farm_Mining");
 
                         string reason = $"mod reordered the original tilesheets, which {(isFarmMap ? "would cause a crash" : "often causes crashes")}.\nTechnical details for mod author: Expected order: {string.Join(", ", vanillaTilesheetRefs.Select(p => p.Id))}. See https://stardewvalleywiki.com/Modding:Maps#Tilesheet_order for help.";
 
                         SCore.DeprecationManager.PlaceholderWarn("3.8.2", DeprecationLevel.PendingRemoval);
                         if (isFarmMap)
                         {
-                            mod.LogAsMod($"SMAPI blocked '{info.AssetName}' map load: {reason}", LogLevel.Error);
+                            mod.LogAsMod($"SMAPI blocked '{info.Name}' map load: {reason}", LogLevel.Error);
                             return false;
                         }
-                        mod.LogAsMod($"SMAPI found an issue with '{info.AssetName}' map load: {reason}", LogLevel.Warn);
+                        mod.LogAsMod($"SMAPI found an issue with '{info.Name}' map load: {reason}", LogLevel.Warn);
                     }
                 }
             }
diff --git a/src/SMAPI/Framework/ContentManagers/IContentManager.cs b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
index d7963305..ba7dbc06 100644
--- a/src/SMAPI/Framework/ContentManagers/IContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
@@ -58,9 +58,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="language">The language.</param>
         bool IsLoaded(string assetName, LocalizedContentManager.LanguageCode language);
 
-        /// <summary>Get the cached asset keys.</summary>
-        IEnumerable<string> GetAssetKeys();
-
         /// <summary>Purge matched assets from the cache.</summary>
         /// <param name="predicate">Matches the asset keys to invalidate.</param>
         /// <param name="dispose">Whether to dispose invalidated assets. This should only be <c>true</c> when they're being invalidated as part of a dispose, to avoid crashing the game.</param>
diff --git a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
index beb90a5d..21f88d47 100644
--- a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
@@ -80,7 +80,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         {
             // normalize key
             bool isXnbFile = Path.GetExtension(assetName).ToLower() == ".xnb";
-            assetName = this.AssertAndNormalizeAssetName(assetName);
+            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
 
             // disable caching
             // This is necessary to avoid assets being shared between content managers, which can
@@ -97,21 +97,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
 
             // resolve managed asset key
             {
-                if (this.Coordinator.TryParseManagedAssetKey(assetName, out string contentManagerID, out string relativePath))
+                if (this.Coordinator.TryParseManagedAssetKey(parsedName.Name, out string contentManagerID, out string relativePath))
                 {
                     if (contentManagerID != this.Name)
-                        throw new SContentLoadException($"Can't load managed asset key '{assetName}' through content manager '{this.Name}' for a different mod.");
-                    assetName = relativePath;
+                        throw new SContentLoadException($"Can't load managed asset key '{parsedName}' through content manager '{this.Name}' for a different mod.");
+                    parsedName = this.Coordinator.ParseAssetName(relativePath);
                 }
             }
 
             // get local asset
-            SContentLoadException GetContentError(string reasonPhrase) => new SContentLoadException($"Failed loading asset '{assetName}' from {this.Name}: {reasonPhrase}");
+            SContentLoadException GetContentError(string reasonPhrase) => new SContentLoadException($"Failed loading asset '{parsedName}' from {this.Name}: {reasonPhrase}");
             T asset;
             try
             {
                 // get file
-                FileInfo file = this.GetModFile(isXnbFile ? $"{assetName}.xnb" : assetName); // .xnb extension is stripped from asset names passed to the content manager
+                FileInfo file = this.GetModFile(isXnbFile ? $"{parsedName}.xnb" : parsedName.Name); // .xnb extension is stripped from asset names passed to the content manager
                 if (!file.Exists)
                     throw GetContentError("the specified path doesn't exist.");
 
@@ -121,11 +121,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
                     // XNB file
                     case ".xnb":
                         {
-                            asset = this.RawLoad<T>(assetName, useCache: false);
+                            asset = this.RawLoad<T>(parsedName.Name, useCache: false);
                             if (asset is Map map)
                             {
-                                map.assetPath = assetName;
-                                this.FixTilesheetPaths(map, relativeMapPath: assetName, fixEagerPathPrefixes: true);
+                                map.assetPath = parsedName.Name;
+                                this.FixTilesheetPaths(map, relativeMapPath: parsedName.Name, fixEagerPathPrefixes: true);
                             }
                         }
                         break;
@@ -173,8 +173,8 @@ namespace StardewModdingAPI.Framework.ContentManagers
                             // fetch & cache
                             FormatManager formatManager = FormatManager.Instance;
                             Map map = formatManager.LoadMap(file.FullName);
-                            map.assetPath = assetName;
-                            this.FixTilesheetPaths(map, relativeMapPath: assetName, fixEagerPathPrefixes: false);
+                            map.assetPath = parsedName.Name;
+                            this.FixTilesheetPaths(map, relativeMapPath: parsedName.Name, fixEagerPathPrefixes: false);
                             asset = (T)(object)map;
                         }
                         break;
@@ -185,11 +185,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
             catch (Exception ex) when (!(ex is SContentLoadException))
             {
-                throw new SContentLoadException($"The content manager failed loading content asset '{assetName}' from {this.Name}.", ex);
+                throw new SContentLoadException($"The content manager failed loading content asset '{parsedName}' from {this.Name}.", ex);
             }
 
             // track & return asset
-            this.TrackAsset(assetName, asset, language, useCache);
+            this.TrackAsset(parsedName.Name, asset, language, useCache);
             return asset;
         }
 
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index bfca2264..a01248a8 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -129,7 +129,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
         {
             string actualKey = this.GetActualAssetKey(key, ContentSource.GameContent);
             this.Monitor.Log($"Requested cache invalidation for '{actualKey}'.", LogLevel.Trace);
-            return this.ContentCore.InvalidateCache(asset => asset.AssetNameEquals(actualKey)).Any();
+            return this.ContentCore.InvalidateCache(asset => asset.Name.IsEquivalentTo(actualKey)).Any();
         }
 
         /// <inheritdoc />
@@ -153,7 +153,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
                 throw new ArgumentNullException(nameof(data), "Can't get a patch helper for a null value.");
 
             assetName ??= $"temp/{Guid.NewGuid():N}";
-            return new AssetDataForObject(this.CurrentLocale, assetName, data, this.NormalizeAssetName);
+
+            return new AssetDataForObject(this.CurrentLocale, this.ContentCore.ParseAssetName(assetName), data, this.NormalizeAssetName);
         }
 
 
diff --git a/src/SMAPI/IAssetInfo.cs b/src/SMAPI/IAssetInfo.cs
index 6cdf01ee..6ac8358d 100644
--- a/src/SMAPI/IAssetInfo.cs
+++ b/src/SMAPI/IAssetInfo.cs
@@ -11,7 +11,11 @@ namespace StardewModdingAPI
         /// <summary>The content's locale code, if the content is localized.</summary>
         string Locale { get; }
 
+        /// <summary>The asset name being read.</summary>
+        public IAssetName Name { get; }
+
         /// <summary>The normalized asset name being read. The format may change between platforms; see <see cref="AssetNameEquals"/> to compare with a known path.</summary>
+        [Obsolete($"Use {nameof(Name)} instead.")]
         string AssetName { get; }
 
         /// <summary>The content data type.</summary>
@@ -23,6 +27,7 @@ namespace StardewModdingAPI
         *********/
         /// <summary>Get whether the asset name being loaded matches a given name after normalization.</summary>
         /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
+        [Obsolete($"Use {nameof(Name)}.{nameof(IAssetName.IsEquivalentTo)} instead.")]
         bool AssetNameEquals(string path);
     }
 }
diff --git a/src/SMAPI/IAssetName.cs b/src/SMAPI/IAssetName.cs
new file mode 100644
index 00000000..a5bfea93
--- /dev/null
+++ b/src/SMAPI/IAssetName.cs
@@ -0,0 +1,44 @@
+using System;
+using StardewValley;
+
+namespace StardewModdingAPI
+{
+    /// <summary>The name for an asset loaded through the content pipeline.</summary>
+    public interface IAssetName : IEquatable<IAssetName>
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The full normalized asset name, including the locale if applicable (like <c>Data/Achievements.fr-FR</c>).</summary>
+        string Name { get; }
+
+        /// <summary>The base asset name without the locale code.</summary>
+        string BaseName { get; }
+
+        /// <summary>The locale code specified in the <see cref="Name"/>, if it's a valid code recognized by the game content.</summary>
+        string LocaleCode { get; }
+
+        /// <summary>The language code matching the <see cref="LocaleCode"/>, if applicable.</summary>
+        LocalizedContentManager.LanguageCode? LanguageCode { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether the given asset name is equivalent, ignoring capitalization and formatting.</summary>
+        /// <param name="assetName">The asset name to compare this instance to.</param>
+        /// <param name="useBaseName">Whether to compare the given name with the <see cref="BaseName"/> (if true) or <see cref="Name"/> (if false). This has no effect on any locale included in the given <paramref name="assetName"/>.</param>
+        bool IsEquivalentTo(string assetName, bool useBaseName = false);
+
+        /// <summary>Get whether the asset name starts with the given value, ignoring capitalization and formatting. This can be used with a trailing slash to test for an asset folder, like <c>Data/</c>.</summary>
+        /// <param name="prefix">The prefix to match.</param>
+        /// <param name="allowPartialWord">Whether to match if the prefix occurs mid-word, so <c>Data/AchievementsToIgnore</c> matches prefix <c>Data/Achievements</c>. If this is false, the prefix only matches if the asset name starts with the prefix followed by a non-alphanumeric character (including <c>.</c>, <c>/</c>, or <c>\\</c>) or the end of string.</param>
+        /// <param name="allowSubfolder">Whether to match the prefix if there's a subfolder path after it, so <c>Data/Achievements/Example</c> matches prefix <c>Data/Achievements</c>. If this is false, the prefix only matches if the asset name has no <c>/</c> or <c>\\</c> characters after the prefix.</param>
+        bool StartsWith(string prefix, bool allowPartialWord = true, bool allowSubfolder = true);
+
+        /// <summary>Get whether the asset is directly within the given asset path.</summary>
+        /// <remarks>For example, <c>Characters/Dialogue/Abigail</c> is directly under <c>Characters/Dialogue</c> but not <c>Characters</c> or <c>Characters/Dialogue/Ab</c>. To allow sub-paths, use <see cref="StartsWith"/> instead.</remarks>
+        /// <param name="assetFolder">The asset path to check. This doesn't need a trailing slash.</param>
+        bool IsDirectlyUnderPath(string assetFolder);
+    }
+}
diff --git a/src/SMAPI/Metadata/CoreAssetPropagator.cs b/src/SMAPI/Metadata/CoreAssetPropagator.cs
index a6c4bb24..e7fac578 100644
--- a/src/SMAPI/Metadata/CoreAssetPropagator.cs
+++ b/src/SMAPI/Metadata/CoreAssetPropagator.cs
@@ -87,22 +87,22 @@ namespace StardewModdingAPI.Metadata
         /// <param name="ignoreWorld">Whether the in-game world is fully unloaded (e.g. on the title screen), so there's no need to propagate changes into the world.</param>
         /// <param name="propagatedAssets">A lookup of asset names to whether they've been propagated.</param>
         /// <param name="updatedNpcWarps">Whether the NPC pathfinding cache was reloaded.</param>
-        public void Propagate(IDictionary<string, Type> assets, bool ignoreWorld, out IDictionary<string, bool> propagatedAssets, out bool updatedNpcWarps)
+        public void Propagate(IDictionary<IAssetName, Type> assets, bool ignoreWorld, out IDictionary<IAssetName, bool> propagatedAssets, out bool updatedNpcWarps)
         {
             // group into optimized lists
             var buckets = assets.GroupBy(p =>
             {
-                if (this.IsInFolder(p.Key, "Characters") || this.IsInFolder(p.Key, "Characters/Monsters"))
+                if (p.Key.IsDirectlyUnderPath("Characters") || p.Key.IsDirectlyUnderPath("Characters/Monsters"))
                     return AssetBucket.Sprite;
 
-                if (this.IsInFolder(p.Key, "Portraits"))
+                if (p.Key.IsDirectlyUnderPath("Portraits"))
                     return AssetBucket.Portrait;
 
                 return AssetBucket.Other;
             });
 
             // reload assets
-            propagatedAssets = assets.ToDictionary(p => p.Key, _ => false, StringComparer.OrdinalIgnoreCase);
+            propagatedAssets = assets.ToDictionary(p => p.Key, _ => false);
             updatedNpcWarps = false;
             foreach (var bucket in buckets)
             {
@@ -149,16 +149,16 @@ namespace StardewModdingAPI.Metadata
         ** Private methods
         *********/
         /// <summary>Reload one of the game's core assets (if applicable).</summary>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <param name="type">The asset type to reload.</param>
         /// <param name="ignoreWorld">Whether the in-game world is fully unloaded (e.g. on the title screen), so there's no need to propagate changes into the world.</param>
         /// <param name="changedWarps">Whether any map warps were changed as part of this propagation.</param>
         /// <returns>Returns whether an asset was loaded. The return value may be true or false, or a non-null value for true.</returns>
         [SuppressMessage("ReSharper", "StringLiteralTypo", Justification = "These deliberately match the asset names.")]
-        private bool PropagateOther(string key, Type type, bool ignoreWorld, out bool changedWarps)
+        private bool PropagateOther(IAssetName assetName, Type type, bool ignoreWorld, out bool changedWarps)
         {
             var content = this.MainContentManager;
-            key = this.AssertAndNormalizeAssetName(key);
+            string key = assetName.Name;
             changedWarps = false;
 
             /****
@@ -170,7 +170,7 @@ namespace StardewModdingAPI.Metadata
             {
                 foreach (TileSheet tilesheet in Game1.currentLocation.map.TileSheets)
                 {
-                    if (this.IsSameAssetKey(tilesheet.ImageSource, key))
+                    if (assetName.IsEquivalentTo(tilesheet.ImageSource))
                         Game1.mapDisplayDevice.LoadTileSheet(tilesheet);
                 }
             }
@@ -188,7 +188,7 @@ namespace StardewModdingAPI.Metadata
                     {
                         GameLocation location = info.Location;
 
-                        if (this.IsSameAssetKey(location.mapPath.Value, key))
+                        if (assetName.IsEquivalentTo(location.mapPath.Value))
                         {
                             static ISet<string> GetWarpSet(GameLocation location)
                             {
@@ -213,14 +213,13 @@ namespace StardewModdingAPI.Metadata
             /****
             ** Propagate by key
             ****/
-            Reflector reflection = this.Reflection;
-            switch (key.ToLower().Replace("\\", "/")) // normalized key so we can compare statically
+            switch (assetName.Name.ToLower().Replace("\\", "/")) // normalized key so we can compare statically
             {
                 /****
                 ** Animals
                 ****/
                 case "animals/horse":
-                    return !ignoreWorld && this.ReloadPetOrHorseSprites<Horse>(content, key);
+                    return !ignoreWorld && this.ReloadPetOrHorseSprites<Horse>(content, assetName);
 
                 /****
                 ** Buildings
@@ -231,7 +230,7 @@ namespace StardewModdingAPI.Metadata
 
                 case "buildings/houses_paintmask": // Farm
                     {
-                        bool removedFromCache = this.RemoveFromPaintMaskCache(key);
+                        bool removedFromCache = this.RemoveFromPaintMaskCache(assetName);
 
                         Farm farm = Game1.getFarm();
                         farm?.ApplyHousePaint();
@@ -250,7 +249,7 @@ namespace StardewModdingAPI.Metadata
                 case "characters/farmer/farmer_base_bald":
                 case "characters/farmer/farmer_girl_base":
                 case "characters/farmer/farmer_girl_base_bald":
-                    return !ignoreWorld && this.ReloadPlayerSprites(key);
+                    return !ignoreWorld && this.ReloadPlayerSprites(assetName);
 
                 case "characters/farmer/hairstyles": // Game1.LoadContent
                     FarmerRenderer.hairStylesTexture = this.LoadAndDisposeIfNeeded(FarmerRenderer.hairStylesTexture, key);
@@ -313,7 +312,7 @@ namespace StardewModdingAPI.Metadata
                     return true;
 
                 case "data/npcdispositions": // NPC constructor
-                    return !ignoreWorld && this.ReloadNpcDispositions(content, key);
+                    return !ignoreWorld && this.ReloadNpcDispositions(content, assetName);
 
                 case "data/npcgifttastes": // Game1.LoadContent
                     Game1.NPCGiftTastes = content.Load<Dictionary<string, string>>(key);
@@ -393,7 +392,7 @@ namespace StardewModdingAPI.Metadata
                     }
 
                     if (!ignoreWorld)
-                        this.ReloadDoorSprites(content, key);
+                        this.ReloadDoorSprites(content, assetName);
                     return true;
 
                 case "loosesprites/cursors2": // Game1.LoadContent
@@ -425,7 +424,7 @@ namespace StardewModdingAPI.Metadata
                     return true;
 
                 case "loosesprites/suspensionbridge": // SuspensionBridge constructor
-                    return !ignoreWorld && this.ReloadSuspensionBridges(content, key);
+                    return !ignoreWorld && this.ReloadSuspensionBridges(content, assetName);
 
                 /****
                 ** Content\Maps
@@ -456,7 +455,7 @@ namespace StardewModdingAPI.Metadata
                     return false;
 
                 case "minigames/titlebuttons": // TitleMenu
-                    return this.ReloadTitleButtons(content, key);
+                    return this.ReloadTitleButtons(content, assetName);
 
                 /****
                 ** Content\Strings
@@ -480,14 +479,14 @@ namespace StardewModdingAPI.Metadata
                     return true;
 
                 case "tilesheets/chairtiles": // Game1.LoadContent
-                    return this.ReloadChairTiles(content, key, ignoreWorld);
+                    return this.ReloadChairTiles(content, assetName, ignoreWorld);
 
                 case "tilesheets/craftables": // Game1.LoadContent
                     Game1.bigCraftableSpriteSheet = content.Load<Texture2D>(key);
                     return true;
 
                 case "tilesheets/critters": // Critter constructor
-                    return !ignoreWorld && this.ReloadCritterTextures(content, key) > 0;
+                    return !ignoreWorld && this.ReloadCritterTextures(content, assetName) > 0;
 
                 case "tilesheets/crops": // Game1.LoadContent
                     Game1.cropSpriteSheet = content.Load<Texture2D>(key);
@@ -541,7 +540,7 @@ namespace StardewModdingAPI.Metadata
                     return true;
 
                 case "terrainfeatures/grass": // from Grass
-                    return !ignoreWorld && this.ReloadGrassTextures(content, key);
+                    return !ignoreWorld && this.ReloadGrassTextures(content, assetName);
 
                 case "terrainfeatures/hoedirt": // from HoeDirt
                     HoeDirt.lightTexture = content.Load<Texture2D>(key);
@@ -556,27 +555,27 @@ namespace StardewModdingAPI.Metadata
                     return true;
 
                 case "terrainfeatures/mushroom_tree": // from Tree
-                    return !ignoreWorld && this.ReloadTreeTextures(content, key, Tree.mushroomTree);
+                    return !ignoreWorld && this.ReloadTreeTextures(content, assetName, Tree.mushroomTree);
 
                 case "terrainfeatures/tree_palm": // from Tree
-                    return !ignoreWorld && this.ReloadTreeTextures(content, key, Tree.palmTree);
+                    return !ignoreWorld && this.ReloadTreeTextures(content, assetName, Tree.palmTree);
 
                 case "terrainfeatures/tree1_fall": // from Tree
                 case "terrainfeatures/tree1_spring": // from Tree
                 case "terrainfeatures/tree1_summer": // from Tree
                 case "terrainfeatures/tree1_winter": // from Tree
-                    return !ignoreWorld && this.ReloadTreeTextures(content, key, Tree.bushyTree);
+                    return !ignoreWorld && this.ReloadTreeTextures(content, assetName, Tree.bushyTree);
 
                 case "terrainfeatures/tree2_fall": // from Tree
                 case "terrainfeatures/tree2_spring": // from Tree
                 case "terrainfeatures/tree2_summer": // from Tree
                 case "terrainfeatures/tree2_winter": // from Tree
-                    return !ignoreWorld && this.ReloadTreeTextures(content, key, Tree.leafyTree);
+                    return !ignoreWorld && this.ReloadTreeTextures(content, assetName, Tree.leafyTree);
 
                 case "terrainfeatures/tree3_fall": // from Tree
                 case "terrainfeatures/tree3_spring": // from Tree
                 case "terrainfeatures/tree3_winter": // from Tree
-                    return !ignoreWorld && this.ReloadTreeTextures(content, key, Tree.pineTree);
+                    return !ignoreWorld && this.ReloadTreeTextures(content, assetName, Tree.pineTree);
             }
 
             /****
@@ -585,25 +584,25 @@ namespace StardewModdingAPI.Metadata
             if (!ignoreWorld)
             {
                 // dynamic textures
-                if (this.KeyStartsWith(key, "animals/cat"))
-                    return this.ReloadPetOrHorseSprites<Cat>(content, key);
-                if (this.KeyStartsWith(key, "animals/dog"))
-                    return this.ReloadPetOrHorseSprites<Dog>(content, key);
-                if (this.IsInFolder(key, "Animals"))
-                    return this.ReloadFarmAnimalSprites(content, key);
+                if (assetName.StartsWith("animals/cat"))
+                    return this.ReloadPetOrHorseSprites<Cat>(content, assetName);
+                if (assetName.StartsWith("animals/dog"))
+                    return this.ReloadPetOrHorseSprites<Dog>(content, assetName);
+                if (assetName.IsDirectlyUnderPath("Animals"))
+                    return this.ReloadFarmAnimalSprites(content, assetName);
 
-                if (this.IsInFolder(key, "Buildings"))
-                    return this.ReloadBuildings(key);
+                if (assetName.IsDirectlyUnderPath("Buildings"))
+                    return this.ReloadBuildings(assetName);
 
-                if (this.KeyStartsWith(key, "LooseSprites/Fence"))
-                    return this.ReloadFenceTextures(key);
+                if (assetName.StartsWith("LooseSprites/Fence"))
+                    return this.ReloadFenceTextures(assetName);
 
                 // dynamic data
-                if (this.IsInFolder(key, "Characters/Dialogue"))
-                    return this.ReloadNpcDialogue(key);
+                if (assetName.IsDirectlyUnderPath("Characters/Dialogue"))
+                    return this.ReloadNpcDialogue(assetName);
 
-                if (this.IsInFolder(key, "Characters/schedules"))
-                    return this.ReloadNpcSchedules(key);
+                if (assetName.IsDirectlyUnderPath("Characters/schedules"))
+                    return this.ReloadNpcSchedules(assetName);
             }
 
             return false;
@@ -618,14 +617,14 @@ namespace StardewModdingAPI.Metadata
         ****/
         /// <summary>Reload buttons on the title screen.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
         /// <remarks>Derived from the <see cref="TitleMenu"/> constructor and <see cref="TitleMenu.setUpIcons"/>.</remarks>
-        private bool ReloadTitleButtons(LocalizedContentManager content, string key)
+        private bool ReloadTitleButtons(LocalizedContentManager content, IAssetName assetName)
         {
             if (Game1.activeClickableMenu is TitleMenu titleMenu)
             {
-                Texture2D texture = content.Load<Texture2D>(key);
+                Texture2D texture = content.Load<Texture2D>(assetName.Name);
 
                 titleMenu.titleButtonsTexture = texture;
                 titleMenu.backButton.texture = texture;
@@ -645,21 +644,21 @@ namespace StardewModdingAPI.Metadata
         /// <summary>Reload the sprites for matching pets or horses.</summary>
         /// <typeparam name="TAnimal">The animal type.</typeparam>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadPetOrHorseSprites<TAnimal>(LocalizedContentManager content, string key)
+        private bool ReloadPetOrHorseSprites<TAnimal>(LocalizedContentManager content, IAssetName assetName)
             where TAnimal : NPC
         {
             // find matches
             TAnimal[] animals = this.GetCharacters()
                 .OfType<TAnimal>()
-                .Where(p => this.IsSameAssetKey(p.Sprite?.Texture?.Name, key))
+                .Where(p => assetName.IsEquivalentTo(p.Sprite?.Texture?.Name))
                 .ToArray();
             if (!animals.Any())
                 return false;
 
             // update sprites
-            Texture2D texture = content.Load<Texture2D>(key);
+            Texture2D texture = content.Load<Texture2D>(assetName.Name);
             foreach (TAnimal animal in animals)
                 animal.Sprite.spriteTexture = texture;
             return true;
@@ -667,10 +666,10 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload the sprites for matching farm animals.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
         /// <remarks>Derived from <see cref="FarmAnimal.reload"/>.</remarks>
-        private bool ReloadFarmAnimalSprites(LocalizedContentManager content, string key)
+        private bool ReloadFarmAnimalSprites(LocalizedContentManager content, IAssetName assetName)
         {
             // find matches
             FarmAnimal[] animals = this.GetFarmAnimals().ToArray();
@@ -678,7 +677,7 @@ namespace StardewModdingAPI.Metadata
                 return false;
 
             // update sprites
-            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(key));
+            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(assetName.Name));
             foreach (FarmAnimal animal in animals)
             {
                 // get expected key
@@ -690,23 +689,23 @@ namespace StardewModdingAPI.Metadata
                 expectedKey = $"Animals/{expectedKey}";
 
                 // reload asset
-                if (this.IsSameAssetKey(expectedKey, key))
+                if (assetName.IsEquivalentTo(expectedKey))
                     animal.Sprite.spriteTexture = texture.Value;
             }
             return texture.IsValueCreated;
         }
 
         /// <summary>Reload building textures.</summary>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadBuildings(string key)
+        private bool ReloadBuildings(IAssetName assetName)
         {
             // get paint mask info
             const string paintMaskSuffix = "_PaintMask";
-            bool isPaintMask = key.EndsWith(paintMaskSuffix, StringComparison.OrdinalIgnoreCase);
+            bool isPaintMask = assetName.BaseName.EndsWith(paintMaskSuffix, StringComparison.OrdinalIgnoreCase);
 
             // get building type
-            string type = Path.GetFileName(key);
+            string type = Path.GetFileName(assetName.Name)!;
             if (isPaintMask)
                 type = type.Substring(0, type.Length - paintMaskSuffix.Length);
 
@@ -718,7 +717,7 @@ namespace StardewModdingAPI.Metadata
                 .ToArray();
 
             // remove from paint mask cache
-            bool removedFromCache = this.RemoveFromPaintMaskCache(key);
+            bool removedFromCache = this.RemoveFromPaintMaskCache(assetName);
 
             // reload textures
             if (buildings.Any())
@@ -734,12 +733,12 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload map seat textures.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <param name="ignoreWorld">Whether the in-game world is fully unloaded (e.g. on the title screen), so there's no need to propagate changes into the world.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadChairTiles(LocalizedContentManager content, string key, bool ignoreWorld)
+        private bool ReloadChairTiles(LocalizedContentManager content, IAssetName assetName, bool ignoreWorld)
         {
-            MapSeat.mapChairTexture = content.Load<Texture2D>(key);
+            MapSeat.mapChairTexture = content.Load<Texture2D>(assetName.Name);
 
             if (!ignoreWorld)
             {
@@ -747,7 +746,7 @@ namespace StardewModdingAPI.Metadata
                 {
                     foreach (MapSeat seat in location.mapSeats.Where(p => p != null))
                     {
-                        if (this.IsSameAssetKey(seat._loadedTextureFile, key))
+                        if (assetName.IsEquivalentTo(seat._loadedTextureFile))
                             seat.overlayTexture = MapSeat.mapChairTexture;
                     }
                 }
@@ -758,9 +757,9 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload critter textures.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns the number of reloaded assets.</returns>
-        private int ReloadCritterTextures(LocalizedContentManager content, string key)
+        private int ReloadCritterTextures(LocalizedContentManager content, IAssetName assetName)
         {
             // get critters
             Critter[] critters =
@@ -768,7 +767,7 @@ namespace StardewModdingAPI.Metadata
                     from location in this.GetLocations()
                     where location.critters != null
                     from Critter critter in location.critters
-                    where this.IsSameAssetKey(critter.sprite?.Texture?.Name, key)
+                    where assetName.IsEquivalentTo(critter.sprite?.Texture?.Name)
                     select critter
                 )
                 .ToArray();
@@ -776,7 +775,7 @@ namespace StardewModdingAPI.Metadata
                 return 0;
 
             // update sprites
-            Texture2D texture = content.Load<Texture2D>(key);
+            Texture2D texture = content.Load<Texture2D>(assetName.Name);
             foreach (var entry in critters)
                 entry.sprite.spriteTexture = texture;
 
@@ -785,11 +784,11 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload the sprites for interior doors.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any doors were affected.</returns>
-        private bool ReloadDoorSprites(LocalizedContentManager content, string key)
+        private bool ReloadDoorSprites(LocalizedContentManager content, IAssetName assetName)
         {
-            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(key));
+            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(assetName.Name));
 
             foreach (GameLocation location in this.GetLocations())
             {
@@ -803,7 +802,7 @@ namespace StardewModdingAPI.Metadata
                         continue;
 
                     string curKey = this.Reflection.GetField<string>(door.Sprite, "textureName").GetValue();
-                    if (this.IsSameAssetKey(curKey, key))
+                    if (assetName.IsEquivalentTo(curKey))
                         door.Sprite.texture = texture.Value;
                 }
             }
@@ -827,12 +826,12 @@ namespace StardewModdingAPI.Metadata
         }
 
         /// <summary>Reload the sprites for a fence type.</summary>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadFenceTextures(string key)
+        private bool ReloadFenceTextures(IAssetName assetName)
         {
-            // get fence type
-            if (!int.TryParse(this.GetSegments(key)[1].Substring("Fence".Length), out int fenceType))
+            // get fence type (e.g. LooseSprites/Fence3 => 3)
+            if (!int.TryParse(this.GetSegments(assetName.BaseName)[1].Substring("Fence".Length), out int fenceType))
                 return false;
 
             // get fences
@@ -855,22 +854,22 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload tree textures.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadGrassTextures(LocalizedContentManager content, string key)
+        private bool ReloadGrassTextures(LocalizedContentManager content, IAssetName assetName)
         {
             Grass[] grasses =
                 (
                     from location in this.GetLocations()
                     from grass in location.terrainFeatures.Values.OfType<Grass>()
-                    where this.IsSameAssetKey(grass.textureName(), key)
+                    where assetName.IsEquivalentTo(grass.textureName())
                     select grass
                 )
                 .ToArray();
 
             if (grasses.Any())
             {
-                Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(key));
+                Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(assetName.Name));
                 foreach (Grass grass in grasses)
                     grass.texture = texture;
                 return true;
@@ -932,11 +931,11 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload the disposition data for matching NPCs.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any NPCs were affected.</returns>
-        private bool ReloadNpcDispositions(LocalizedContentManager content, string key)
+        private bool ReloadNpcDispositions(LocalizedContentManager content, IAssetName assetName)
         {
-            IDictionary<string, string> data = content.Load<Dictionary<string, string>>(key);
+            IDictionary<string, string> data = content.Load<Dictionary<string, string>>(assetName.Name);
             bool changed = false;
             foreach (NPC npc in this.GetCharacters())
             {
@@ -953,16 +952,16 @@ namespace StardewModdingAPI.Metadata
         /// <summary>Reload the sprites for matching NPCs.</summary>
         /// <param name="keys">The asset keys to reload.</param>
         /// <param name="propagated">The asset keys which have been propagated.</param>
-        private void ReloadNpcSprites(IEnumerable<string> keys, IDictionary<string, bool> propagated)
+        private void ReloadNpcSprites(IEnumerable<IAssetName> keys, IDictionary<IAssetName, bool> propagated)
         {
             // get NPCs
-            HashSet<string> lookup = new HashSet<string>(keys, StringComparer.OrdinalIgnoreCase);
+            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.Contains(key)
-                    select new { Npc = npc, Key = key }
+                    where key != null && lookup.ContainsKey(key)
+                    select new { Npc = npc, AssetName = lookup[key] }
                 )
                 .ToArray();
             if (!characters.Any())
@@ -971,56 +970,56 @@ namespace StardewModdingAPI.Metadata
             // update sprite
             foreach (var target in characters)
             {
-                target.Npc.Sprite.spriteTexture = this.LoadAndDisposeIfNeeded(target.Npc.Sprite.spriteTexture, target.Key);
-                propagated[target.Key] = true;
+                target.Npc.Sprite.spriteTexture = this.LoadAndDisposeIfNeeded(target.Npc.Sprite.spriteTexture, target.AssetName.Name);
+                propagated[target.AssetName] = true;
             }
         }
 
         /// <summary>Reload the portraits for matching NPCs.</summary>
         /// <param name="keys">The asset key to reload.</param>
         /// <param name="propagated">The asset keys which have been propagated.</param>
-        private void ReloadNpcPortraits(IEnumerable<string> keys, IDictionary<string, bool> propagated)
+        private void ReloadNpcPortraits(IEnumerable<IAssetName> keys, IDictionary<IAssetName, bool> propagated)
         {
             // get NPCs
-            HashSet<string> lookup = new HashSet<string>(keys, StringComparer.OrdinalIgnoreCase);
+            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.Contains(key)
-                    select new { Npc = npc, Key = key }
+                    where key != null && lookup.ContainsKey(key)
+                    select new { Npc = npc, AssetName = lookup[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.Contains(gilKey))
+                if (lookup.TryGetValue(gilKey, out IAssetName assetName))
                 {
                     GameLocation adventureGuild = Game1.getLocationFromName("AdventureGuild");
                     if (adventureGuild != null)
-                        characters.Add(new { Npc = this.Reflection.GetField<NPC>(adventureGuild, "Gil").GetValue(), Key = gilKey });
+                        characters.Add(new { Npc = this.Reflection.GetField<NPC>(adventureGuild, "Gil").GetValue(), AssetName = assetName });
                 }
             }
 
             // update portrait
             foreach (var target in characters)
             {
-                target.Npc.Portrait = this.LoadAndDisposeIfNeeded(target.Npc.Portrait, target.Key);
-                propagated[target.Key] = true;
+                target.Npc.Portrait = this.LoadAndDisposeIfNeeded(target.Npc.Portrait, target.AssetName.Name);
+                propagated[target.AssetName] = true;
             }
         }
 
         /// <summary>Reload the sprites for matching players.</summary>
-        /// <param name="key">The asset key to reload.</param>
-        private bool ReloadPlayerSprites(string key)
+        /// <param name="assetName">The asset name to reload.</param>
+        private bool ReloadPlayerSprites(IAssetName assetName)
         {
             Farmer[] players =
                 (
                     from player in Game1.getOnlineFarmers()
-                    where this.IsSameAssetKey(player.getTexture(), key)
+                    where assetName.IsEquivalentTo(player.getTexture())
                     select player
                 )
                 .ToArray();
@@ -1036,11 +1035,11 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload suspension bridge textures.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadSuspensionBridges(LocalizedContentManager content, string key)
+        private bool ReloadSuspensionBridges(LocalizedContentManager content, IAssetName assetName)
         {
-            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(key));
+            Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(assetName.Name));
 
             foreach (GameLocation location in this.GetLocations(buildingInteriors: false))
             {
@@ -1059,10 +1058,10 @@ namespace StardewModdingAPI.Metadata
 
         /// <summary>Reload tree textures.</summary>
         /// <param name="content">The content manager through which to reload the asset.</param>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <param name="type">The type to reload.</param>
         /// <returns>Returns whether any textures were reloaded.</returns>
-        private bool ReloadTreeTextures(LocalizedContentManager content, string key, int type)
+        private bool ReloadTreeTextures(LocalizedContentManager content, IAssetName assetName, int type)
         {
             Tree[] trees = this.GetLocations()
                 .SelectMany(p => p.terrainFeatures.Values.OfType<Tree>())
@@ -1071,7 +1070,7 @@ namespace StardewModdingAPI.Metadata
 
             if (trees.Any())
             {
-                Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(key));
+                Lazy<Texture2D> texture = new Lazy<Texture2D>(() => content.Load<Texture2D>(assetName.Name));
                 foreach (Tree tree in trees)
                     tree.texture = texture;
                 return true;
@@ -1084,12 +1083,12 @@ namespace StardewModdingAPI.Metadata
         ** Reload data methods
         ****/
         /// <summary>Reload the dialogue data for matching NPCs.</summary>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any assets were reloaded.</returns>
-        private bool ReloadNpcDialogue(string key)
+        private bool ReloadNpcDialogue(IAssetName assetName)
         {
             // get NPCs
-            string name = Path.GetFileName(key);
+            string name = Path.GetFileName(assetName.Name);
             NPC[] villagers = this.GetCharacters().Where(npc => npc.Name == name && npc.isVillager()).ToArray();
             if (!villagers.Any())
                 return false;
@@ -1114,12 +1113,12 @@ namespace StardewModdingAPI.Metadata
         }
 
         /// <summary>Reload the schedules for matching NPCs.</summary>
-        /// <param name="key">The asset key to reload.</param>
+        /// <param name="assetName">The asset name to reload.</param>
         /// <returns>Returns whether any assets were reloaded.</returns>
-        private bool ReloadNpcSchedules(string key)
+        private bool ReloadNpcSchedules(IAssetName assetName)
         {
             // get NPCs
-            string name = Path.GetFileName(key);
+            string name = Path.GetFileName(assetName.Name);
             NPC[] villagers = this.GetCharacters().Where(npc => npc.Name == name && npc.isVillager()).ToArray();
             if (!villagers.Any())
                 return false;
@@ -1243,39 +1242,6 @@ namespace StardewModdingAPI.Metadata
             return this.AssertAndNormalizeAssetName(path);
         }
 
-        /// <summary>Get whether a given asset key is equivalent to a normalized asset key, ignoring unimportant differences like capitalization and formatting.</summary>
-        /// <param name="actualKey">The actual key to check.</param>
-        /// <param name="normalizedKey">The key to match, already normalized via <see cref="AssertAndNormalizeAssetName"/> or <see cref="NormalizeAssetNameIgnoringEmpty"/>.</param>
-        private bool IsSameAssetKey(string actualKey, string normalizedKey)
-        {
-            if (actualKey is null || normalizedKey is null)
-                return false;
-
-            return normalizedKey.Equals(PathUtilities.NormalizeAssetName(actualKey), StringComparison.OrdinalIgnoreCase);
-        }
-
-        /// <summary>Get whether a key starts with a substring after the substring is normalized.</summary>
-        /// <param name="key">The key to check.</param>
-        /// <param name="rawSubstring">The substring to normalize and find.</param>
-        private bool KeyStartsWith(string key, string rawSubstring)
-        {
-            if (string.IsNullOrWhiteSpace(key) || string.IsNullOrWhiteSpace(rawSubstring))
-                return false;
-
-            return key.StartsWith(this.NormalizeAssetNameIgnoringEmpty(rawSubstring), StringComparison.OrdinalIgnoreCase);
-        }
-
-        /// <summary>Get whether a normalized asset key is in the given folder.</summary>
-        /// <param name="key">The normalized asset key (like <c>Animals/cat</c>).</param>
-        /// <param name="folder">The key folder (like <c>Animals</c>); doesn't need to be normalized.</param>
-        /// <param name="allowSubfolders">Whether to return true if the key is inside a subfolder of the <paramref name="folder"/>.</param>
-        private bool IsInFolder(string key, string folder, bool allowSubfolders = false)
-        {
-            return
-                this.KeyStartsWith(key, $"{folder}/")
-                && (allowSubfolders || this.CountSegments(key) == this.CountSegments(folder) + 1);
-        }
-
         /// <summary>Get the segments in a path (e.g. 'a/b' is 'a' and 'b').</summary>
         /// <param name="path">The path to check.</param>
         private string[] GetSegments(string path)
@@ -1285,13 +1251,6 @@ namespace StardewModdingAPI.Metadata
                 : Array.Empty<string>();
         }
 
-        /// <summary>Count the number of segments in a path (e.g. 'a/b' is 2).</summary>
-        /// <param name="path">The path to check.</param>
-        private int CountSegments(string path)
-        {
-            return this.GetSegments(path).Length;
-        }
-
         /// <summary>Load a texture, and dispose the old one if <see cref="AggressiveMemoryOptimizations"/> is enabled and it's different from the new instance.</summary>
         /// <param name="oldTexture">The previous texture to dispose.</param>
         /// <param name="key">The asset key to load.</param>
@@ -1315,8 +1274,8 @@ namespace StardewModdingAPI.Metadata
         }
 
         /// <summary>Remove a case-insensitive key from the paint mask cache.</summary>
-        /// <param name="key">The paint mask asset key.</param>
-        private bool RemoveFromPaintMaskCache(string key)
+        /// <param name="assetName">The paint mask asset name.</param>
+        private bool RemoveFromPaintMaskCache(IAssetName assetName)
         {
             // make cache case-insensitive
             // This is needed for cache invalidation since mods may specify keys with a different capitalization
@@ -1324,7 +1283,7 @@ namespace StardewModdingAPI.Metadata
                 BuildingPainter.paintMaskLookup = new Dictionary<string, List<List<int>>>(BuildingPainter.paintMaskLookup, StringComparer.OrdinalIgnoreCase);
 
             // remove key from cache
-            return BuildingPainter.paintMaskLookup.Remove(key);
+            return BuildingPainter.paintMaskLookup.Remove(assetName.Name);
         }
 
         /// <summary>Metadata about a location used in asset propagation.</summary>
-- 
cgit 


From 2d52681b1034d314d8d56c561a5aa72e54e34576 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 19 Feb 2022 11:07:26 -0500
Subject: add Constants.GamePath & deprecate Constants.ExecutionPath

---
 docs/release-notes.md                               | 21 ++++++++++++++-------
 .../Commands/Other/ShowGameFilesCommand.cs          |  6 +++---
 src/SMAPI.Mods.SaveBackup/ModEntry.cs               |  2 +-
 src/SMAPI/Constants.cs                              | 14 +++++++++-----
 src/SMAPI/Framework/ContentCoordinator.cs           |  2 +-
 .../Framework/ContentManagers/BaseContentManager.cs |  2 +-
 src/SMAPI/Program.cs                                | 10 +++++-----
 7 files changed, 34 insertions(+), 23 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index b84f8a06..4cbd1ad9 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -4,20 +4,27 @@
 ## Upcoming release
 * For players:
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+  * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
 
 * 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.
+  * Added `IAssetName Name` field to the info received by `IAssetEditor` and `IAssetLoader` methods.  
+    _This adds methods for working with asset names, parsed locales, etc._
+  * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
+  * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
 
-* For console commands:
-  * Fixed `player_add` with Journal Scraps and Secret Notes.
+* **Deprecation warning for mod authors:**   
+  These APIs are now deprecated and will be removed in the upcoming SMAPI 4.0.0.
+
+  API | how to update code
+  :-- | :-----------------
+  `Constants.ExecutionPath` | Use `Constants.GamePath` instead.
+  `IAssetInfo.AssetName`<br />`IAssetData.AssetName` | Use `Name` instead, which changes the type from `string` to the new `AssetName`.
+  `IAssetInfo.AssetNameEquals`<br />`IAssetData.AssetNameEquals` | Use `Name.IsEquivalentTo` instead.
 
 * For the web UI:
   * Added `data-*` attributes to log parser page for external tools.
-  * Fixed JSON validator warning for update keys without a subkey.
+  * Fixed JSON validator warning shown for update keys without a subkey.
 
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
diff --git a/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Other/ShowGameFilesCommand.cs b/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Other/ShowGameFilesCommand.cs
index 71093184..b97cb3e6 100644
--- a/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Other/ShowGameFilesCommand.cs
+++ b/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Other/ShowGameFilesCommand.cs
@@ -1,4 +1,4 @@
-using System.Diagnostics;
+using System.Diagnostics;
 
 namespace StardewModdingAPI.Mods.ConsoleCommands.Framework.Commands.Other
 {
@@ -18,8 +18,8 @@ namespace StardewModdingAPI.Mods.ConsoleCommands.Framework.Commands.Other
         /// <param name="args">The command arguments.</param>
         public override void Handle(IMonitor monitor, string command, ArgumentParser args)
         {
-            Process.Start(Constants.ExecutionPath);
-            monitor.Log($"OK, opening {Constants.ExecutionPath}.", LogLevel.Info);
+            Process.Start(Constants.GamePath);
+            monitor.Log($"OK, opening {Constants.GamePath}.", LogLevel.Info);
         }
     }
 }
diff --git a/src/SMAPI.Mods.SaveBackup/ModEntry.cs b/src/SMAPI.Mods.SaveBackup/ModEntry.cs
index d6414e9c..b89bb9c3 100644
--- a/src/SMAPI.Mods.SaveBackup/ModEntry.cs
+++ b/src/SMAPI.Mods.SaveBackup/ModEntry.cs
@@ -19,7 +19,7 @@ namespace StardewModdingAPI.Mods.SaveBackup
         private readonly int BackupsToKeep = 10;
 
         /// <summary>The absolute path to the folder in which to store save backups.</summary>
-        private readonly string BackupFolder = Path.Combine(Constants.ExecutionPath, "save-backups");
+        private readonly string BackupFolder = Path.Combine(Constants.GamePath, "save-backups");
 
         /// <summary>A unique label for the save backup to create.</summary>
         private readonly string BackupLabel = $"{DateTime.UtcNow:yyyy-MM-dd} - SMAPI {Constants.ApiVersion} with Stardew Valley {Game1.version}";
diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index 667491d6..810dfe48 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -31,10 +31,10 @@ namespace StardewModdingAPI
         ** Accessors
         *********/
         /// <summary>The path to the game folder.</summary>
-        public static string ExecutionPath { get; } = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
+        public static string GamePath { get; } = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
 
         /// <summary>The absolute path to the folder containing SMAPI's internal files.</summary>
-        public static readonly string InternalFilesPath = Path.Combine(EarlyConstants.ExecutionPath, "smapi-internal");
+        public static readonly string InternalFilesPath = Path.Combine(EarlyConstants.GamePath, "smapi-internal");
 
         /// <summary>The target game platform.</summary>
         internal static GamePlatform Platform { get; } = (GamePlatform)Enum.Parse(typeof(GamePlatform), LowLevelEnvironmentUtility.DetectPlatform());
@@ -77,7 +77,11 @@ namespace StardewModdingAPI
         public static GameFramework GameFramework { get; } = EarlyConstants.GameFramework;
 
         /// <summary>The path to the game folder.</summary>
-        public static string ExecutionPath { get; } = EarlyConstants.ExecutionPath;
+        [Obsolete($"Use {nameof(GamePath)} instead.")]
+        public static string ExecutionPath => Constants.GamePath;
+
+        /// <summary>The path to the game folder.</summary>
+        public static string GamePath { get; } = EarlyConstants.GamePath;
 
         /// <summary>The directory path containing Stardew Valley's app data.</summary>
         public static string DataPath { get; } = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "StardewValley");
@@ -139,7 +143,7 @@ namespace StardewModdingAPI
         internal static string UpdateMarker => Path.Combine(Constants.InternalFilesPath, "StardewModdingAPI.update.marker");
 
         /// <summary>The default full path to search for mods.</summary>
-        internal static string DefaultModsPath { get; } = Path.Combine(Constants.ExecutionPath, "Mods");
+        internal static string DefaultModsPath { get; } = Path.Combine(Constants.GamePath, "Mods");
 
         /// <summary>The actual full path to search for mods.</summary>
         internal static string ModsPath { get; set; }
@@ -222,7 +226,7 @@ namespace StardewModdingAPI
         internal static void ConfigureAssemblyResolver(AssemblyDefinitionResolver resolver)
         {
             // add search paths
-            resolver.AddSearchDirectory(Constants.ExecutionPath);
+            resolver.AddSearchDirectory(Constants.GamePath);
             resolver.AddSearchDirectory(Constants.InternalFilesPath);
 
             // add SMAPI explicitly
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 97a37b3f..00f9439c 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -107,7 +107,7 @@ namespace StardewModdingAPI.Framework
             this.Reflection = reflection;
             this.JsonHelper = jsonHelper;
             this.OnLoadingFirstAsset = onLoadingFirstAsset;
-            this.FullRootDirectory = Path.Combine(Constants.ExecutionPath, rootDirectory);
+            this.FullRootDirectory = Path.Combine(Constants.GamePath, rootDirectory);
             this.ContentManagers.Add(
                 this.MainContentManager = new GameContentManager(
                     name: "Game1.content",
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index be892b33..26f0921d 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -56,7 +56,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; }
diff --git a/src/SMAPI/Program.cs b/src/SMAPI/Program.cs
index 0c90f2aa..f2f65287 100644
--- a/src/SMAPI/Program.cs
+++ b/src/SMAPI/Program.cs
@@ -66,7 +66,7 @@ namespace StardewModdingAPI
             {
                 Program.AssemblyPathsByName = new(StringComparer.OrdinalIgnoreCase);
 
-                foreach (string searchPath in new[] { EarlyConstants.ExecutionPath, Program.DllSearchPath })
+                foreach (string searchPath in new[] { EarlyConstants.GamePath, Program.DllSearchPath })
                 {
                     foreach (string dllPath in Directory.EnumerateFiles(searchPath, "*.dll"))
                     {
@@ -110,7 +110,7 @@ namespace StardewModdingAPI
             catch (Exception ex)
             {
                 // file doesn't exist
-                if (!File.Exists(Path.Combine(EarlyConstants.ExecutionPath, $"{EarlyConstants.GameAssemblyName}.exe")))
+                if (!File.Exists(Path.Combine(EarlyConstants.GamePath, $"{EarlyConstants.GameAssemblyName}.exe")))
                     Program.PrintErrorAndExit("Oops! SMAPI can't find the game. Make sure you're running StardewModdingAPI.exe in your game folder.");
 
                 // can't load file
@@ -160,8 +160,8 @@ namespace StardewModdingAPI
         /// <remarks>This is needed to resolve native DLLs like libSkiaSharp.</remarks>
         private static void AssertDepsJson()
         {
-            string sourcePath = Path.Combine(Constants.ExecutionPath, "Stardew Valley.deps.json");
-            string targetPath = Path.Combine(Constants.ExecutionPath, "StardewModdingAPI.deps.json");
+            string sourcePath = Path.Combine(Constants.GamePath, "Stardew Valley.deps.json");
+            string targetPath = Path.Combine(Constants.GamePath, "StardewModdingAPI.deps.json");
 
             if (!File.Exists(targetPath) || FileUtilities.GetFileHash(sourcePath) != FileUtilities.GetFileHash(targetPath))
             {
@@ -194,7 +194,7 @@ namespace StardewModdingAPI
 
                 // normalise
                 modsPath = !string.IsNullOrWhiteSpace(rawModsPath)
-                    ? Path.Combine(Constants.ExecutionPath, rawModsPath)
+                    ? Path.Combine(Constants.GamePath, rawModsPath)
                     : Constants.DefaultModsPath;
             }
 
-- 
cgit 


From 3c29ae6a1e77ba098b4d9421cacb0fc37510227c Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 19 Feb 2022 11:26:24 -0500
Subject: add Constants.ContentPath

---
 docs/release-notes.md  |  1 +
 src/SMAPI/Constants.cs | 44 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 4cbd1ad9..2448995e 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -7,6 +7,7 @@
   * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
 
 * For mod authors:
+  * Added `Constants.ContentPath`.
   * Added `IAssetName Name` field to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
   * Fixed the `SDate` constructor being case-sensitive.
diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index 810dfe48..b736ca59 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -83,6 +83,9 @@ namespace StardewModdingAPI
         /// <summary>The path to the game folder.</summary>
         public static string GamePath { get; } = EarlyConstants.GamePath;
 
+        /// <summary>The path to the game's <c>Content</c> folder.</summary>
+        public static string ContentPath { get; } = Constants.GetContentFolderPath();
+
         /// <summary>The directory path containing Stardew Valley's app data.</summary>
         public static string DataPath { get; } = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "StardewValley");
 
@@ -297,13 +300,52 @@ namespace StardewModdingAPI
         /*********
         ** Private methods
         *********/
+        /// <summary>Get the absolute path to the game's <c>Content</c> folder.</summary>
+        private static string GetContentFolderPath()
+        {
+            //
+            // We can't use Path.Combine(Constants.GamePath, Game1.content.RootDirectory) here,
+            // since Game1.content isn't initialized until later in the game startup.
+            //
+
+            string gamePath = EarlyConstants.GamePath;
+
+            // most platforms
+            if (EarlyConstants.Platform != GamePlatform.Mac)
+                return Path.Combine(gamePath, "Content");
+
+            // macOS
+            string[] paths = new[]
+                {
+                    // GOG
+                    // - game:    Stardew Valley.app/Contents/MacOS
+                    // - content: Stardew Valley.app/Resources/Content
+                    "../../Resources/Content",
+
+                    // Steam
+                    // - game:    StardewValley/Contents/MacOS
+                    // - content: StardewValley/Contents/Resources/Content
+                    "../Resources/Content"
+                }
+                .Select(path => Path.GetFullPath(Path.Combine(gamePath, path)))
+                .ToArray();
+
+            foreach (string path in paths)
+            {
+                if (Directory.Exists(path))
+                    return path;
+            }
+
+            return paths.Last();
+        }
+
         /// <summary>Get the name of the save folder, if any.</summary>
         private static string GetSaveFolderName()
         {
             return Constants.GetSaveFolder()?.Name;
         }
 
-        /// <summary>Get the path to the current save folder, if any.</summary>
+        /// <summary>Get the absolute path to the current save folder, if any.</summary>
         private static string GetSaveFolderPathIfExists()
         {
             DirectoryInfo saveFolder = Constants.GetSaveFolder();
-- 
cgit 


From f36b4e06ef81f8d48280287058dbea999cd50166 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 25 Feb 2022 23:50:52 -0500
Subject: update release notes

---
 docs/release-notes.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2448995e..29aa24c9 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -7,6 +7,8 @@
   * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
 
 * For mod authors:
+  * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
+    _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
   * Added `IAssetName Name` field to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
-- 
cgit 


From 8429485e696cd4eb9f1f1a6ab50fe2629a1836a0 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sun, 27 Feb 2022 20:40:49 -0500
Subject: update schema for Content Patcher 1.25.0

---
 docs/release-notes.md                              |  1 +
 src/SMAPI.Web/wwwroot/schemas/content-patcher.json | 42 ++++++++++------------
 2 files changed, 20 insertions(+), 23 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 29aa24c9..d92ef63d 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -26,6 +26,7 @@
   `IAssetInfo.AssetNameEquals`<br />`IAssetData.AssetNameEquals` | Use `Name.IsEquivalentTo` instead.
 
 * For the web UI:
+  * Updated the JSON validator/schema for Content Patcher 1.25.0.
   * Added `data-*` attributes to log parser page for external tools.
   * Fixed JSON validator warning shown for update keys without a subkey.
 
diff --git a/src/SMAPI.Web/wwwroot/schemas/content-patcher.json b/src/SMAPI.Web/wwwroot/schemas/content-patcher.json
index 6b80f260..4975a973 100644
--- a/src/SMAPI.Web/wwwroot/schemas/content-patcher.json
+++ b/src/SMAPI.Web/wwwroot/schemas/content-patcher.json
@@ -14,9 +14,9 @@
             "title": "Format version",
             "description": "The format version. You should always use the latest version to enable the latest features, avoid obsolete behavior, and reduce load times.",
             "type": "string",
-            "const": "1.24.0",
+            "const": "1.25.0",
             "@errorMessages": {
-                "const": "Incorrect value '@value'. You should always use the latest format version (currently 1.24.0) to enable the latest features, avoid obsolete behavior, and reduce load times."
+                "const": "Incorrect value '@value'. You should always use the latest format version (currently 1.25.0) to enable the latest features, avoid obsolete behavior, and reduce load times."
             }
         },
         "ConfigSchema": {
@@ -159,6 +159,14 @@
                 "additionalProperties": false
             }
         },
+        "AliasTokenNames": {
+            "title": "Alias token names",
+            "description": "Defines optional alternate name for existing tokens. This only affects your content pack, and you can use both the alias name and the original token name. This is mostly useful for custom tokens provided by other mods, which often have longer names. Each entry key is the alias name, and the value is the original token name.",
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
         "Changes": {
             "title": "Changes",
             "description": "The changes you want to make. Each entry is called a patch, and describes a specific action to perform: replace this file, copy this image into the file, etc. You can list any number of patches.",
@@ -187,22 +195,6 @@
                         "description": "A name for this patch shown in log messages. This is very useful for understanding errors; if not specified, will default to a name like 'entry #14 (EditImage Animals/Dinosaurs)'.",
                         "type": "string"
                     },
-                    "Enabled": {
-                        "title": "Enabled",
-                        "description": "Whether to apply this patch. Default true. This field does not allow tokens.",
-                        "anyOf": [
-                            {
-                                "type": "boolean"
-                            },
-                            {
-                                "type": "string",
-                                "enum": [ "true", "false" ]
-                            }
-                        ],
-                        "@errorMessages": {
-                            "anyOf": "Invalid value; must be true, false, or a single token which evaluates to true or false."
-                        }
-                    },
                     "Update": {
                         "title": "Update",
                         "description": "When the patch should update if it changed. The possible values are 'OnDayStart', 'OnLocationChange', or 'OnTimeChange' (defaults to OnDayStart).",
@@ -241,6 +233,14 @@
                         "description": "The part of the target image to replace. Defaults to the FromArea size starting from the top-left corner.",
                         "$ref": "#/definitions/Rectangle"
                     },
+                    "TargetField": {
+                        "title": "Target field",
+                        "description": "The path to the field within the value to set as the root scope. See 'target field' in the EditData documentation for more info. This field supports tokens.",
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
                     "Fields": {
                         "title": "Fields",
                         "description": "The individual fields you want to change for existing entries. This field supports tokens in field keys and values. The key for each field is the field index (starting at zero) for a slash-delimited string, or the field name for an object.",
@@ -408,7 +408,6 @@
                             "propertyNames": {
                                 "enum": [
                                     "Action",
-                                    "Enabled",
                                     "FromFile",
                                     "LogName",
                                     "Target",
@@ -438,7 +437,6 @@
                             "propertyNames": {
                                 "enum": [
                                     "Action",
-                                    "Enabled",
                                     "FromFile",
                                     "LogName",
                                     "Target",
@@ -462,12 +460,12 @@
                             "propertyNames": {
                                 "enum": [
                                     "Action",
-                                    "Enabled",
                                     "LogName",
                                     "Target",
                                     "Update",
                                     "When",
 
+                                    "TargetField",
                                     "Entries",
                                     "Fields",
                                     "MoveEntries",
@@ -504,7 +502,6 @@
                             "propertyNames": {
                                 "enum": [
                                     "Action",
-                                    "Enabled",
                                     "FromFile",
                                     "LogName",
                                     "Target",
@@ -533,7 +530,6 @@
                             "propertyNames": {
                                 "enum": [
                                     "Action",
-                                    "Enabled",
                                     "FromFile",
                                     "LogName",
                                     "Update",
-- 
cgit 


From 2216e37726874af6ab164dbbaef454eb0f2218d0 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sun, 6 Mar 2022 19:55:32 -0500
Subject: rework launch script argument parsing (#832)

This commit...

* replaces the internal `--no-reopen-terminal` arg with a documented `--use-current-shell` arg that works on Linux too;
* replaces the new SKIP_TERMINAL environment variable with the existing SMAPI_NO_TERMINAL one;
* moves argument parsing out of the 'initial setup' section (so it's easier for players to edit if needed);
* simplfies argument parsing (no need to support short opt names or add arguments for the default behavior);
* fixes arguments not parsed after the first unrecognized argument, so `--unknown --no-terminal` would still open a terminal.
---
 docs/release-notes.md                       |  3 ++
 docs/technical/smapi.md                     | 10 +++--
 src/SMAPI.Installer/assets/unix-launcher.sh | 61 ++++++++++++++++++-----------
 3 files changed, 47 insertions(+), 27 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index d92ef63d..3030cc5d 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -5,6 +5,9 @@
 * For players:
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
   * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
+  * Improved [command-line arguments](technical/smapi.md#command-line-arguments) on Linux/macOS:
+    * Added `--use-current-shell` to avoid opening a separate terminal window.
+    * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
 
 * For mod authors:
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
index d9aad875..7da1e0f1 100644
--- a/docs/technical/smapi.md
+++ b/docs/technical/smapi.md
@@ -38,18 +38,20 @@ or testing and may change without warning. On Linux/macOS, see _environment vari
 
 argument | purpose
 -------- | -------
-`--no-terminal` | SMAPI won't write anything to the console window. (Messages will still be written to the log file.)
+`--no-terminal` | The SMAPI launcher won't try to open a terminal window, and SMAPI won't log anything to the console. (Messages will still be written to the log file.)
+`--use-current-shell` | The SMAPI launcher won't try to open a terminal window, but SMAPI will still log to the console. (Messages will still be written to the log file.)
 `--mods-path` | The path to search for mods, if not the standard `Mods` folder. This can be a path relative to the game folder (like `--mods-path "Mods (test)"`) or an absolute path.
 
 ### Environment variables
-The above SMAPI arguments don't work on Linux/macOS due to the way the game launcher works. You can
-set temporary environment variables instead. For example:
+The above SMAPI arguments may not work on Linux/macOS due to the way the game launcher works. You
+can set temporary environment variables instead. For example:
 > SMAPI_MODS_PATH="Mods (multiplayer)" /path/to/StardewValley
 
 environment variable | purpose
 -------------------- | -------
-`SMAPI_NO_TERMINAL` | Equivalent to `--no-terminal` above.
 `SMAPI_MODS_PATH` | Equivalent to `--mods-path` above.
+`SMAPI_NO_TERMINAL` | Equivalent to `--no-terminal` above.
+`SMAPI_USE_CURRENT_SHELL` | Equivalent to `--use-current-shell` above.
 
 ### Compile flags
 SMAPI uses a small number of conditional compilation constants, which you can set by editing the
diff --git a/src/SMAPI.Installer/assets/unix-launcher.sh b/src/SMAPI.Installer/assets/unix-launcher.sh
index 6e8d4df3..ae9624e7 100644
--- a/src/SMAPI.Installer/assets/unix-launcher.sh
+++ b/src/SMAPI.Installer/assets/unix-launcher.sh
@@ -6,19 +6,40 @@
 # move to script's directory
 cd "$(dirname "$0")" || exit $?
 
-# change to true to skip opening a terminal
+# Whether to avoid opening a separate terminal window, and avoid logging anything to the console.
 # This isn't recommended since you won't see errors, warnings, and update alerts.
-OPTS=`getopt -o St --long skip-terminal,terminal -n 'parse-options' -- "$@"`
-while true; do
-  case "$1" in
-    -S | --skip-terminal ) SKIP_TERMINAL=true; shift ;;
-    -t | --terminal ) SKIP_TERMINAL=false; shift ;;
-    -- ) shift; break ;;
-    * ) break ;;
-  esac
+SKIP_TERMINAL=false
+
+# Whether to avoid opening a separate terminal, but still send the usual log output to the console.
+USE_CURRENT_SHELL=false
+
+
+##########
+## Read environment variables
+##########
+if [ "$SMAPI_NO_TERMINAL" == "true" ]; then
+    SKIP_TERMINAL=true
+fi
+if [ "$SMAPI_USE_CURRENT_SHELL" == "true" ]; then
+    USE_CURRENT_SHELL=true
+fi
+
+
+##########
+## Read command-line arguments
+##########
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --skip-terminal ) SKIP_TERMINAL=true; shift ;;
+        --use-current-shell ) USE_CURRENT_SHELL=true; shift ;;
+        -- ) shift; break ;;
+        * ) shift ;;
+    esac
 done
 
-${SKIP_TERMINAL:=false}
+if [ "$SKIP_TERMINAL" == "true" ]; then
+    USE_CURRENT_SHELL=true
+fi
 
 
 ##########
@@ -28,21 +49,13 @@ ${SKIP_TERMINAL:=false}
 # Besides letting the player see errors/warnings/alerts in the console, this is also needed because
 # Steam messes with the PATH.
 if [ "$(uname)" == "Darwin" ]; then
-    if [ ! -t 1 ]; then # https://stackoverflow.com/q/911168/262123
-        # sanity check to make sure we don't have an infinite loop of opening windows
-        for argument in "$@"; do
-            if [ "$argument" == "--no-reopen-terminal" ]; then
-                SKIP_TERMINAL=true
-                break
-            fi
-        done
-
+    if [ ! -t 1 ]; then # not open in Terminal (https://stackoverflow.com/q/911168/262123)
         # reopen in Terminal if needed
         # https://stackoverflow.com/a/29511052/262123
-        if [ "$SKIP_TERMINAL" == "false" ]; then
+        if [ "$USE_CURRENT_SHELL" == "false" ]; then
             echo "Reopening in the Terminal app..."
             echo '#!/bin/sh' > /tmp/open-smapi-terminal.sh
-            echo "\"$0\" $@ --no-reopen-terminal" >> /tmp/open-smapi-terminal.sh
+            echo "\"$0\" $@ --use-current-shell" >> /tmp/open-smapi-terminal.sh
             chmod +x /tmp/open-smapi-terminal.sh
             cat /tmp/open-smapi-terminal.sh
             open -W -a Terminal /tmp/open-smapi-terminal.sh
@@ -78,7 +91,7 @@ else
     export LAUNCH_FILE
 
     # run in terminal
-    if [ "$SKIP_TERMINAL" == "false" ]; then
+    if [ "$USE_CURRENT_SHELL" == "false" ]; then
         # select terminal (prefer xterm for best compatibility, then known supported terminals)
         for terminal in xterm gnome-terminal kitty terminator xfce4-terminal konsole terminal termite alacritty mate-terminal x-terminal-emulator; do
             if command -v "$terminal" 2>/dev/null; then
@@ -141,7 +154,9 @@ else
         fi
 
     # explicitly run without terminal
-    else
+    elif [ "$SKIP_TERMINAL" == "true" ]; then
         exec $LAUNCH_FILE --no-terminal "$@"
+    else
+        exec $LAUNCH_FILE "$@"
     fi
 fi
-- 
cgit 


From d96cec88e461806c4676c9280455da19f5c7af24 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 10 Mar 2022 23:24:01 -0500
Subject: fix set_farm_type not updating warps

---
 docs/release-notes.md                                                    | 1 +
 .../Framework/Commands/Player/SetFarmTypeCommand.cs                      | 1 +
 2 files changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 3030cc5d..2598dad5 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -5,6 +5,7 @@
 * For players:
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
   * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
+  * Fixed `set_farm_type` console command not updating warps if they moved.
   * Improved [command-line arguments](technical/smapi.md#command-line-arguments) on Linux/macOS:
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
diff --git a/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Player/SetFarmTypeCommand.cs b/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Player/SetFarmTypeCommand.cs
index 6b3b27cd..6fb399ae 100644
--- a/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Player/SetFarmTypeCommand.cs
+++ b/src/SMAPI.Mods.ConsoleCommands/Framework/Commands/Player/SetFarmTypeCommand.cs
@@ -131,6 +131,7 @@ namespace StardewModdingAPI.Mods.ConsoleCommands.Framework.Commands.Player
             Farm farm = Game1.getFarm();
             farm.mapPath.Value = $@"Maps\{Farm.getMapNameFromTypeInt(Game1.whichFarm)}";
             farm.reloadMap();
+            farm.updateWarps();
 
             // clear spouse area cache to avoid errors
             FieldInfo cacheField = farm.GetType().GetField("_baseSpouseAreaTiles", BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public);
-- 
cgit 


From b07d2340a9a6da22ee0fd95f2c6ccca3939cb7ab Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Tue, 22 Mar 2022 23:00:18 -0400
Subject: encapsulate & cache asset operation groups (#766)

This is needed for the upcoming Stardew Valley 1.6 to avoid duplicate checks between DoesAssetExist and Load calls, and to make sure the answer doesn't change between them.
---
 docs/release-notes.md                              |   1 +
 src/SMAPI/Framework/Content/AssetOperationGroup.cs |  33 +++++++
 src/SMAPI/Framework/ContentCoordinator.cs          | 100 ++++++++++++++++++---
 .../ContentManagers/GameContentManager.cs          |  44 ++-------
 .../Framework/Utilities/TickCacheDictionary.cs     |  51 +++++++++++
 5 files changed, 180 insertions(+), 49 deletions(-)
 create mode 100644 src/SMAPI/Framework/Content/AssetOperationGroup.cs
 create mode 100644 src/SMAPI/Framework/Utilities/TickCacheDictionary.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2598dad5..b9385e3f 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -16,6 +16,7 @@
   * Added `Constants.ContentPath`.
   * Added `IAssetName Name` field to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
+  * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated via `helper.Content.InvalidateCache`.
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
diff --git a/src/SMAPI/Framework/Content/AssetOperationGroup.cs b/src/SMAPI/Framework/Content/AssetOperationGroup.cs
new file mode 100644
index 00000000..a2fcb722
--- /dev/null
+++ b/src/SMAPI/Framework/Content/AssetOperationGroup.cs
@@ -0,0 +1,33 @@
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>A set of operations to apply to an asset for a given <see cref="IAssetEditor"/> or <see cref="IAssetLoader"/> implementation.</summary>
+    internal class AssetOperationGroup
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The mod applying the changes.</summary>
+        public IModMetadata Mod { get; }
+
+        /// <summary>The load operations to apply.</summary>
+        public AssetLoadOperation[] LoadOperations { get; }
+
+        /// <summary>The edit operations to apply.</summary>
+        public AssetEditOperation[] EditOperations { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="mod">The mod applying the changes.</param>
+        /// <param name="loadOperations">The load operations to apply.</param>
+        /// <param name="editOperations">The edit operations to apply.</param>
+        public AssetOperationGroup(IModMetadata mod, AssetLoadOperation[] loadOperations, AssetEditOperation[] editOperations)
+        {
+            this.Mod = mod;
+            this.LoadOperations = loadOperations;
+            this.EditOperations = editOperations;
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index fbbbe2d2..bf944e23 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -10,6 +10,8 @@ using Microsoft.Xna.Framework.Content;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Reflection;
+using StardewModdingAPI.Framework.Utilities;
+using StardewModdingAPI.Internal;
 using StardewModdingAPI.Metadata;
 using StardewModdingAPI.Toolkit.Serialization;
 using StardewModdingAPI.Toolkit.Utilities;
@@ -68,6 +70,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>The language enum values indexed by locale code.</summary>
         private Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>> LocaleCodes;
 
+        /// <summary>The cached asset load/edit operations to apply, indexed by asset name.</summary>
+        private readonly TickCacheDictionary<IAssetName, AssetOperationGroup[]> AssetOperationsByKey = new();
+
 
         /*********
         ** Accessors
@@ -351,17 +356,17 @@ namespace StardewModdingAPI.Framework
         public IEnumerable<IAssetName> InvalidateCache(Func<IContentManager, string, Type, bool> predicate, bool dispose = false)
         {
             // invalidate cache & track removed assets
-            IDictionary<IAssetName, Type> removedAssets = new Dictionary<IAssetName, Type>();
+            IDictionary<IAssetName, Type> invalidatedAssets = new Dictionary<IAssetName, Type>();
             this.ContentManagerLock.InReadLock(() =>
             {
                 // cached assets
                 foreach (IContentManager contentManager in this.ContentManagers)
                 {
-                    foreach (var entry in contentManager.InvalidateCache((key, type) => predicate(contentManager, key, type), dispose))
+                    foreach ((string key, object asset) in contentManager.InvalidateCache((key, type) => predicate(contentManager, key, type), dispose))
                     {
-                        AssetName assetName = this.ParseAssetName(entry.Key);
-                        if (!removedAssets.ContainsKey(assetName))
-                            removedAssets[assetName] = entry.Value.GetType();
+                        AssetName assetName = this.ParseAssetName(key);
+                        if (!invalidatedAssets.ContainsKey(assetName))
+                            invalidatedAssets[assetName] = asset.GetType();
                     }
                 }
 
@@ -376,18 +381,22 @@ namespace StardewModdingAPI.Framework
 
                         // get map path
                         AssetName mapPath = this.ParseAssetName(this.MainContentManager.AssertAndNormalizeAssetName(location.mapPath.Value));
-                        if (!removedAssets.ContainsKey(mapPath) && predicate(this.MainContentManager, mapPath.Name, typeof(Map)))
-                            removedAssets[mapPath] = typeof(Map);
+                        if (!invalidatedAssets.ContainsKey(mapPath) && predicate(this.MainContentManager, mapPath.Name, typeof(Map)))
+                            invalidatedAssets[mapPath] = typeof(Map);
                     }
                 }
             });
 
+            // clear cached editor checks
+            foreach (IAssetName name in invalidatedAssets.Keys)
+                this.AssetOperationsByKey.Remove(name);
+
             // reload core game assets
-            if (removedAssets.Any())
+            if (invalidatedAssets.Any())
             {
                 // propagate changes to the game
                 this.CoreAssets.Propagate(
-                    assets: removedAssets.ToDictionary(p => p.Key, p => p.Value),
+                    assets: invalidatedAssets.ToDictionary(p => p.Key, p => p.Value),
                     ignoreWorld: Context.IsWorldFullyUnloaded,
                     out IDictionary<IAssetName, bool> propagated,
                     out bool updatedNpcWarps
@@ -396,7 +405,7 @@ namespace StardewModdingAPI.Framework
                 // log summary
                 StringBuilder report = new();
                 {
-                    IAssetName[] invalidatedKeys = removedAssets.Keys.ToArray();
+                    IAssetName[] invalidatedKeys = invalidatedAssets.Keys.ToArray();
                     IAssetName[] propagatedKeys = propagated.Where(p => p.Value).Select(p => p.Key).ToArray();
 
                     string FormatKeyList(IEnumerable<IAssetName> keys) => string.Join(", ", keys.Select(p => p.Name).OrderBy(p => p, StringComparer.OrdinalIgnoreCase));
@@ -414,7 +423,18 @@ namespace StardewModdingAPI.Framework
             else
                 this.Monitor.Log("Invalidated 0 cache entries.");
 
-            return removedAssets.Keys;
+            return invalidatedAssets.Keys;
+        }
+
+        /// <summary>Get the asset load and edit operations to apply to a given asset if it's (re)loaded now.</summary>
+        /// <typeparam name="T">The asset type.</typeparam>
+        /// <param name="info">The asset info to load or edit.</param>
+        public IEnumerable<AssetOperationGroup> GetAssetOperations<T>(IAssetInfo info)
+        {
+            return this.AssetOperationsByKey.GetOrSet(
+                info.Name,
+                () => this.GetAssetOperationsWithoutCache<T>(info).ToArray()
+            );
         }
 
         /// <summary>Get all loaded instances of an asset name.</summary>
@@ -534,5 +554,63 @@ namespace StardewModdingAPI.Framework
 
             return map;
         }
+
+        /// <summary>Get the asset load and edit operations to apply to a given asset if it's (re)loaded now, ignoring the <see cref="AssetOperationsByKey"/> cache.</summary>
+        /// <typeparam name="T">The asset type.</typeparam>
+        /// <param name="info">The asset info to load or edit.</param>
+        private IEnumerable<AssetOperationGroup> GetAssetOperationsWithoutCache<T>(IAssetInfo info)
+        {
+            // legacy load operations
+            foreach (ModLinked<IAssetLoader> loader in this.Loaders)
+            {
+                // check if loader applies
+                try
+                {
+                    if (!loader.Data.CanLoad<T>(info))
+                        continue;
+                }
+                catch (Exception ex)
+                {
+                    loader.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    continue;
+                }
+
+                // add operation
+                yield return new AssetOperationGroup(
+                    mod: loader.Mod,
+                    loadOperations: new[]
+                    {
+                        new AssetLoadOperation(loader.Mod, assetInfo => loader.Data.Load<T>(assetInfo))
+                    },
+                    editOperations: Array.Empty<AssetEditOperation>()
+                );
+            }
+
+            // legacy edit operations
+            foreach (var editor in this.Editors)
+            {
+                // check if editor applies
+                try
+                {
+                    if (!editor.Data.CanEdit<T>(info))
+                        continue;
+                }
+                catch (Exception ex)
+                {
+                    editor.Mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    continue;
+                }
+
+                // add operation
+                yield return new AssetOperationGroup(
+                    mod: editor.Mod,
+                    loadOperations: Array.Empty<AssetLoadOperation>(),
+                    editOperations: new[]
+                    {
+                        new AssetEditOperation(editor.Mod, assetData => editor.Data.Edit<T>(assetData))
+                    }
+                );
+            }
+        }
     }
 }
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 7ed1fcda..642e526c 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -26,12 +26,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <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();
 
-        /// <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;
 
@@ -370,22 +364,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="info">The basic asset metadata.</param>
         private IEnumerable<AssetLoadOperation> GetLoaders<T>(IAssetInfo info)
         {
-            return this.Loaders
-                .Where(loader =>
-                {
-                    try
-                    {
-                        return loader.Data.CanLoad<T>(info);
-                    }
-                    catch (Exception ex)
-                    {
-                        loader.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
-                        return false;
-                    }
-                })
-                .Select(
-                    loader => new AssetLoadOperation(loader.Mod, assetInfo => loader.Data.Load<T>(assetInfo))
-                );
+            return this.Coordinator
+                .GetAssetOperations<T>(info)
+                .SelectMany(p => p.LoadOperations);
         }
 
         /// <summary>Get the asset editors to apply to an asset.</summary>
@@ -393,22 +374,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="info">The basic asset metadata.</param>
         private IEnumerable<AssetEditOperation> GetEditors<T>(IAssetInfo info)
         {
-            return this.Editors
-                .Where(editor =>
-                {
-                    try
-                    {
-                        return editor.Data.CanEdit<T>(info);
-                    }
-                    catch (Exception ex)
-                    {
-                        editor.Mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
-                        return false;
-                    }
-                })
-                .Select(
-                    editor => new AssetEditOperation(editor.Mod, assetData => editor.Data.Edit<T>(assetData))
-                );
+            return this.Coordinator
+                .GetAssetOperations<T>(info)
+                .SelectMany(p => p.EditOperations);
         }
 
         /// <summary>Assert that at most one loader will be applied to an asset.</summary>
diff --git a/src/SMAPI/Framework/Utilities/TickCacheDictionary.cs b/src/SMAPI/Framework/Utilities/TickCacheDictionary.cs
new file mode 100644
index 00000000..1613a480
--- /dev/null
+++ b/src/SMAPI/Framework/Utilities/TickCacheDictionary.cs
@@ -0,0 +1,51 @@
+using System;
+using System.Collections.Generic;
+using StardewValley;
+
+namespace StardewModdingAPI.Framework.Utilities
+{
+    /// <summary>An in-memory dictionary cache that stores data for the duration of a game update tick.</summary>
+    /// <typeparam name="TKey">The dictionary key type.</typeparam>
+    /// <typeparam name="TValue">The dictionary value type.</typeparam>
+    internal class TickCacheDictionary<TKey, TValue>
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The last game tick for which data was cached.</summary>
+        private int LastGameTick = -1;
+
+        /// <summary>The underlying cached data.</summary>
+        private readonly Dictionary<TKey, TValue> Cache = new();
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get a value from the cache, fetching it first if it's not cached yet.</summary>
+        /// <param name="cacheKey">The unique key for the cached value.</param>
+        /// <param name="get">Get the latest data if it's not in the cache yet.</param>
+        public TValue GetOrSet(TKey cacheKey, Func<TValue> get)
+        {
+            // clear cache on new tick
+            if (Game1.ticks != this.LastGameTick)
+            {
+                this.Cache.Clear();
+                this.LastGameTick = Game1.ticks;
+            }
+
+            // fetch value
+            if (!this.Cache.TryGetValue(cacheKey, out TValue cached))
+                this.Cache[cacheKey] = cached = get();
+            return cached;
+        }
+
+        /// <summary>Remove an entry from the cache.</summary>
+        /// <param name="cacheKey">The unique key for the cached value.</param>
+        /// <returns>Returns whether the key was present in the dictionary.</returns>
+        public bool Remove(TKey cacheKey)
+        {
+            return this.Cache.Remove(cacheKey);
+        }
+    }
+}
-- 
cgit 


From 584725bb8e554e314843315facca1fd15868bee4 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Wed, 23 Mar 2022 01:06:11 -0400
Subject: add initial AssetRequested content event (#766)

---
 docs/release-notes.md                          |  1 +
 src/SMAPI/Events/AssetRequestedEventArgs.cs    | 94 ++++++++++++++++++++++++++
 src/SMAPI/Events/IContentEvents.cs             | 17 +++++
 src/SMAPI/Events/IModEvents.cs                 |  3 +
 src/SMAPI/Framework/ContentCoordinator.cs      | 12 +++-
 src/SMAPI/Framework/Events/EventManager.cs     | 11 ++-
 src/SMAPI/Framework/Events/ManagedEvent.cs     | 10 ++-
 src/SMAPI/Framework/Events/ModContentEvents.cs | 29 ++++++++
 src/SMAPI/Framework/Events/ModEvents.cs        |  4 ++
 src/SMAPI/Framework/SCore.cs                   | 41 ++++++++++-
 src/SMAPI/IContentHelper.cs                    |  2 +-
 11 files changed, 219 insertions(+), 5 deletions(-)
 create mode 100644 src/SMAPI/Events/AssetRequestedEventArgs.cs
 create mode 100644 src/SMAPI/Events/IContentEvents.cs
 create mode 100644 src/SMAPI/Framework/Events/ModContentEvents.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index b9385e3f..2d1cdf44 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -11,6 +11,7 @@
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
 
 * For mod authors:
+  * Added [`AssetRequested` content event](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will eventually replace `IAssetEditor` and `IAssetLoader`.
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
     _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Events/AssetRequestedEventArgs.cs b/src/SMAPI/Events/AssetRequestedEventArgs.cs
new file mode 100644
index 00000000..b17250b0
--- /dev/null
+++ b/src/SMAPI/Events/AssetRequestedEventArgs.cs
@@ -0,0 +1,94 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+using StardewModdingAPI.Framework;
+using StardewModdingAPI.Framework.Content;
+using xTile;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IContentEvents.AssetRequested"/> event.</summary>
+    public class AssetRequestedEventArgs : EventArgs
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The mod handling the event.</summary>
+        private readonly IModMetadata Mod;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The name of the asset being requested.</summary>
+        public IAssetName Name { get; }
+
+        /// <summary>The load operations requested by the event handler.</summary>
+        internal IList<AssetLoadOperation> LoadOperations { get; } = new List<AssetLoadOperation>();
+
+        /// <summary>The edit operations requested by the event handler.</summary>
+        internal IList<AssetEditOperation> EditOperations { get; } = new List<AssetEditOperation>();
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="mod">The mod handling the event.</param>
+        /// <param name="name">The name of the asset being requested.</param>
+        internal AssetRequestedEventArgs(IModMetadata mod, IAssetName name)
+        {
+            this.Mod = mod;
+            this.Name = name;
+        }
+
+        /// <summary>Provide the initial instance for the asset, instead of trying to load it from the game's <c>Content</c> folder.</summary>
+        /// <param name="load">Get the initial instance of an asset.</param>
+        /// <remarks>
+        /// Usage notes:
+        /// <list type="bullet">
+        ///   <item>The asset doesn't need to exist in the game's <c>Content</c> folder. If any mod loads the asset, the game will see it as an existing asset as if it was in that folder.</item>
+        ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will raise an error and ignore all of them. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
+        /// </list>
+        /// </remarks>
+        public void LoadFrom(Func<object> load)
+        {
+            this.LoadOperations.Add(
+                new AssetLoadOperation(this.Mod, _ => load())
+            );
+        }
+
+        /// <summary>Provide the initial instance for the asset from a file in your mod folder, instead of trying to load it from the game's <c>Content</c> folder.</summary>
+        /// <typeparam name="TAsset">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
+        /// <param name="relativePath">The relative path to the file in your mod folder.</param>
+        /// <remarks>
+        /// Usage notes:
+        /// <list type="bullet">
+        ///   <item>The asset doesn't need to exist in the game's <c>Content</c> folder. If any mod loads the asset, the game will see it as an existing asset as if it was in that folder.</item>
+        ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will raise an error and ignore all of them. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
+        /// </list>
+        /// </remarks>
+        public void LoadFromModFile<TAsset>(string relativePath)
+        {
+            this.LoadOperations.Add(
+                new AssetLoadOperation(this.Mod, _ => this.Mod.Mod.Helper.Content.Load<TAsset>(relativePath))
+            );
+        }
+
+        /// <summary>Edit the asset after it's loaded.</summary>
+        /// <param name="apply">Apply changes to the asset.</param>
+        /// <remarks>
+        /// Usage notes:
+        /// <list type="bullet">
+        ///   <item>Editing an asset which doesn't exist has no effect. This is applied after the asset is loaded from the game's <c>Content</c> folder, or from any mod's <see cref="LoadFrom"/> or <see cref="LoadFromModFile{TAsset}"/>.</item>
+        ///   <item>You can apply any number of edits to the asset. Each edit will be applied on top of the previous one (i.e. it'll see the merged asset from all previous edits as its input).</item>
+        /// </list>
+        /// </remarks>
+        public void Edit(Action<IAssetData> apply)
+        {
+            this.EditOperations.Add(
+                new AssetEditOperation(this.Mod, apply)
+            );
+        }
+    }
+}
diff --git a/src/SMAPI/Events/IContentEvents.cs b/src/SMAPI/Events/IContentEvents.cs
new file mode 100644
index 00000000..feaf9c0a
--- /dev/null
+++ b/src/SMAPI/Events/IContentEvents.cs
@@ -0,0 +1,17 @@
+using System;
+using StardewValley;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Events related to assets loaded from the content pipeline (including data, maps, and textures).</summary>
+    public interface IContentEvents
+    {
+        /// <summary>Raised when an asset is being requested from the content pipeline.</summary>
+        /// <remarks>
+        /// The asset isn't necessarily being loaded yet (e.g. the game may be checking if it exists). Mods can register the changes they want to apply using methods on the <paramref name="e"/> parameter. These will be applied when the asset is actually loaded.
+        ///
+        /// If the asset is requested multiple times in the same tick (e.g. once to check if it exists and once to load it), SMAPI might only raise the event once and reuse the cached result.
+        /// </remarks>
+        event EventHandler<AssetRequestedEventArgs> AssetRequested;
+    }
+}
diff --git a/src/SMAPI/Events/IModEvents.cs b/src/SMAPI/Events/IModEvents.cs
index 1f892b31..2603961b 100644
--- a/src/SMAPI/Events/IModEvents.cs
+++ b/src/SMAPI/Events/IModEvents.cs
@@ -3,6 +3,9 @@ namespace StardewModdingAPI.Events
     /// <summary>Manages access to events raised by SMAPI.</summary>
     public interface IModEvents
     {
+        /// <summary>Events related to assets loaded from the content pipeline (including data, maps, and textures).</summary>
+        IContentEvents Content { get; }
+
         /// <summary>Events related to UI and drawing to the screen.</summary>
         IDisplayEvents Display { get; }
 
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index bf944e23..22ae0a18 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -7,6 +7,7 @@ using System.Linq;
 using System.Text;
 using System.Threading;
 using Microsoft.Xna.Framework.Content;
+using StardewModdingAPI.Events;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Reflection;
@@ -70,6 +71,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>The language enum values indexed by locale code.</summary>
         private Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>> LocaleCodes;
 
+        /// <summary>Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</summary>
+        private readonly Func<IAssetInfo, IList<AssetOperationGroup>> RequestAssetOperations;
+
         /// <summary>The cached asset load/edit operations to apply, indexed by asset name.</summary>
         private readonly TickCacheDictionary<IAssetName, AssetOperationGroup[]> AssetOperationsByKey = new();
 
@@ -105,13 +109,15 @@ namespace StardewModdingAPI.Framework
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
         /// <param name="onLoadingFirstAsset">A callback to invoke the first time *any* game content manager loads an asset.</param>
         /// <param name="aggressiveMemoryOptimizations">Whether to enable more aggressive memory optimizations.</param>
-        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, bool aggressiveMemoryOptimizations)
+        /// <param name="requestAssetOperations">Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</param>
+        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, bool aggressiveMemoryOptimizations, Func<IAssetInfo, IList<AssetOperationGroup>> requestAssetOperations)
         {
             this.AggressiveMemoryOptimizations = aggressiveMemoryOptimizations;
             this.Monitor = monitor ?? throw new ArgumentNullException(nameof(monitor));
             this.Reflection = reflection;
             this.JsonHelper = jsonHelper;
             this.OnLoadingFirstAsset = onLoadingFirstAsset;
+            this.RequestAssetOperations = requestAssetOperations;
             this.FullRootDirectory = Path.Combine(Constants.GamePath, rootDirectory);
             this.ContentManagers.Add(
                 this.MainContentManager = new GameContentManager(
@@ -560,6 +566,10 @@ namespace StardewModdingAPI.Framework
         /// <param name="info">The asset info to load or edit.</param>
         private IEnumerable<AssetOperationGroup> GetAssetOperationsWithoutCache<T>(IAssetInfo info)
         {
+            // new content API
+            foreach (AssetOperationGroup group in this.RequestAssetOperations(info))
+                yield return group;
+
             // legacy load operations
             foreach (ModLinked<IAssetLoader> loader in this.Loaders)
             {
diff --git a/src/SMAPI/Framework/Events/EventManager.cs b/src/SMAPI/Framework/Events/EventManager.cs
index fa4d564d..8142f00e 100644
--- a/src/SMAPI/Framework/Events/EventManager.cs
+++ b/src/SMAPI/Framework/Events/EventManager.cs
@@ -10,6 +10,13 @@ namespace StardewModdingAPI.Framework.Events
         /*********
         ** Events
         *********/
+        /****
+        ** Content
+        ****/
+        /// <inheritdoc cref="IContentEvents.AssetRequested" />
+        public readonly ManagedEvent<AssetRequestedEventArgs> AssetRequested;
+
+
         /****
         ** Display
         ****/
@@ -189,7 +196,9 @@ namespace StardewModdingAPI.Framework.Events
                 return new ManagedEvent<TEventArgs>($"{typeName}.{eventName}", modRegistry, isPerformanceCritical);
             }
 
-            // init events (new)
+            // init events
+            this.AssetRequested = ManageEventOf<AssetRequestedEventArgs>(nameof(IModEvents.Content), nameof(IContentEvents.AssetRequested));
+
             this.MenuChanged = ManageEventOf<MenuChangedEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.MenuChanged));
             this.Rendering = ManageEventOf<RenderingEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.Rendering), isPerformanceCritical: true);
             this.Rendered = ManageEventOf<RenderedEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.Rendered), isPerformanceCritical: true);
diff --git a/src/SMAPI/Framework/Events/ManagedEvent.cs b/src/SMAPI/Framework/Events/ManagedEvent.cs
index a200393d..154ef659 100644
--- a/src/SMAPI/Framework/Events/ManagedEvent.cs
+++ b/src/SMAPI/Framework/Events/ManagedEvent.cs
@@ -99,6 +99,14 @@ namespace StardewModdingAPI.Framework.Events
         /// <param name="args">The event arguments to pass.</param>
         /// <param name="match">A lambda which returns true if the event should be raised for the given mod.</param>
         public void Raise(TEventArgs args, Func<IModMetadata, bool> match = null)
+        {
+            this.Raise((_, invoke) => invoke(args), match);
+        }
+
+        /// <summary>Raise the event and notify all handlers.</summary>
+        /// <param name="invoke">Invoke an event handler. This receives the mod which registered the handler, and should invoke the callback with the event arguments to pass it.</param>
+        /// <param name="match">A lambda which returns true if the event should be raised for the given mod.</param>
+        public void Raise(Action<IModMetadata, Action<TEventArgs>> invoke, Func<IModMetadata, bool> match = null)
         {
             // skip if no handlers
             if (this.Handlers.Count == 0)
@@ -128,7 +136,7 @@ namespace StardewModdingAPI.Framework.Events
 
                 try
                 {
-                    handler.Handler.Invoke(null, args);
+                    invoke(handler.SourceMod, args => handler.Handler.Invoke(null, args));
                 }
                 catch (Exception ex)
                 {
diff --git a/src/SMAPI/Framework/Events/ModContentEvents.cs b/src/SMAPI/Framework/Events/ModContentEvents.cs
new file mode 100644
index 00000000..b4d4279c
--- /dev/null
+++ b/src/SMAPI/Framework/Events/ModContentEvents.cs
@@ -0,0 +1,29 @@
+using System;
+using StardewModdingAPI.Events;
+
+namespace StardewModdingAPI.Framework.Events
+{
+    /// <inheritdoc cref="IContentEvents" />
+    internal class ModContentEvents : ModEventsBase, IContentEvents
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <inheritdoc />
+        public event EventHandler<AssetRequestedEventArgs> AssetRequested
+        {
+            add => this.EventManager.AssetRequested.Add(value, this.Mod);
+            remove => this.EventManager.AssetRequested.Remove(value);
+        }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="mod">The mod which uses this instance.</param>
+        /// <param name="eventManager">The underlying event manager.</param>
+        internal ModContentEvents(IModMetadata mod, EventManager eventManager)
+            : base(mod, eventManager) { }
+    }
+}
diff --git a/src/SMAPI/Framework/Events/ModEvents.cs b/src/SMAPI/Framework/Events/ModEvents.cs
index 0c365d42..1fb3482c 100644
--- a/src/SMAPI/Framework/Events/ModEvents.cs
+++ b/src/SMAPI/Framework/Events/ModEvents.cs
@@ -8,6 +8,9 @@ namespace StardewModdingAPI.Framework.Events
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public IContentEvents Content { get; }
+
         /// <inheritdoc />
         public IDisplayEvents Display { get; }
 
@@ -38,6 +41,7 @@ namespace StardewModdingAPI.Framework.Events
         /// <param name="eventManager">The underlying event manager.</param>
         public ModEvents(IModMetadata mod, EventManager eventManager)
         {
+            this.Content = new ModContentEvents(mod, eventManager);
             this.Display = new ModDisplayEvents(mod, eventManager);
             this.GameLoop = new ModGameLoopEvents(mod, eventManager);
             this.Input = new ModInputEvents(mod, eventManager);
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index 342d6415..f0340cf5 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1106,6 +1106,35 @@ namespace StardewModdingAPI.Framework
             this.EventManager.DayEnding.RaiseEmpty();
         }
 
+        /// <summary>Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</summary>
+        /// <param name="asset">The asset info being requested.</param>
+        private IList<AssetOperationGroup> RequestAssetOperations(IAssetInfo asset)
+        {
+            List<AssetOperationGroup> operations = new();
+
+            this.EventManager.AssetRequested.Raise(
+                invoke: (mod, invoke) =>
+                {
+                    AssetRequestedEventArgs args = new(mod, asset.Name);
+
+                    invoke(args);
+
+                    if (args.LoadOperations.Any() || args.EditOperations.Any())
+                    {
+                        operations.Add(
+                            new AssetOperationGroup(
+                                mod,
+                                args.LoadOperations.Select(p => new AssetLoadOperation(mod, assetInfo => p.GetData(assetInfo))).ToArray(),
+                                args.EditOperations.Select(p => new AssetEditOperation(mod, assetInfo => p.ApplyEdit(assetInfo))).ToArray()
+                            )
+                        );
+                    }
+                }
+            );
+
+            return operations;
+        }
+
         /// <summary>Raised immediately before the player returns to the title screen.</summary>
         private void OnReturningToTitle()
         {
@@ -1142,7 +1171,17 @@ namespace StardewModdingAPI.Framework
             // Game1._temporaryContent initializing from SGame constructor
             if (this.ContentCore == null)
             {
-                this.ContentCore = new ContentCoordinator(serviceProvider, rootDirectory, Thread.CurrentThread.CurrentUICulture, this.Monitor, this.Reflection, this.Toolkit.JsonHelper, this.InitializeBeforeFirstAssetLoaded, this.Settings.AggressiveMemoryOptimizations);
+                this.ContentCore = new ContentCoordinator(
+                    serviceProvider: serviceProvider,
+                    rootDirectory: rootDirectory,
+                    currentCulture: Thread.CurrentThread.CurrentUICulture,
+                    monitor: this.Monitor,
+                    reflection: this.Reflection,
+                    jsonHelper: this.Toolkit.JsonHelper,
+                    onLoadingFirstAsset: this.InitializeBeforeFirstAssetLoaded,
+                    aggressiveMemoryOptimizations: this.Settings.AggressiveMemoryOptimizations,
+                    requestAssetOperations: this.RequestAssetOperations
+                );
                 if (this.ContentCore.Language != this.Translator.LocaleEnum)
                     this.Translator.SetLocale(this.ContentCore.GetLocale(), this.ContentCore.Language);
 
diff --git a/src/SMAPI/IContentHelper.cs b/src/SMAPI/IContentHelper.cs
index 2936ecfb..207b4a33 100644
--- a/src/SMAPI/IContentHelper.cs
+++ b/src/SMAPI/IContentHelper.cs
@@ -31,7 +31,7 @@ namespace StardewModdingAPI
         ** Public methods
         *********/
         /// <summary>Load content from the game folder or mod folder (if not already cached), and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
-        /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, and dictionaries; other types may be supported by the game's content pipeline.</typeparam>
+        /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
         /// <param name="key">The asset key to fetch (if the <paramref name="source"/> is <see cref="ContentSource.GameContent"/>), or the local path to a content file relative to the mod folder.</param>
         /// <param name="source">Where to search for a matching content asset.</param>
         /// <exception cref="ArgumentException">The <paramref name="key"/> is empty or contains invalid characters.</exception>
-- 
cgit 


From 2b0ce2bb4d6690b7d00da0a243855db9bffffbf0 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 24 Mar 2022 22:55:55 -0400
Subject: add AssetInvalidated content event (#766)

---
 docs/release-notes.md                          |  2 +-
 src/SMAPI/Events/AssetsInvalidatedEventArgs.cs | 27 +++++++++++++++++++++++
 src/SMAPI/Events/IContentEvents.cs             |  3 +++
 src/SMAPI/Framework/ContentCoordinator.cs      | 30 ++++++++++++++++----------
 src/SMAPI/Framework/Events/EventManager.cs     |  4 ++++
 src/SMAPI/Framework/Events/ModContentEvents.cs |  7 ++++++
 src/SMAPI/Framework/SCore.cs                   |  9 ++++++++
 7 files changed, 70 insertions(+), 12 deletions(-)
 create mode 100644 src/SMAPI/Events/AssetsInvalidatedEventArgs.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2d1cdf44..8bf451a5 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -11,7 +11,7 @@
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
 
 * For mod authors:
-  * Added [`AssetRequested` content event](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will eventually replace `IAssetEditor` and `IAssetLoader`.
+  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
     _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Events/AssetsInvalidatedEventArgs.cs b/src/SMAPI/Events/AssetsInvalidatedEventArgs.cs
new file mode 100644
index 00000000..0127f83a
--- /dev/null
+++ b/src/SMAPI/Events/AssetsInvalidatedEventArgs.cs
@@ -0,0 +1,27 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IContentEvents.AssetsInvalidated"/> event.</summary>
+    public class AssetsInvalidatedEventArgs : EventArgs
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The asset names that were invalidated.</summary>
+        public IEnumerable<IAssetName> Names { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="names">The asset names that were invalidated.</param>
+        internal AssetsInvalidatedEventArgs(IEnumerable<IAssetName> names)
+        {
+            this.Names = names.ToArray();
+        }
+    }
+}
diff --git a/src/SMAPI/Events/IContentEvents.cs b/src/SMAPI/Events/IContentEvents.cs
index feaf9c0a..ede9ea23 100644
--- a/src/SMAPI/Events/IContentEvents.cs
+++ b/src/SMAPI/Events/IContentEvents.cs
@@ -13,5 +13,8 @@ namespace StardewModdingAPI.Events
         /// If the asset is requested multiple times in the same tick (e.g. once to check if it exists and once to load it), SMAPI might only raise the event once and reuse the cached result.
         /// </remarks>
         event EventHandler<AssetRequestedEventArgs> AssetRequested;
+
+        /// <summary>Raised after one or more assets were invalidated from the content cache by a mod, so they'll be reloaded next time they're requested. If the assets will be reloaded or propagated automatically, this event is raised before that happens.</summary>
+        event EventHandler<AssetsInvalidatedEventArgs> AssetsInvalidated;
     }
 }
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 22ae0a18..4f696928 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -49,6 +49,12 @@ namespace StardewModdingAPI.Framework
         /// <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 any asset names have been invalidated from the cache.</summary>
+        private readonly Action<IEnumerable<IAssetName>> OnAssetsInvalidated;
+
+        /// <summary>Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</summary>
+        private readonly Func<IAssetInfo, IList<AssetOperationGroup>> RequestAssetOperations;
+
         /// <summary>The loaded content managers (including the <see cref="MainContentManager"/>).</summary>
         private readonly List<IContentManager> ContentManagers = new();
 
@@ -71,9 +77,6 @@ namespace StardewModdingAPI.Framework
         /// <summary>The language enum values indexed by locale code.</summary>
         private Lazy<Dictionary<string, LocalizedContentManager.LanguageCode>> LocaleCodes;
 
-        /// <summary>Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</summary>
-        private readonly Func<IAssetInfo, IList<AssetOperationGroup>> RequestAssetOperations;
-
         /// <summary>The cached asset load/edit operations to apply, indexed by asset name.</summary>
         private readonly TickCacheDictionary<IAssetName, AssetOperationGroup[]> AssetOperationsByKey = new();
 
@@ -109,14 +112,16 @@ namespace StardewModdingAPI.Framework
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
         /// <param name="onLoadingFirstAsset">A callback to invoke the first time *any* game content manager loads an asset.</param>
         /// <param name="aggressiveMemoryOptimizations">Whether to enable more aggressive memory optimizations.</param>
+        /// <param name="onAssetsInvalidated">A callback to invoke when any asset names have been invalidated from the cache.</param>
         /// <param name="requestAssetOperations">Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</param>
-        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, bool aggressiveMemoryOptimizations, Func<IAssetInfo, IList<AssetOperationGroup>> requestAssetOperations)
+        public ContentCoordinator(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action onLoadingFirstAsset, bool aggressiveMemoryOptimizations, Action<IEnumerable<IAssetName>> onAssetsInvalidated, Func<IAssetInfo, IList<AssetOperationGroup>> requestAssetOperations)
         {
             this.AggressiveMemoryOptimizations = aggressiveMemoryOptimizations;
             this.Monitor = monitor ?? throw new ArgumentNullException(nameof(monitor));
             this.Reflection = reflection;
             this.JsonHelper = jsonHelper;
             this.OnLoadingFirstAsset = onLoadingFirstAsset;
+            this.OnAssetsInvalidated = onAssetsInvalidated;
             this.RequestAssetOperations = requestAssetOperations;
             this.FullRootDirectory = Path.Combine(Constants.GamePath, rootDirectory);
             this.ContentManagers.Add(
@@ -257,7 +262,7 @@ namespace StardewModdingAPI.Framework
             // Note that we *must* propagate changes here, otherwise when mods invalidate the cache later to reapply
             // their changes, the assets won't be found in the cache so no changes will be propagated.
             if (LocalizedContentManager.CurrentLanguageCode != LocalizedContentManager.LanguageCode.en)
-                this.InvalidateCache((contentManager, key, type) => contentManager is GameContentManager);
+                this.InvalidateCache((contentManager, _, _) => contentManager is GameContentManager);
         }
 
         /// <summary>Parse a raw asset name.</summary>
@@ -347,7 +352,7 @@ namespace StardewModdingAPI.Framework
         public IEnumerable<IAssetName> InvalidateCache(Func<IAssetInfo, bool> predicate, bool dispose = false)
         {
             string locale = this.GetLocale();
-            return this.InvalidateCache((contentManager, rawName, type) =>
+            return this.InvalidateCache((_, rawName, type) =>
             {
                 IAssetName assetName = this.ParseAssetName(rawName);
                 IAssetInfo info = new AssetInfo(locale, assetName, type, this.MainContentManager.AssertAndNormalizeAssetName);
@@ -393,13 +398,16 @@ namespace StardewModdingAPI.Framework
                 }
             });
 
-            // clear cached editor checks
-            foreach (IAssetName name in invalidatedAssets.Keys)
-                this.AssetOperationsByKey.Remove(name);
-
-            // reload core game assets
+            // handle invalidation
             if (invalidatedAssets.Any())
             {
+                // clear cached editor checks
+                foreach (IAssetName name in invalidatedAssets.Keys)
+                    this.AssetOperationsByKey.Remove(name);
+
+                // raise event
+                this.OnAssetsInvalidated(invalidatedAssets.Keys);
+
                 // propagate changes to the game
                 this.CoreAssets.Propagate(
                     assets: invalidatedAssets.ToDictionary(p => p.Key, p => p.Value),
diff --git a/src/SMAPI/Framework/Events/EventManager.cs b/src/SMAPI/Framework/Events/EventManager.cs
index 8142f00e..96582380 100644
--- a/src/SMAPI/Framework/Events/EventManager.cs
+++ b/src/SMAPI/Framework/Events/EventManager.cs
@@ -16,6 +16,9 @@ namespace StardewModdingAPI.Framework.Events
         /// <inheritdoc cref="IContentEvents.AssetRequested" />
         public readonly ManagedEvent<AssetRequestedEventArgs> AssetRequested;
 
+        /// <inheritdoc cref="IContentEvents.AssetsInvalidated" />
+        public readonly ManagedEvent<AssetsInvalidatedEventArgs> AssetsInvalidated;
+
 
         /****
         ** Display
@@ -198,6 +201,7 @@ namespace StardewModdingAPI.Framework.Events
 
             // init events
             this.AssetRequested = ManageEventOf<AssetRequestedEventArgs>(nameof(IModEvents.Content), nameof(IContentEvents.AssetRequested));
+            this.AssetsInvalidated = ManageEventOf<AssetsInvalidatedEventArgs>(nameof(IModEvents.Content), nameof(IContentEvents.AssetsInvalidated));
 
             this.MenuChanged = ManageEventOf<MenuChangedEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.MenuChanged));
             this.Rendering = ManageEventOf<RenderingEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.Rendering), isPerformanceCritical: true);
diff --git a/src/SMAPI/Framework/Events/ModContentEvents.cs b/src/SMAPI/Framework/Events/ModContentEvents.cs
index b4d4279c..4d0cfb97 100644
--- a/src/SMAPI/Framework/Events/ModContentEvents.cs
+++ b/src/SMAPI/Framework/Events/ModContentEvents.cs
@@ -16,6 +16,13 @@ namespace StardewModdingAPI.Framework.Events
             remove => this.EventManager.AssetRequested.Remove(value);
         }
 
+        /// <inheritdoc />
+        public event EventHandler<AssetsInvalidatedEventArgs> AssetsInvalidated
+        {
+            add => this.EventManager.AssetsInvalidated.Add(value, this.Mod);
+            remove => this.EventManager.AssetsInvalidated.Remove(value);
+        }
+
 
         /*********
         ** Public methods
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index f9f84206..e9bc9a2b 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1106,6 +1106,14 @@ namespace StardewModdingAPI.Framework
             this.EventManager.DayEnding.RaiseEmpty();
         }
 
+        /// <summary>A callback invoked after assets have been invalidated from the content cache.</summary>
+        /// <param name="assetNames">The invalidated asset names.</param>
+        private void OnAssetsInvalidated(IEnumerable<IAssetName> assetNames)
+        {
+            if (this.EventManager.AssetsInvalidated.HasListeners())
+                this.EventManager.AssetsInvalidated.Raise(new AssetsInvalidatedEventArgs(assetNames));
+        }
+
         /// <summary>Get the load/edit operations to apply to an asset by querying registered <see cref="IContentEvents.AssetRequested"/> event handlers.</summary>
         /// <param name="asset">The asset info being requested.</param>
         private IList<AssetOperationGroup> RequestAssetOperations(IAssetInfo asset)
@@ -1175,6 +1183,7 @@ namespace StardewModdingAPI.Framework
                     reflection: this.Reflection,
                     jsonHelper: this.Toolkit.JsonHelper,
                     onLoadingFirstAsset: this.InitializeBeforeFirstAssetLoaded,
+                    onAssetsInvalidated: this.OnAssetsInvalidated,
                     aggressiveMemoryOptimizations: this.Settings.AggressiveMemoryOptimizations,
                     requestAssetOperations: this.RequestAssetOperations
                 );
-- 
cgit 


From e1fc566e0afeb6eb92418bb039365611abd33829 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 25 Mar 2022 21:46:37 -0400
Subject: add content pack labels (#766)

---
 docs/release-notes.md                              |  2 +-
 src/SMAPI/Events/AssetRequestedEventArgs.cs        | 30 ++++++++++++++++----
 src/SMAPI/Framework/Content/AssetEditOperation.cs  |  7 ++++-
 src/SMAPI/Framework/Content/AssetLoadOperation.cs  |  9 ++++--
 src/SMAPI/Framework/ContentCoordinator.cs          | 12 ++++++--
 .../ContentManagers/GameContentManager.cs          | 26 ++++++++++++------
 src/SMAPI/Framework/InternalExtensions.cs          |  9 ++++++
 src/SMAPI/Framework/SCore.cs                       | 32 +++++++++++++++++++++-
 8 files changed, 106 insertions(+), 21 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 8bf451a5..2a8d142f 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -11,7 +11,7 @@
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
 
 * For mod authors:
-  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.
+  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0. These include new features not supported by the old API like content pack labels.
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
     _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Events/AssetRequestedEventArgs.cs b/src/SMAPI/Events/AssetRequestedEventArgs.cs
index b17250b0..774ab808 100644
--- a/src/SMAPI/Events/AssetRequestedEventArgs.cs
+++ b/src/SMAPI/Events/AssetRequestedEventArgs.cs
@@ -16,6 +16,9 @@ namespace StardewModdingAPI.Events
         /// <summary>The mod handling the event.</summary>
         private readonly IModMetadata Mod;
 
+        /// <summary>Get the mod metadata for a content pack, if it's a valid content pack for the mod.</summary>
+        private readonly Func<IModMetadata, string, string, IModMetadata> GetOnBehalfOf;
+
 
         /*********
         ** Accessors
@@ -36,14 +39,17 @@ namespace StardewModdingAPI.Events
         /// <summary>Construct an instance.</summary>
         /// <param name="mod">The mod handling the event.</param>
         /// <param name="name">The name of the asset being requested.</param>
-        internal AssetRequestedEventArgs(IModMetadata mod, IAssetName name)
+        /// <param name="getOnBehalfOf">Get the mod metadata for a content pack, if it's a valid content pack for the mod.</param>
+        internal AssetRequestedEventArgs(IModMetadata mod, IAssetName name, Func<IModMetadata, string, string, IModMetadata> getOnBehalfOf)
         {
             this.Mod = mod;
             this.Name = name;
+            this.GetOnBehalfOf = getOnBehalfOf;
         }
 
         /// <summary>Provide the initial instance for the asset, instead of trying to load it from the game's <c>Content</c> folder.</summary>
         /// <param name="load">Get the initial instance of an asset.</param>
+        /// <param name="onBehalfOf">The content pack ID on whose behalf you're applying the change. This is only valid for content packs for your mod.</param>
         /// <remarks>
         /// Usage notes:
         /// <list type="bullet">
@@ -51,10 +57,14 @@ namespace StardewModdingAPI.Events
         ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will raise an error and ignore all of them. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
         /// </list>
         /// </remarks>
-        public void LoadFrom(Func<object> load)
+        public void LoadFrom(Func<object> load, string onBehalfOf = null)
         {
             this.LoadOperations.Add(
-                new AssetLoadOperation(this.Mod, _ => load())
+                new AssetLoadOperation(
+                    mod: this.Mod,
+                    onBehalfOf: this.GetOnBehalfOf(this.Mod, onBehalfOf, "load assets"),
+                    getData: _ => load()
+                )
             );
         }
 
@@ -71,12 +81,16 @@ namespace StardewModdingAPI.Events
         public void LoadFromModFile<TAsset>(string relativePath)
         {
             this.LoadOperations.Add(
-                new AssetLoadOperation(this.Mod, _ => this.Mod.Mod.Helper.Content.Load<TAsset>(relativePath))
+                new AssetLoadOperation(
+                    mod: this.Mod,
+                    onBehalfOf: null,
+                    _ => this.Mod.Mod.Helper.Content.Load<TAsset>(relativePath))
             );
         }
 
         /// <summary>Edit the asset after it's loaded.</summary>
         /// <param name="apply">Apply changes to the asset.</param>
+        /// <param name="onBehalfOf">The content pack ID on whose behalf you're applying the change. This is only valid for content packs for your mod.</param>
         /// <remarks>
         /// Usage notes:
         /// <list type="bullet">
@@ -84,10 +98,14 @@ namespace StardewModdingAPI.Events
         ///   <item>You can apply any number of edits to the asset. Each edit will be applied on top of the previous one (i.e. it'll see the merged asset from all previous edits as its input).</item>
         /// </list>
         /// </remarks>
-        public void Edit(Action<IAssetData> apply)
+        public void Edit(Action<IAssetData> apply, string onBehalfOf = null)
         {
             this.EditOperations.Add(
-                new AssetEditOperation(this.Mod, apply)
+                new AssetEditOperation(
+                    mod: this.Mod,
+                    onBehalfOf: this.GetOnBehalfOf(this.Mod, onBehalfOf, "edit assets"),
+                    apply
+                )
             );
         }
     }
diff --git a/src/SMAPI/Framework/Content/AssetEditOperation.cs b/src/SMAPI/Framework/Content/AssetEditOperation.cs
index fa189d44..14db231c 100644
--- a/src/SMAPI/Framework/Content/AssetEditOperation.cs
+++ b/src/SMAPI/Framework/Content/AssetEditOperation.cs
@@ -11,6 +11,9 @@ namespace StardewModdingAPI.Framework.Content
         /// <summary>The mod applying the edit.</summary>
         public IModMetadata Mod { get; }
 
+        /// <summary>The content pack on whose behalf the edit is being applied, if any.</summary>
+        public IModMetadata OnBehalfOf { get; }
+
         /// <summary>Apply the edit to an asset.</summary>
         public Action<IAssetData> ApplyEdit { get; }
 
@@ -20,10 +23,12 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="mod">The mod applying the edit.</param>
+        /// <param name="onBehalfOf">The content pack on whose behalf the edit is being applied, if any.</param>
         /// <param name="applyEdit">Apply the edit to an asset.</param>
-        public AssetEditOperation(IModMetadata mod, Action<IAssetData> applyEdit)
+        public AssetEditOperation(IModMetadata mod, IModMetadata onBehalfOf, Action<IAssetData> applyEdit)
         {
             this.Mod = mod;
+            this.OnBehalfOf = onBehalfOf;
             this.ApplyEdit = applyEdit;
         }
     }
diff --git a/src/SMAPI/Framework/Content/AssetLoadOperation.cs b/src/SMAPI/Framework/Content/AssetLoadOperation.cs
index d773cadd..29bf1518 100644
--- a/src/SMAPI/Framework/Content/AssetLoadOperation.cs
+++ b/src/SMAPI/Framework/Content/AssetLoadOperation.cs
@@ -8,9 +8,12 @@ namespace StardewModdingAPI.Framework.Content
         /*********
         ** Accessors
         *********/
-        /// <summary>The mod applying the edit.</summary>
+        /// <summary>The mod loading the asset.</summary>
         public IModMetadata Mod { get; }
 
+        /// <summary>The content pack on whose behalf the asset is being loaded, if any.</summary>
+        public IModMetadata OnBehalfOf { get; }
+
         /// <summary>Load the initial value for an asset.</summary>
         public Func<IAssetInfo, object> GetData { get; }
 
@@ -20,10 +23,12 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="mod">The mod applying the edit.</param>
+        /// <param name="onBehalfOf">The content pack on whose behalf the asset is being loaded, if any.</param>
         /// <param name="getData">Load the initial value for an asset.</param>
-        public AssetLoadOperation(IModMetadata mod, Func<IAssetInfo, object> getData)
+        public AssetLoadOperation(IModMetadata mod, IModMetadata onBehalfOf, Func<IAssetInfo, object> getData)
         {
             this.Mod = mod;
+            this.OnBehalfOf = onBehalfOf;
             this.GetData = getData;
         }
     }
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 4dbbae15..3b304f0d 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -606,7 +606,11 @@ namespace StardewModdingAPI.Framework
                     mod: loader.Mod,
                     loadOperations: new[]
                     {
-                        new AssetLoadOperation(loader.Mod, assetInfo => loader.Data.Load<T>(assetInfo))
+                        new AssetLoadOperation(
+                            mod: loader.Mod,
+                            onBehalfOf: null,
+                            getData: assetInfo => loader.Data.Load<T>(assetInfo)
+                        )
                     },
                     editOperations: Array.Empty<AssetEditOperation>()
                 );
@@ -633,7 +637,11 @@ namespace StardewModdingAPI.Framework
                     loadOperations: Array.Empty<AssetLoadOperation>(),
                     editOperations: new[]
                     {
-                        new AssetEditOperation(editor.Mod, assetData => editor.Data.Edit<T>(assetData))
+                        new AssetEditOperation(
+                            mod: editor.Mod,
+                            onBehalfOf: null,
+                            applyEdit: assetData => editor.Data.Edit<T>(assetData)
+                        )
                     }
                 );
             }
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 12ed5506..58e36128 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -267,7 +267,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
         }
 
-        /// <summary>Load the initial asset from the registered <see cref="Loaders"/>.</summary>
+        /// <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)
@@ -296,11 +296,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
             try
             {
                 data = (T)loader.GetData(info);
-                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.Name}'.");
+                this.Monitor.Log($"{mod.DisplayName} loaded asset '{info.Name}'{this.GetOnBehalfOfLabel(loader.OnBehalfOf)}.");
             }
             catch (Exception ex)
             {
-                mod.LogAsMod($"Mod crashed when loading asset '{info.Name}'. 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;
             }
 
@@ -310,7 +310,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 : 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>
@@ -343,22 +343,22 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 try
                 {
                     editor.ApplyEdit(asset);
-                    this.Monitor.Log($"{mod.DisplayName} edited {info.Name}.");
+                    this.Monitor.Log($"{mod.DisplayName} edited {info.Name}{this.GetOnBehalfOfLabel(editor.OnBehalfOf)}.");
                 }
                 catch (Exception ex)
                 {
-                    mod.LogAsMod($"Mod crashed when editing asset '{info.Name}', which may cause errors in-game. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    mod.LogAsMod($"Mod crashed when editing asset '{info.Name}'{this.GetOnBehalfOfLabel(editor.OnBehalfOf)}, which may cause errors in-game. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                 }
 
                 // validate edit
                 if (asset.Data == null)
                 {
-                    mod.LogAsMod($"Mod incorrectly set asset '{info.Name}' to a null value; ignoring override.", LogLevel.Warn);
+                    mod.LogAsMod($"Mod incorrectly set asset '{info.Name}'{this.GetOnBehalfOfLabel(editor.OnBehalfOf)} to a null value; ignoring override.", LogLevel.Warn);
                     asset = GetNewData(prevAsset);
                 }
                 else if (!(asset.Data is T))
                 {
-                    mod.LogAsMod($"Mod incorrectly set asset '{asset.Name}' to incompatible type '{asset.Data.GetType()}', expected '{typeof(T)}'; ignoring override.", LogLevel.Warn);
+                    mod.LogAsMod($"Mod incorrectly set asset '{asset.Name}'{this.GetOnBehalfOfLabel(editor.OnBehalfOf)} to incompatible type '{asset.Data.GetType()}', expected '{typeof(T)}'; ignoring override.", LogLevel.Warn);
                     asset = GetNewData(prevAsset);
                 }
             }
@@ -409,6 +409,16 @@ namespace StardewModdingAPI.Framework.ContentManagers
             return false;
         }
 
+        /// <summary>Get a parenthetical label for log messages for the content pack on whose behalf the action is being performed, if any.</summary>
+        /// <param name="onBehalfOf">The content pack on whose behalf the action is being performed.</param>
+        private string GetOnBehalfOfLabel(IModMetadata onBehalfOf)
+        {
+            if (onBehalfOf == null)
+                return string.Empty;
+
+            return $" (for the '{onBehalfOf.Manifest.Name}' content pack)";
+        }
+
         /// <summary>Validate that an asset loaded by a mod is valid and won't cause issues, and fix issues if possible.</summary>
         /// <typeparam name="T">The asset type.</typeparam>
         /// <param name="info">The basic asset metadata.</param>
diff --git a/src/SMAPI/Framework/InternalExtensions.cs b/src/SMAPI/Framework/InternalExtensions.cs
index 4cb77a45..fe10b045 100644
--- a/src/SMAPI/Framework/InternalExtensions.cs
+++ b/src/SMAPI/Framework/InternalExtensions.cs
@@ -45,6 +45,15 @@ namespace StardewModdingAPI.Framework
             metadata.Monitor.Log(message, level);
         }
 
+        /// <summary>Log a message using the mod's monitor, but only if it hasn't already been logged since the last game launch.</summary>
+        /// <param name="metadata">The mod whose monitor to use.</param>
+        /// <param name="message">The message to log.</param>
+        /// <param name="level">The log severity level.</param>
+        public static void LogAsModOnce(this IModMetadata metadata, string message, LogLevel level = LogLevel.Trace)
+        {
+            metadata.Monitor.LogOnce(message, level);
+        }
+
         /****
         ** ManagedEvent
         ****/
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index 9d97ec7d..dd682e40 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1133,7 +1133,7 @@ namespace StardewModdingAPI.Framework
             this.EventManager.AssetRequested.Raise(
                 invoke: (mod, invoke) =>
                 {
-                    AssetRequestedEventArgs args = new(mod, asset.Name);
+                    AssetRequestedEventArgs args = new(mod, asset.Name, this.GetOnBehalfOfContentPack);
 
                     invoke(args);
 
@@ -1149,6 +1149,36 @@ namespace StardewModdingAPI.Framework
             return operations;
         }
 
+        /// <summary>Get the mod metadata for a content pack whose ID matches <paramref name="id"/>, if it's a valid content pack for the given <paramref name="mod"/>.</summary>
+        /// <param name="mod">The mod requesting to act on the content pack's behalf.</param>
+        /// <param name="id">The content pack ID.</param>
+        /// <param name="verb">The verb phrase indicating what action will be performed, like 'load assets' or 'edit assets'.</param>
+        /// <returns>Returns the content pack metadata if valid, else <c>null</c>.</returns>
+        private IModMetadata GetOnBehalfOfContentPack(IModMetadata mod, string id, string verb)
+        {
+            if (id == null)
+                return null;
+
+            string errorPrefix = $"Can't {verb} on behalf of content pack ID '{id}'";
+
+            // get target mod
+            IModMetadata onBehalfOf = this.ModRegistry.Get(id);
+            if (onBehalfOf == null)
+            {
+                mod.LogAsModOnce($"{errorPrefix}: there's no content pack installed with that ID.", LogLevel.Warn);
+                return null;
+            }
+
+            // make sure it's a content pack for the requesting mod
+            if (!onBehalfOf.IsContentPack || !string.Equals(onBehalfOf.Manifest?.ContentPackFor?.UniqueID, mod.Manifest.UniqueID))
+            {
+                mod.LogAsModOnce($"{errorPrefix}: that isn't a content pack for this mod.", LogLevel.Warn);
+                return null;
+            }
+
+            return onBehalfOf;
+        }
+
         /// <summary>Raised immediately before the player returns to the title screen.</summary>
         private void OnReturningToTitle()
         {
-- 
cgit 


From 9025b0dcc5c537cbde37aef2482ccd942eb9769f Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 25 Mar 2022 22:16:49 -0400
Subject: fix asset load conflict always showing multiple-mod form

---
 docs/release-notes.md                                     | 1 +
 src/SMAPI/Framework/ContentManagers/GameContentManager.cs | 5 ++++-
 2 files changed, 5 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2a8d142f..7cdd093a 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -9,6 +9,7 @@
   * Improved [command-line arguments](technical/smapi.md#command-line-arguments) on Linux/macOS:
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
+  * Fixed warning text when a mod causes an asset load conflict with itself.
 
 * For mod authors:
   * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0. These include new features not supported by the old API like content pack labels.
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 58e36128..8bdb39d0 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -400,7 +400,10 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 return true;
             }
 
-            string[] loaderNames = loaders.Select(p => p.Mod.DisplayName).ToArray();
+            string[] loaderNames = loaders
+                .Select(p => p.Mod.DisplayName)
+                .Distinct()
+                .ToArray();
             string errorPhrase = loaderNames.Length > 1
                 ? $"Multiple mods want to provide '{info.Name}' asset ({string.Join(", ", loaderNames)})"
                 : $"The '{loaderNames[0]}' mod wants to provide the '{info.Name}' asset multiple times";
-- 
cgit 


From 021891ff0ceb6b327bc196c336aa56ddfaf99b0e Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 25 Mar 2022 22:49:14 -0400
Subject: add load conflict resolution option (#766)

---
 docs/release-notes.md                                   |  3 ++-
 src/SMAPI/Events/AssetRequestedEventArgs.cs             | 10 +++++++---
 src/SMAPI/Framework/Content/AssetLoadOperation.cs       |  7 ++++++-
 src/SMAPI/Framework/ContentCoordinator.cs               |  1 +
 .../Framework/ContentManagers/GameContentManager.cs     | 17 ++++++++++-------
 5 files changed, 26 insertions(+), 12 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 7cdd093a..c8c87db3 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -12,7 +12,8 @@
   * Fixed warning text when a mod causes an asset load conflict with itself.
 
 * For mod authors:
-  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0. These include new features not supported by the old API like content pack labels.
+  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
+    _These include new features not supported by the old API, like load conflict resolution and content pack labels. They also support new cases like easily detecting when an asset has been changed._
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
     _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Events/AssetRequestedEventArgs.cs b/src/SMAPI/Events/AssetRequestedEventArgs.cs
index 774ab808..9942079b 100644
--- a/src/SMAPI/Events/AssetRequestedEventArgs.cs
+++ b/src/SMAPI/Events/AssetRequestedEventArgs.cs
@@ -50,18 +50,20 @@ namespace StardewModdingAPI.Events
         /// <summary>Provide the initial instance for the asset, instead of trying to load it from the game's <c>Content</c> folder.</summary>
         /// <param name="load">Get the initial instance of an asset.</param>
         /// <param name="onBehalfOf">The content pack ID on whose behalf you're applying the change. This is only valid for content packs for your mod.</param>
+        /// <param name="allowSkipOnConflict">When there are multiple loads that apply to the same asset, this indicates whether this one can be skipped to resolve the conflict. If all loads allow skipping, the first one that was registered will be applied. If this is false, SMAPI will raise an error and apply none of them.</param>
         /// <remarks>
         /// Usage notes:
         /// <list type="bullet">
         ///   <item>The asset doesn't need to exist in the game's <c>Content</c> folder. If any mod loads the asset, the game will see it as an existing asset as if it was in that folder.</item>
-        ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will raise an error and ignore all of them. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
+        ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will use the <paramref name="allowSkipOnConflict"/> parameter to decide what happens. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
         /// </list>
         /// </remarks>
-        public void LoadFrom(Func<object> load, string onBehalfOf = null)
+        public void LoadFrom(Func<object> load, string onBehalfOf = null, bool allowSkipOnConflict = false)
         {
             this.LoadOperations.Add(
                 new AssetLoadOperation(
                     mod: this.Mod,
+                    allowSkipOnConflict: allowSkipOnConflict,
                     onBehalfOf: this.GetOnBehalfOf(this.Mod, onBehalfOf, "load assets"),
                     getData: _ => load()
                 )
@@ -71,6 +73,7 @@ namespace StardewModdingAPI.Events
         /// <summary>Provide the initial instance for the asset from a file in your mod folder, instead of trying to load it from the game's <c>Content</c> folder.</summary>
         /// <typeparam name="TAsset">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
         /// <param name="relativePath">The relative path to the file in your mod folder.</param>
+        /// <param name="allowSkipOnConflict">When there are multiple loads that apply to the same asset, this indicates whether this one can be skipped to resolve the conflict. If all loads allow skipping, the first one that was registered will be applied. If this is false, SMAPI will raise an error and apply none of them.</param>
         /// <remarks>
         /// Usage notes:
         /// <list type="bullet">
@@ -78,11 +81,12 @@ namespace StardewModdingAPI.Events
         ///   <item>Each asset can logically only have one initial instance. If multiple loads apply at the same time, SMAPI will raise an error and ignore all of them. If you're making changes to the existing asset instead of replacing it, you should use <see cref="Edit"/> instead to avoid those limitations and improve mod compatibility.</item>
         /// </list>
         /// </remarks>
-        public void LoadFromModFile<TAsset>(string relativePath)
+        public void LoadFromModFile<TAsset>(string relativePath, bool allowSkipOnConflict = false)
         {
             this.LoadOperations.Add(
                 new AssetLoadOperation(
                     mod: this.Mod,
+                    allowSkipOnConflict: allowSkipOnConflict,
                     onBehalfOf: null,
                     _ => this.Mod.Mod.Helper.Content.Load<TAsset>(relativePath))
             );
diff --git a/src/SMAPI/Framework/Content/AssetLoadOperation.cs b/src/SMAPI/Framework/Content/AssetLoadOperation.cs
index 29bf1518..36baf1aa 100644
--- a/src/SMAPI/Framework/Content/AssetLoadOperation.cs
+++ b/src/SMAPI/Framework/Content/AssetLoadOperation.cs
@@ -14,6 +14,9 @@ namespace StardewModdingAPI.Framework.Content
         /// <summary>The content pack on whose behalf the asset is being loaded, if any.</summary>
         public IModMetadata OnBehalfOf { get; }
 
+        /// <summary>Whether to allow skipping this operation to resolve a load conflict.</summary>
+        public bool AllowSkipOnConflict { get; }
+
         /// <summary>Load the initial value for an asset.</summary>
         public Func<IAssetInfo, object> GetData { get; }
 
@@ -23,11 +26,13 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="mod">The mod applying the edit.</param>
+        /// <param name="allowSkipOnConflict">Whether to allow skipping this operation to resolve a load conflict.</param>
         /// <param name="onBehalfOf">The content pack on whose behalf the asset is being loaded, if any.</param>
         /// <param name="getData">Load the initial value for an asset.</param>
-        public AssetLoadOperation(IModMetadata mod, IModMetadata onBehalfOf, Func<IAssetInfo, object> getData)
+        public AssetLoadOperation(IModMetadata mod, bool allowSkipOnConflict, IModMetadata onBehalfOf, Func<IAssetInfo, object> getData)
         {
             this.Mod = mod;
+            this.AllowSkipOnConflict = allowSkipOnConflict;
             this.OnBehalfOf = onBehalfOf;
             this.GetData = getData;
         }
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 3b304f0d..43cebcbe 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -608,6 +608,7 @@ namespace StardewModdingAPI.Framework
                     {
                         new AssetLoadOperation(
                             mod: loader.Mod,
+                            allowSkipOnConflict: false,
                             onBehalfOf: null,
                             getData: assetInfo => loader.Data.Load<T>(assetInfo)
                         )
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 1d9c8b4c..b3e98648 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -80,7 +80,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             IAssetInfo info = new AssetInfo(locale, assetName, typeof(object), this.AssertAndNormalizeAssetName);
             AssetLoadOperation[] loaders = this.GetLoaders<object>(info).ToArray();
 
-            if (!this.AssertMaxOneLoader(info, loaders, out string error))
+            if (!this.AssertMaxOneRequiredLoader(info, loaders, out string error))
                 this.Monitor.Log(error, LogLevel.Warn);
 
             return loaders.Length == 1;
@@ -277,13 +277,15 @@ namespace StardewModdingAPI.Framework.ContentManagers
             {
                 AssetLoadOperation[] loaders = this.GetLoaders<T>(info).ToArray();
 
-                if (!this.AssertMaxOneLoader(info, loaders, out string error))
+                if (!this.AssertMaxOneRequiredLoader(info, loaders, out string error))
                 {
                     this.Monitor.Log(error, LogLevel.Warn);
                     return null;
                 }
 
-                loader = loaders.FirstOrDefault();
+                loader =
+                    loaders.FirstOrDefault(p => !p.AllowSkipOnConflict)
+                    ?? loaders.FirstOrDefault();
             }
 
             // no loader found
@@ -392,20 +394,21 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="loaders">The asset loaders to apply.</param>
         /// <param name="error">The error message to show to the user, if the method returns false.</param>
         /// <returns>Returns true if only one loader will apply, else false.</returns>
-        private bool AssertMaxOneLoader(IAssetInfo info, AssetLoadOperation[] loaders, out string error)
+        private bool AssertMaxOneRequiredLoader(IAssetInfo info, AssetLoadOperation[] loaders, out string error)
         {
-            if (loaders.Length <= 1)
+            AssetLoadOperation[] required = loaders.Where(p => !p.AllowSkipOnConflict).ToArray();
+            if (required.Length <= 1)
             {
                 error = null;
                 return true;
             }
 
-            string[] loaderNames = loaders
+            string[] loaderNames = required
                 .Select(p => p.Mod.DisplayName + this.GetOnBehalfOfLabel(p.OnBehalfOf))
                 .Distinct()
                 .ToArray();
             string errorPhrase = loaderNames.Length > 1
-                ? $"Multiple mods want to provide '{info.Name}' asset: {string.Join(", ", loaderNames)}"
+                ? $"Multiple mods want to provide the '{info.Name}' asset: {string.Join(", ", loaderNames)}"
                 : $"The '{loaderNames[0]}' mod wants to provide the '{info.Name}' asset multiple times";
 
             error = $"{errorPhrase}. An asset can't be loaded multiple times, so 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.)";
-- 
cgit 


From ad8912047beaf84ce34f4918703d55841be13ff0 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 26 Mar 2022 01:43:40 -0400
Subject: add asset edit priority (#766)

---
 docs/release-notes.md                                    |  2 +-
 src/SMAPI/Events/AssetEditPriority.cs                    | 16 ++++++++++++++++
 src/SMAPI/Events/AssetRequestedEventArgs.cs              |  4 +++-
 src/SMAPI/Framework/Content/AssetEditOperation.cs        |  8 +++++++-
 src/SMAPI/Framework/ContentCoordinator.cs                |  1 +
 .../Framework/ContentManagers/GameContentManager.cs      |  7 +++++--
 6 files changed, 33 insertions(+), 5 deletions(-)
 create mode 100644 src/SMAPI/Events/AssetEditPriority.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index c8c87db3..a8f8ccfd 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -13,7 +13,7 @@
 
 * For mod authors:
   * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
-    _These include new features not supported by the old API, like load conflict resolution and content pack labels. They also support new cases like easily detecting when an asset has been changed._
+    _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has been changed._
   * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
     _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Events/AssetEditPriority.cs b/src/SMAPI/Events/AssetEditPriority.cs
new file mode 100644
index 00000000..d41dfd7d
--- /dev/null
+++ b/src/SMAPI/Events/AssetEditPriority.cs
@@ -0,0 +1,16 @@
+namespace StardewModdingAPI.Events
+{
+    /// <summary>The priority for an asset edit when multiple apply for the same asset.</summary>
+    /// <remarks>You can also specify arbitrary intermediate values, like <c>AssetLoadPriority.Low + 5</c>.</remarks>
+    public enum AssetEditPriority
+    {
+        /// <summary>This edit should be applied before (i.e. 'under') <see cref="Default"/> edits.</summary>
+        Early = -1000,
+
+        /// <summary>The default priority.</summary>
+        Default = 0,
+
+        /// <summary>This edit should be applied after (i.e. 'on top of') <see cref="Default"/> edits.</summary>
+        Late = 1000
+    }
+}
diff --git a/src/SMAPI/Events/AssetRequestedEventArgs.cs b/src/SMAPI/Events/AssetRequestedEventArgs.cs
index 9e2cde7f..4d9ee236 100644
--- a/src/SMAPI/Events/AssetRequestedEventArgs.cs
+++ b/src/SMAPI/Events/AssetRequestedEventArgs.cs
@@ -100,6 +100,7 @@ namespace StardewModdingAPI.Events
 
         /// <summary>Edit the asset after it's loaded.</summary>
         /// <param name="apply">Apply changes to the asset.</param>
+        /// <param name="priority">If there are multiple edits that apply to the same asset, the priority with which this one should be applied.</param>
         /// <param name="onBehalfOf">The content pack ID on whose behalf you're applying the change. This is only valid for content packs for your mod.</param>
         /// <remarks>
         /// Usage notes:
@@ -108,11 +109,12 @@ namespace StardewModdingAPI.Events
         ///   <item>You can apply any number of edits to the asset. Each edit will be applied on top of the previous one (i.e. it'll see the merged asset from all previous edits as its input).</item>
         /// </list>
         /// </remarks>
-        public void Edit(Action<IAssetData> apply, string onBehalfOf = null)
+        public void Edit(Action<IAssetData> apply, AssetEditPriority priority = AssetEditPriority.Default, string onBehalfOf = null)
         {
             this.EditOperations.Add(
                 new AssetEditOperation(
                     mod: this.Mod,
+                    priority: priority,
                     onBehalfOf: this.GetOnBehalfOf(this.Mod, onBehalfOf, "edit assets"),
                     apply
                 )
diff --git a/src/SMAPI/Framework/Content/AssetEditOperation.cs b/src/SMAPI/Framework/Content/AssetEditOperation.cs
index 14db231c..818209fa 100644
--- a/src/SMAPI/Framework/Content/AssetEditOperation.cs
+++ b/src/SMAPI/Framework/Content/AssetEditOperation.cs
@@ -1,4 +1,5 @@
 using System;
+using StardewModdingAPI.Events;
 
 namespace StardewModdingAPI.Framework.Content
 {
@@ -11,6 +12,9 @@ namespace StardewModdingAPI.Framework.Content
         /// <summary>The mod applying the edit.</summary>
         public IModMetadata Mod { get; }
 
+        /// <summary>If there are multiple edits that apply to the same asset, the priority with which this one should be applied.</summary>
+        public AssetEditPriority Priority { get; }
+
         /// <summary>The content pack on whose behalf the edit is being applied, if any.</summary>
         public IModMetadata OnBehalfOf { get; }
 
@@ -23,11 +27,13 @@ namespace StardewModdingAPI.Framework.Content
         *********/
         /// <summary>Construct an instance.</summary>
         /// <param name="mod">The mod applying the edit.</param>
+        /// <param name="priority">If there are multiple edits that apply to the same asset, the priority with which this one should be applied.</param>
         /// <param name="onBehalfOf">The content pack on whose behalf the edit is being applied, if any.</param>
         /// <param name="applyEdit">Apply the edit to an asset.</param>
-        public AssetEditOperation(IModMetadata mod, IModMetadata onBehalfOf, Action<IAssetData> applyEdit)
+        public AssetEditOperation(IModMetadata mod, AssetEditPriority priority, IModMetadata onBehalfOf, Action<IAssetData> applyEdit)
         {
             this.Mod = mod;
+            this.Priority = priority;
             this.OnBehalfOf = onBehalfOf;
             this.ApplyEdit = applyEdit;
         }
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index fc137e50..8e7465de 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -640,6 +640,7 @@ namespace StardewModdingAPI.Framework
                     {
                         new AssetEditOperation(
                             mod: editor.Mod,
+                            priority: AssetEditPriority.Default,
                             onBehalfOf: null,
                             applyEdit: assetData => editor.Data.Edit<T>(assetData)
                         )
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index 16eddb00..a121f4c0 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -82,9 +82,12 @@ namespace StardewModdingAPI.Framework.ContentManagers
             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.Length == 1;
+            return loaders.Any();
         }
 
         /// <inheritdoc />
@@ -334,7 +337,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
 
             // edit asset
-            AssetEditOperation[] editors = this.GetEditors<T>(info).ToArray();
+            AssetEditOperation[] editors = this.GetEditors<T>(info).OrderBy(p => p.Priority).ToArray();
             foreach (AssetEditOperation editor in editors)
             {
                 IModMetadata mod = editor.Mod;
-- 
cgit 


From 4c64f9f644c2349d2ca2407ce3aff736ba3fc354 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 26 Mar 2022 14:07:16 -0400
Subject: rewrite content loading to allow handling locale variants (#766,
 #786, #812)

The game's content pipeline automatically loads localized variants if present. For example, it will try to load "Maps/cave.fr-FR", then "Maps/cave_international", then "Maps/cave". The old content API obfuscates this logic and treats them as interchangeable, which causes edge cases like bundle corruption (#812). This commit rewrites the loading logic to match the game logic when using the new content events, while maintaining the legacy behavior for the old IAssetLoader/IAssetEditor interfaces that'll be removed in SMAPI 4.0.0.
---
 docs/release-notes.md                              |   1 +
 src/SMAPI/Framework/ContentCoordinator.cs          |  89 +++++++++++++---
 .../ContentManagers/BaseContentManager.cs          |  71 +++++++++++--
 .../ContentManagers/GameContentManager.cs          | 114 ++-------------------
 .../GameContentManagerForAssetPropagation.cs       |   4 +-
 .../Framework/ContentManagers/IContentManager.cs   |  14 ++-
 .../Framework/ContentManagers/ModContentManager.cs |  32 ++----
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs    |   4 +-
 8 files changed, 169 insertions(+), 160 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index a8f8ccfd..98392c17 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -10,6 +10,7 @@
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
   * Fixed warning text when a mod causes an asset load conflict with itself.
+  * Fixed support for `_international` content assets (used in the movie theater).
 
 * For mod authors:
   * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 8e7465de..a4d29068 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -61,9 +61,6 @@ namespace StardewModdingAPI.Framework
         /// <summary>The loaded content managers (including the <see cref="MainContentManager"/>).</summary>
         private readonly List<IContentManager> ContentManagers = new();
 
-        /// <summary>The language code for language-agnostic mod assets.</summary>
-        private readonly LocalizedContentManager.LanguageCode DefaultLanguage = Constants.DefaultLanguage;
-
         /// <summary>Whether the content coordinator has been disposed.</summary>
         private bool IsDisposed;
 
@@ -350,7 +347,7 @@ namespace StardewModdingAPI.Framework
                 throw new InvalidOperationException($"The '{contentManagerID}' prefix isn't handled by any mod.");
 
             // get fresh asset
-            return contentManager.Load<T>(relativePath, this.DefaultLanguage, useCache: false);
+            return contentManager.LoadExact<T>(relativePath, useCache: false);
         }
 
         /// <summary>Purge matched assets from the cache.</summary>
@@ -467,9 +464,9 @@ namespace StardewModdingAPI.Framework
             return this.ContentManagerLock.InReadLock(() =>
             {
                 List<object> values = new List<object>();
-                foreach (IContentManager content in this.ContentManagers.Where(p => !p.IsNamespaced && p.IsLoaded(assetName, p.Language)))
+                foreach (IContentManager content in this.ContentManagers.Where(p => !p.IsNamespaced && p.IsLoaded(assetName)))
                 {
-                    object value = content.Load<object>(assetName, this.Language, useCache: true);
+                    object value = content.LoadExact<object>(assetName, useCache: true);
                     values.Add(value);
                 }
                 return values;
@@ -582,6 +579,8 @@ namespace StardewModdingAPI.Framework
         /// <param name="info">The asset info to load or edit.</param>
         private IEnumerable<AssetOperationGroup> GetAssetOperationsWithoutCache<T>(IAssetInfo info)
         {
+            IAssetInfo legacyInfo = this.GetLegacyAssetInfo(info);
+
             // new content API
             foreach (AssetOperationGroup group in this.RequestAssetOperations(info))
                 yield return group;
@@ -592,12 +591,12 @@ namespace StardewModdingAPI.Framework
                 // check if loader applies
                 try
                 {
-                    if (!loader.Data.CanLoad<T>(info))
+                    if (!loader.Data.CanLoad<T>(legacyInfo))
                         continue;
                 }
                 catch (Exception ex)
                 {
-                    loader.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    loader.Mod.LogAsMod($"Mod failed when checking whether it could load asset '{legacyInfo.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                     continue;
                 }
 
@@ -610,7 +609,9 @@ namespace StardewModdingAPI.Framework
                             mod: loader.Mod,
                             priority: AssetLoadPriority.Exclusive,
                             onBehalfOf: null,
-                            getData: assetInfo => loader.Data.Load<T>(assetInfo)
+                            getData: assetInfo => loader.Data.Load<T>(
+                                this.GetLegacyAssetInfo(assetInfo)
+                            )
                         )
                     },
                     editOperations: Array.Empty<AssetEditOperation>()
@@ -623,12 +624,12 @@ namespace StardewModdingAPI.Framework
                 // check if editor applies
                 try
                 {
-                    if (!editor.Data.CanEdit<T>(info))
+                    if (!editor.Data.CanEdit<T>(legacyInfo))
                         continue;
                 }
                 catch (Exception ex)
                 {
-                    editor.Mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{info.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
+                    editor.Mod.LogAsMod($"Mod crashed when checking whether it could edit asset '{legacyInfo.Name}', and will be ignored. Error details:\n{ex.GetLogSummary()}", LogLevel.Error);
                     continue;
                 }
 
@@ -642,11 +643,75 @@ namespace StardewModdingAPI.Framework
                             mod: editor.Mod,
                             priority: AssetEditPriority.Default,
                             onBehalfOf: null,
-                            applyEdit: assetData => editor.Data.Edit<T>(assetData)
+                            applyEdit: assetData => editor.Data.Edit<T>(
+                                this.GetLegacyAssetData(assetData)
+                            )
                         )
                     }
                 );
             }
         }
+
+        /// <summary>Get an asset info compatible with legacy <see cref="IAssetLoader"/> and <see cref="IAssetEditor"/> instances, which always expect the base name.</summary>
+        /// <param name="asset">The asset info.</param>
+        private IAssetInfo GetLegacyAssetInfo(IAssetInfo asset)
+        {
+            if (!this.TryGetLegacyAssetName(asset.Name, out IAssetName legacyName))
+                return asset;
+
+            return new AssetInfo(
+                locale: null,
+                assetName: legacyName,
+                type: asset.DataType,
+                getNormalizedPath: this.MainContentManager.AssertAndNormalizeAssetName
+            );
+        }
+
+        /// <summary>Get an asset data compatible with legacy <see cref="IAssetLoader"/> and <see cref="IAssetEditor"/> instances, which always expect the base name.</summary>
+        /// <param name="asset">The asset data.</param>
+        private IAssetData GetLegacyAssetData(IAssetData asset)
+        {
+            if (!this.TryGetLegacyAssetName(asset.Name, out IAssetName legacyName))
+                return asset;
+
+            return asset.Name.LocaleCode == null
+                ? asset
+                : new AssetDataForObject(
+                    locale: null,
+                    assetName: legacyName,
+                    data: asset.Data,
+                    getNormalizedPath: this.MainContentManager.AssertAndNormalizeAssetName
+                );
+        }
+
+        /// <summary>Get an asset name compatible with legacy <see cref="IAssetLoader"/> and <see cref="IAssetEditor"/> instances, which always expect the base name.</summary>
+        /// <param name="asset">The asset name to map.</param>
+        /// <param name="newAsset">The legacy asset name (or the <paramref name="asset"/> if no change is needed).</param>
+        /// <returns>Returns whether any change is needed for legacy compatibility.</returns>
+        private bool TryGetLegacyAssetName(IAssetName asset, out IAssetName newAsset)
+        {
+            // strip _international suffix
+            const string internationalSuffix = "_international";
+            if (asset.Name.EndsWith(internationalSuffix))
+            {
+                newAsset = new AssetName(
+                    baseName: asset.Name[..^internationalSuffix.Length],
+                    localeCode: null,
+                    languageCode: null
+                );
+                return true;
+            }
+
+            // else strip locale
+            if (asset.LocaleCode != null)
+            {
+                newAsset = new AssetName(asset.BaseName, null, null);
+                return true;
+            }
+
+            // else no change needed
+            newAsset = asset;
+            return false;
+        }
     }
 }
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 030c60a7..b1ace259 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;
@@ -32,6 +33,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <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 +43,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>
@@ -115,11 +119,51 @@ namespace StardewModdingAPI.Framework.ContentManagers
         public override T Load<T>(string assetName, LanguageCode language)
         {
             IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
-            return this.Load<T>(parsedName, language, useCache: true);
+            return this.LoadLocalized<T>(parsedName, language, useCache: true);
         }
 
         /// <inheritdoc />
-        public abstract T Load<T>(IAssetName assetName, LanguageCode language, bool useCache);
+        public T LoadLocalized<T>(IAssetName assetName, LanguageCode language, bool useCache)
+        {
+            // 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
+                {
+                    this.LoadExact<T>(localizedName, useCache: useCache);
+                    LocalizedContentManager.localizedAssetNames[assetName.Name] = localizedName.Name;
+                }
+                catch (ContentLoadException)
+                {
+                    localizedName = new AssetName(assetName.BaseName + "_international", null, null);
+                    try
+                    {
+                        this.LoadExact<T>(localizedName, useCache: useCache);
+                        LocalizedContentManager.localizedAssetNames[assetName.Name] = localizedName.Name;
+                    }
+                    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(assetName.Name);
+            return this.LoadExact<T>(assetName, useCache: useCache);
+        }
+
+        /// <inheritdoc />
+        public abstract T LoadExact<T>(IAssetName assetName, bool useCache);
 
         /// <inheritdoc />
         public virtual void OnLocaleChanged() { }
@@ -154,7 +198,11 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public abstract bool IsLoaded(IAssetName assetName, LanguageCode language);
+        public bool IsLoaded(IAssetName assetName)
+        {
+            return this.Cache.ContainsKey(assetName.Name);
+        }
+
 
         /****
         ** Cache invalidation
@@ -241,26 +289,29 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <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)
+                : base.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>(IAssetName assetName, T value, LanguageCode language, bool useCache)
+        protected virtual void TrackAsset<T>(IAssetName assetName, T value, bool useCache)
         {
             // track asset key
             if (value is Texture2D texture)
                 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)
                 this.Cache[assetName.Name] = value;
 
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index a121f4c0..500c0191 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -4,11 +4,9 @@ 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.Reflection;
 using StardewModdingAPI.Framework.Utilities;
 using StardewModdingAPI.Internal;
@@ -91,7 +89,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
+        public override T LoadExact<T>(IAssetName assetName, bool useCache)
         {
             // raise first-load callback
             if (GameContentManager.IsFirstLoad)
@@ -100,19 +98,15 @@ namespace StardewModdingAPI.Framework.ContentManagers
                 this.OnLoadingFirstAsset();
             }
 
-            // normalize asset name
-            if (assetName.LanguageCode.HasValue)
-                return this.Load<T>(this.Coordinator.ParseAssetName(assetName.BaseName), assetName.LanguageCode.Value, 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.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;
             }
 
@@ -122,44 +116,29 @@ namespace StardewModdingAPI.Framework.ContentManagers
             {
                 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.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);
                     asset = this.ApplyEditors<T>(info, asset);
                     return (T)asset.Data;
                 });
             }
 
             // update cache
-            this.TrackAsset(assetName, data, language, useCache);
+            this.TrackAsset(assetName, data, useCache);
 
             // raise event & return data
             this.OnAssetLoaded(this, assetName);
             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()
         {
@@ -175,7 +154,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
 
             // invalidate translatable assets
             string[] invalidated = this
-                .InvalidateCache((key, type) =>
+                .InvalidateCache((key, _) =>
                     removeAssetNames.Contains(key)
                     || removeAssetNames.Contains(this.Coordinator.ParseAssetName(key).BaseName)
                 )
@@ -196,81 +175,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /*********
         ** Private methods
         *********/
-        /// <inheritdoc />
-        protected override void TrackAsset<T>(IAssetName assetName, T value, LanguageCode language, bool useCache)
-        {
-            // handle explicit language in asset name
-            {
-                if (assetName.LanguageCode.HasValue)
-                {
-                    this.TrackAsset(this.Coordinator.ParseAssetName(assetName.BaseName), value, assetName.LanguageCode.Value, 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)
-            {
-                IAssetName translatedKey = new AssetName(assetName.Name, this.GetLocale(language), language);
-                base.TrackAsset(assetName, value, language, useCache: true);
-                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.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);
-            }
-        }
-
-        /// <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>(IAssetName assetName, LanguageCode language, bool useCache)
-        {
-            try
-            {
-                // use cached key
-                if (language == this.Language && this.LocalizedAssetNames.TryGetValue(assetName.Name, out string cachedKey))
-                    return base.RawLoad<T>(cachedKey, useCache);
-
-                // try translated key
-                if (language != LanguageCode.en)
-                {
-                    string translatedKey = $"{assetName}.{this.GetLocale(language)}";
-                    try
-                    {
-                        T obj = base.RawLoad<T>(translatedKey, useCache);
-                        this.LocalizedAssetNames[assetName.Name] = translatedKey;
-                        return obj;
-                    }
-                    catch (ContentLoadException)
-                    {
-                        this.LocalizedAssetNames[assetName.Name] = assetName.Name;
-                    }
-                }
-
-                // try base asset
-                return base.RawLoad<T>(assetName.Name, useCache);
-            }
-            catch (ContentLoadException ex) when (ex.InnerException is FileNotFoundException { InnerException: null })
-            {
-                throw new SContentLoadException($"Error loading \"{assetName}\": it isn't in the Content folder and no mod provided it.");
-            }
-        }
-
         /// <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>
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs b/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
index 847e2ce1..3f7188da 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManagerForAssetPropagation.cs
@@ -25,9 +25,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
             : base(name, serviceProvider, rootDirectory, currentCulture, coordinator, monitor, reflection, onDisposing, onLoadingFirstAsset, onAssetLoaded, aggressiveMemoryOptimizations) { }
 
         /// <inheritdoc />
-        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
+        public override T LoadExact<T>(IAssetName assetName, bool useCache)
         {
-            T data = base.Load<T>(assetName, language, useCache);
+            T data = base.LoadExact<T>(assetName, useCache);
 
             if (data is Texture2D texture)
                 texture.Tag = this.Tag;
diff --git a/src/SMAPI/Framework/ContentManagers/IContentManager.cs b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
index 6d71472f..4de9a8c3 100644
--- a/src/SMAPI/Framework/ContentManagers/IContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
@@ -32,12 +32,17 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="assetName">The normalized asset name.</param>
         bool DoesAssetExist(IAssetName assetName);
 
-        /// <summary>Load an asset that has been processed by the content pipeline.</summary>
+        /// <summary>Load an asset through the content pipeline, using a localized variant of the <paramref name="assetName"/> if available.</summary>
         /// <typeparam name="T">The type of asset to load.</typeparam>
         /// <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>(IAssetName assetName, LocalizedContentManager.LanguageCode language, bool useCache);
+        T LoadLocalized<T>(IAssetName assetName, LocalizedContentManager.LanguageCode language, bool useCache);
+
+        /// <summary>Load an asset through the content pipeline, using the exact asset name without checking for localized variants.</summary>
+        /// <typeparam name="T">The type of asset to load.</typeparam>
+        /// <param name="assetName">The asset name relative to the loader root directory.</param>
+        /// <param name="useCache">Whether to read/write the loaded asset to the asset cache.</param>
+        T LoadExact<T>(IAssetName assetName, 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>
@@ -53,8 +58,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(IAssetName assetName, LocalizedContentManager.LanguageCode language);
+        bool IsLoaded(IAssetName assetName);
 
         /// <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 90836fcf..375b5e0e 100644
--- a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
@@ -61,6 +61,8 @@ namespace StardewModdingAPI.Framework.ContentManagers
             this.GameContentManager = gameContentManager;
             this.JsonHelper = jsonHelper;
             this.ModName = modName;
+
+            this.TryLocalizeKeys = false;
         }
 
         /// <inheritdoc />
@@ -80,14 +82,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         }
 
         /// <inheritdoc />
-        public override T Load<T>(string assetName, LanguageCode language)
-        {
-            IAssetName parsedName = this.Coordinator.ParseAssetName(assetName);
-            return this.Load<T>(parsedName, language, useCache: false);
-        }
-
-        /// <inheritdoc />
-        public override T Load<T>(IAssetName assetName, LanguageCode language, bool useCache)
+        public override T LoadExact<T>(IAssetName assetName, bool useCache)
         {
             // disable caching
             // This is necessary to avoid assets being shared between content managers, which can
@@ -97,11 +92,6 @@ namespace StardewModdingAPI.Framework.ContentManagers
             if (useCache)
                 throw new InvalidOperationException("Mod content managers don't support asset caching.");
 
-            // disable language handling
-            // Mod files don't support automatic translation logic, so this should never happen.
-            if (language != this.DefaultLanguage)
-                throw new InvalidOperationException("Localized assets aren't supported by the mod content manager.");
-
             // resolve managed asset key
             {
                 if (this.Coordinator.TryParseManagedAssetKey(assetName.Name, out string contentManagerID, out IAssetName relativePath))
@@ -130,14 +120,14 @@ 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 = assetName.Name[..^".xnb".Length];
+                            IAssetName loadName = this.Coordinator.ParseAssetName(assetName.Name[..^".xnb".Length]);
 
                             // load asset
                             asset = this.RawLoad<T>(loadName, useCache: false);
                             if (asset is Map map)
                             {
-                                map.assetPath = loadName;
-                                this.FixTilesheetPaths(map, relativeMapPath: loadName, fixEagerPathPrefixes: true);
+                                map.assetPath = loadName.Name;
+                                this.FixTilesheetPaths(map, relativeMapPath: loadName.Name, fixEagerPathPrefixes: true);
                             }
                         }
                         break;
@@ -201,16 +191,10 @@ namespace StardewModdingAPI.Framework.ContentManagers
             }
 
             // track & return asset
-            this.TrackAsset(assetName, asset, language, useCache);
+            this.TrackAsset(assetName, asset, useCache);
             return asset;
         }
 
-        /// <inheritdoc />
-        public override bool IsLoaded(IAssetName assetName, LanguageCode language)
-        {
-            return this.Cache.ContainsKey(assetName.Name);
-        }
-
         /// <inheritdoc />
         public override LocalizedContentManager CreateTemporary()
         {
@@ -371,7 +355,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             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
+                this.GameContentManager.LoadLocalized<Texture2D>(contentKey, this.GameContentManager.Language, useCache: true); // no need to bypass cache here, since we're not storing the asset
                 assetName = contentKey;
                 return true;
             }
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index 4e522c8d..3416c286 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -88,10 +88,10 @@ namespace StardewModdingAPI.Framework.ModHelpers
                 switch (source)
                 {
                     case ContentSource.GameContent:
-                        return this.GameContentManager.Load<T>(assetName, this.CurrentLocaleConstant, useCache: false);
+                        return this.GameContentManager.LoadLocalized<T>(assetName, this.CurrentLocaleConstant, useCache: false);
 
                     case ContentSource.ModFolder:
-                        return this.ModContentManager.Load<T>(assetName, Constants.DefaultLanguage, useCache: false);
+                        return this.ModContentManager.LoadExact<T>(assetName, useCache: false);
 
                     default:
                         throw new SContentLoadException($"{this.ModName} failed loading content asset '{key}' from {source}: unknown content source '{source}'.");
-- 
cgit 


From 8d704153762fa73416a3ccb44ee71032952802eb Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 26 Mar 2022 15:02:11 -0400
Subject: add deprecation notices for SMAPI 4.0.0 (#766)

---
 docs/release-notes.md                           | 37 +++++++++++--------------
 src/SMAPI/Constants.cs                          | 17 ++++++++++--
 src/SMAPI/Framework/Content/AssetInfo.cs        | 23 ++++++++++++++-
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs | 34 ++++++++++++++++++++---
 src/SMAPI/Framework/SCore.cs                    | 19 +++++++++++++
 src/SMAPI/IAssetInfo.cs                         |  1 +
 6 files changed, 103 insertions(+), 28 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 98392c17..464049b9 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -3,37 +3,32 @@
 # Release notes
 ## Upcoming release
 * For players:
-  * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
-  * Fixed `player_add` console command's handling of Journal Scraps and Secret Notes.
-  * Fixed `set_farm_type` console command not updating warps if they moved.
-  * Improved [command-line arguments](technical/smapi.md#command-line-arguments) on Linux/macOS:
+  * Fixed support for `_international` content assets (used in the movie theater).
+  * Fixed the warning text when a mod causes an asset load conflict with itself.
+  * Improved Linux/macOS [command-line arguments](technical/smapi.md#command-line-arguments):
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
-  * Fixed warning text when a mod causes an asset load conflict with itself.
-  * Fixed support for `_international` content assets (used in the movie theater).
+  * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+
+* For the Console Commands mod:
+  * Fixed `player_add` not handling journal scraps and secret notes correctly.
+  * Fixed `set_farm_type` not updating warps.
 
 * For mod authors:
-  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
-    _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has been changed._
-  * Overhauled [mod-provided APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) (thanks to Shockah!).  
-    _This adds support for many previously-unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more._
+  * **Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.**  
+    _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
+  * **Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying** (thanks to Shockah!).  
+    _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
+  * **Deprecation warning:** The upcoming SMAPI 4.0 will remove deprecated APIs and break mods which haven't updated yet.  
+    _See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0) for help updating your mod code. You can update your mod code now, there's no need to wait for the 4.0.0 release (which will happen in at least three months, and possibly later if needed to update open-source mods)._
   * Added `Constants.ContentPath`.
-  * Added `IAssetName Name` field to the info received by `IAssetEditor` and `IAssetLoader` methods.  
+  * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
-  * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated via `helper.Content.InvalidateCache`.
+  * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
 
-* **Deprecation warning for mod authors:**   
-  These APIs are now deprecated and will be removed in the upcoming SMAPI 4.0.0.
-
-  API | how to update code
-  :-- | :-----------------
-  `Constants.ExecutionPath` | Use `Constants.GamePath` instead.
-  `IAssetInfo.AssetName`<br />`IAssetData.AssetName` | Use `Name` instead, which changes the type from `string` to the new `AssetName`.
-  `IAssetInfo.AssetNameEquals`<br />`IAssetData.AssetNameEquals` | Use `Name.IsEquivalentTo` instead.
-
 * For the web UI:
   * Updated the JSON validator/schema for Content Patcher 1.25.0.
   * Added `data-*` attributes to log parser page for external tools.
diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index b736ca59..3351e5c4 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -77,8 +77,21 @@ namespace StardewModdingAPI
         public static GameFramework GameFramework { get; } = EarlyConstants.GameFramework;
 
         /// <summary>The path to the game folder.</summary>
-        [Obsolete($"Use {nameof(GamePath)} instead.")]
-        public static string ExecutionPath => Constants.GamePath;
+        [Obsolete($"Use {nameof(Constants)}.{nameof(GamePath)} instead.")]
+        public static string ExecutionPath
+        {
+            get
+            {
+                SCore.DeprecationManager.Warn(
+                    source: SCore.DeprecationManager.GetSourceNameFromStack(),
+                    nounPhrase: $"{nameof(Constants)}.{nameof(Constants.ExecutionPath)}",
+                    version: "3.14.0",
+                    severity: DeprecationLevel.Notice
+                );
+
+                return Constants.GamePath;
+            }
+        }
 
         /// <summary>The path to the game folder.</summary>
         public static string GamePath { get; } = EarlyConstants.GamePath;
diff --git a/src/SMAPI/Framework/Content/AssetInfo.cs b/src/SMAPI/Framework/Content/AssetInfo.cs
index 556f1c2a..6e93c33c 100644
--- a/src/SMAPI/Framework/Content/AssetInfo.cs
+++ b/src/SMAPI/Framework/Content/AssetInfo.cs
@@ -27,7 +27,20 @@ namespace StardewModdingAPI.Framework.Content
 
         /// <inheritdoc />
         [Obsolete($"Use {nameof(Name)} or {nameof(NameWithoutLocale)} instead.")]
-        public string AssetName => this.NameWithoutLocale.Name;
+        public string AssetName
+        {
+            get
+            {
+                SCore.DeprecationManager.Warn(
+                    source: SCore.DeprecationManager.GetSourceNameFromStack(),
+                    nounPhrase: $"{nameof(IAssetInfo)}.{nameof(IAssetInfo.AssetName)}",
+                    version: "3.14.0",
+                    severity: DeprecationLevel.Notice
+                );
+
+                return this.NameWithoutLocale.Name;
+            }
+        }
 
         /// <inheritdoc />
         public Type DataType { get; }
@@ -54,6 +67,14 @@ namespace StardewModdingAPI.Framework.Content
         [Obsolete($"Use {nameof(Name)}.{nameof(IAssetName.IsEquivalentTo)} or {nameof(NameWithoutLocale)}.{nameof(IAssetName.IsEquivalentTo)} instead.")]
         public bool AssetNameEquals(string path)
         {
+            SCore.DeprecationManager.Warn(
+                source: SCore.DeprecationManager.GetSourceNameFromStack(),
+                nounPhrase: $"{nameof(IAssetInfo)}.{nameof(IAssetInfo.AssetNameEquals)}",
+                version: "3.14.0",
+                severity: DeprecationLevel.Notice
+            );
+
+
             return this.NameWithoutLocale.IsEquivalentTo(path);
         }
 
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index 3416c286..3727b909 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -44,16 +44,42 @@ namespace StardewModdingAPI.Framework.ModHelpers
         public LocalizedContentManager.LanguageCode CurrentLocaleConstant => this.GameContentManager.Language;
 
         /// <summary>The observable implementation of <see cref="AssetEditors"/>.</summary>
-        internal ObservableCollection<IAssetEditor> ObservableAssetEditors { get; } = new ObservableCollection<IAssetEditor>();
+        internal ObservableCollection<IAssetEditor> ObservableAssetEditors { get; } = new();
 
         /// <summary>The observable implementation of <see cref="AssetLoaders"/>.</summary>
-        internal ObservableCollection<IAssetLoader> ObservableAssetLoaders { get; } = new ObservableCollection<IAssetLoader>();
+        internal ObservableCollection<IAssetLoader> ObservableAssetLoaders { get; } = new();
 
         /// <inheritdoc />
-        public IList<IAssetLoader> AssetLoaders => this.ObservableAssetLoaders;
+        public IList<IAssetLoader> AssetLoaders
+        {
+            get
+            {
+                SCore.DeprecationManager.Warn(
+                    source: this.ModName,
+                    nounPhrase: $"{nameof(IContentHelper)}.{nameof(IContentHelper.AssetLoaders)}",
+                    version: "3.14.0",
+                    severity: DeprecationLevel.Notice
+                );
+
+                return this.ObservableAssetLoaders;
+            }
+        }
 
         /// <inheritdoc />
-        public IList<IAssetEditor> AssetEditors => this.ObservableAssetEditors;
+        public IList<IAssetEditor> AssetEditors
+        {
+            get
+            {
+                SCore.DeprecationManager.Warn(
+                    source: this.ModName,
+                    nounPhrase: $"{nameof(IContentHelper)}.{nameof(IContentHelper.AssetEditors)}",
+                    version: "3.14.0",
+                    severity: DeprecationLevel.Notice
+                );
+
+                return this.ObservableAssetEditors;
+            }
+        }
 
 
         /*********
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index dd952dee..eab977ac 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1609,9 +1609,28 @@ namespace StardewModdingAPI.Framework
                 {
                     // ReSharper disable SuspiciousTypeConversion.Global
                     if (metadata.Mod is IAssetEditor editor)
+                    {
+                        SCore.DeprecationManager.Warn(
+                            source: metadata.DisplayName,
+                            nounPhrase: $"{nameof(IAssetEditor)}",
+                            version: "3.14.0",
+                            severity: DeprecationLevel.Notice
+                        );
+
                         this.ContentCore.Editors.Add(new ModLinked<IAssetEditor>(metadata, editor));
+                    }
+
                     if (metadata.Mod is IAssetLoader loader)
+                    {
+                        SCore.DeprecationManager.Warn(
+                            source: metadata.DisplayName,
+                            nounPhrase: $"{nameof(IAssetLoader)}",
+                            version: "3.14.0",
+                            severity: DeprecationLevel.Notice
+                        );
+
                         this.ContentCore.Loaders.Add(new ModLinked<IAssetLoader>(metadata, loader));
+                    }
                     // ReSharper restore SuspiciousTypeConversion.Global
 
                     helper.ObservableAssetEditors.CollectionChanged += (sender, e) => this.OnAssetInterceptorsChanged(metadata, e.NewItems?.Cast<IAssetEditor>(), e.OldItems?.Cast<IAssetEditor>(), this.ContentCore.Editors);
diff --git a/src/SMAPI/IAssetInfo.cs b/src/SMAPI/IAssetInfo.cs
index c7b2ab62..c3753b97 100644
--- a/src/SMAPI/IAssetInfo.cs
+++ b/src/SMAPI/IAssetInfo.cs
@@ -12,6 +12,7 @@ namespace StardewModdingAPI
         string Locale { get; }
 
         /// <summary>The asset name being read.</summary>
+        /// <remarks>NOTE: when reading this field from an <see cref="IAssetLoader"/> or <see cref="IAssetEditor"/> implementation, it's always equivalent to <see cref="NameWithoutLocale"/> for backwards compatibility.</remarks>
         public IAssetName Name { get; }
 
         /// <summary>The <see cref="Name"/> with any locale codes stripped.</summary>
-- 
cgit 


From bacb851d7b186946ba1ead1caeab72e7604cfe6b Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 26 Mar 2022 17:44:48 -0400
Subject: add IContentHelper.ParseAssetName (#766)

---
 docs/release-notes.md                           | 1 +
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs | 6 ++++++
 src/SMAPI/IContentHelper.cs                     | 6 ++++++
 3 files changed, 13 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 464049b9..99ac86df 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -24,6 +24,7 @@
   * Added `Constants.ContentPath`.
   * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
+  * Added `helper.Content.ParseAssetName` to get an `IAssetName` for an arbitrary asset key.
   * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index 3727b909..5d58ee26 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -103,6 +103,12 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.Monitor = monitor;
         }
 
+        /// <inheritdoc />
+        public IAssetName ParseAssetName(string rawName)
+        {
+            return this.ContentCore.ParseAssetName(rawName);
+        }
+
         /// <inheritdoc />
         public T Load<T>(string key, ContentSource source = ContentSource.ModFolder)
         {
diff --git a/src/SMAPI/IContentHelper.cs b/src/SMAPI/IContentHelper.cs
index 207b4a33..6fcd18cd 100644
--- a/src/SMAPI/IContentHelper.cs
+++ b/src/SMAPI/IContentHelper.cs
@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Diagnostics.Contracts;
 using Microsoft.Xna.Framework.Content;
 using Microsoft.Xna.Framework.Graphics;
+using StardewModdingAPI.Framework.Content;
 using StardewValley;
 using xTile;
 
@@ -30,6 +31,11 @@ namespace StardewModdingAPI
         /*********
         ** Public methods
         *********/
+        /// <summary>Parse a raw asset name.</summary>
+        /// <param name="rawName">The raw asset name to parse.</param>
+        /// <exception cref="ArgumentException">The <paramref name="rawName"/> is null or empty.</exception>
+        IAssetName ParseAssetName(string rawName);
+
         /// <summary>Load content from the game folder or mod folder (if not already cached), and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
         /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
         /// <param name="key">The asset key to fetch (if the <paramref name="source"/> is <see cref="ContentSource.GameContent"/>), or the local path to a content file relative to the mod folder.</param>
-- 
cgit 


From 1d3c99cc25f6c0d504fd5e43ea71ef327b6e9066 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sun, 27 Mar 2022 13:42:14 -0400
Subject: split helper.Content API into game/mod content APIs

---
 docs/release-notes.md                              |   2 +
 src/SMAPI/Framework/Content/AssetName.cs           |  12 ++
 src/SMAPI/Framework/ContentPack.cs                 |  24 ++--
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs    |   9 +-
 .../Framework/ModHelpers/GameContentHelper.cs      | 129 +++++++++++++++++++++
 src/SMAPI/Framework/ModHelpers/ModContentHelper.cs |  75 ++++++++++++
 src/SMAPI/Framework/ModHelpers/ModHelper.cs        |  38 +++++-
 src/SMAPI/Framework/SCore.cs                       |  12 +-
 src/SMAPI/IAssetName.cs                            |   5 +
 src/SMAPI/IContentHelper.cs                        |  10 +-
 src/SMAPI/IContentPack.cs                          |   5 +
 src/SMAPI/IGameContentHelper.cs                    |  73 ++++++++++++
 src/SMAPI/IModContentHelper.cs                     |  32 +++++
 src/SMAPI/IModHelper.cs                            |  10 ++
 14 files changed, 400 insertions(+), 36 deletions(-)
 create mode 100644 src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
 create mode 100644 src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
 create mode 100644 src/SMAPI/IGameContentHelper.cs
 create mode 100644 src/SMAPI/IModContentHelper.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 99ac86df..2e09240c 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -17,10 +17,12 @@
 * For mod authors:
   * **Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.**  
     _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
+  * **Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.**
   * **Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying** (thanks to Shockah!).  
     _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
   * **Deprecation warning:** The upcoming SMAPI 4.0 will remove deprecated APIs and break mods which haven't updated yet.  
     _See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0) for help updating your mod code. You can update your mod code now, there's no need to wait for the 4.0.0 release (which will happen in at least three months, and possibly later if needed to update open-source mods)._
+  * Added `IContentPack.ModContent` property.
   * Added `Constants.ContentPath`.
   * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
diff --git a/src/SMAPI/Framework/Content/AssetName.cs b/src/SMAPI/Framework/Content/AssetName.cs
index 7ce0f8ee..a1d37b0b 100644
--- a/src/SMAPI/Framework/Content/AssetName.cs
+++ b/src/SMAPI/Framework/Content/AssetName.cs
@@ -100,6 +100,18 @@ namespace StardewModdingAPI.Framework.Content
             return compareTo.Equals(assetName, StringComparison.OrdinalIgnoreCase);
         }
 
+        /// <inheritdoc />
+        public bool IsEquivalentTo(IAssetName assetName, bool useBaseName = false)
+        {
+            if (useBaseName)
+                return this.BaseName.Equals(assetName?.BaseName, StringComparison.OrdinalIgnoreCase);
+
+            if (assetName is AssetName impl)
+                return this.ComparableName == impl?.ComparableName;
+
+            return this.Name.Equals(assetName?.Name, StringComparison.OrdinalIgnoreCase);
+        }
+
         /// <inheritdoc />
         public bool StartsWith(string prefix, bool allowPartialWord = true, bool allowSubfolder = true)
         {
diff --git a/src/SMAPI/Framework/ContentPack.cs b/src/SMAPI/Framework/ContentPack.cs
index b6add7b5..3920354e 100644
--- a/src/SMAPI/Framework/ContentPack.cs
+++ b/src/SMAPI/Framework/ContentPack.cs
@@ -13,9 +13,6 @@ namespace StardewModdingAPI.Framework
         /*********
         ** Fields
         *********/
-        /// <summary>Provides an API for loading content assets.</summary>
-        private readonly IContentHelper Content;
-
         /// <summary>Encapsulates SMAPI's JSON file parsing.</summary>
         private readonly JsonHelper JsonHelper;
 
@@ -35,6 +32,9 @@ namespace StardewModdingAPI.Framework
         /// <inheritdoc />
         public ITranslationHelper Translation => this.TranslationImpl;
 
+        /// <inheritdoc />
+        public IModContentHelper ModContent { get; }
+
         /// <summary>The underlying translation helper.</summary>
         internal TranslationHelper TranslationImpl { get; set; }
 
@@ -45,14 +45,14 @@ namespace StardewModdingAPI.Framework
         /// <summary>Construct an instance.</summary>
         /// <param name="directoryPath">The full path to the content pack's folder.</param>
         /// <param name="manifest">The content pack's manifest.</param>
-        /// <param name="content">Provides an API for loading content assets.</param>
+        /// <param name="content">Provides an API for loading content assets from the content pack's folder.</param>
         /// <param name="translation">Provides translations stored in the content pack's <c>i18n</c> folder.</param>
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
-        public ContentPack(string directoryPath, IManifest manifest, IContentHelper content, TranslationHelper translation, JsonHelper jsonHelper)
+        public ContentPack(string directoryPath, IManifest manifest, IModContentHelper content, TranslationHelper translation, JsonHelper jsonHelper)
         {
             this.DirectoryPath = directoryPath;
             this.Manifest = manifest;
-            this.Content = content;
+            this.ModContent = content;
             this.TranslationImpl = translation;
             this.JsonHelper = jsonHelper;
 
@@ -95,21 +95,17 @@ namespace StardewModdingAPI.Framework
         }
 
         /// <inheritdoc />
+        [Obsolete]
         public T LoadAsset<T>(string key)
         {
-            key = PathUtilities.NormalizePath(key);
-
-            key = this.GetCaseInsensitiveRelativePath(key);
-            return this.Content.Load<T>(key, ContentSource.ModFolder);
+            return this.ModContent.Load<T>(key);
         }
 
         /// <inheritdoc />
+        [Obsolete]
         public string GetActualAssetKey(string key)
         {
-            key = PathUtilities.NormalizePath(key);
-
-            key = this.GetCaseInsensitiveRelativePath(key);
-            return this.Content.GetActualAssetKey(key, ContentSource.ModFolder);
+            return this.ModContent.GetInternalAssetName(key)?.Name;
         }
 
 
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index 3a5c8938..b0064532 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -13,6 +13,7 @@ using StardewValley;
 namespace StardewModdingAPI.Framework.ModHelpers
 {
     /// <summary>Provides an API for loading content assets.</summary>
+    [Obsolete]
     internal class ContentHelper : BaseHelper, IContentHelper
     {
         /*********
@@ -44,11 +45,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
         public LocalizedContentManager.LanguageCode CurrentLocaleConstant => this.GameContentManager.Language;
 
         /// <summary>The observable implementation of <see cref="AssetEditors"/>.</summary>
-        [Obsolete]
         internal ObservableCollection<IAssetEditor> ObservableAssetEditors { get; } = new();
 
         /// <summary>The observable implementation of <see cref="AssetLoaders"/>.</summary>
-        [Obsolete]
         internal ObservableCollection<IAssetLoader> ObservableAssetLoaders { get; } = new();
 
         /// <inheritdoc />
@@ -105,12 +104,6 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.Monitor = monitor;
         }
 
-        /// <inheritdoc />
-        public IAssetName ParseAssetName(string rawName)
-        {
-            return this.ContentCore.ParseAssetName(rawName);
-        }
-
         /// <inheritdoc />
         public T Load<T>(string key, ContentSource source = ContentSource.ModFolder)
         {
diff --git a/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs b/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
new file mode 100644
index 00000000..42a4de20
--- /dev/null
+++ b/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
@@ -0,0 +1,129 @@
+using System;
+using System.Linq;
+using StardewModdingAPI.Framework.Content;
+using StardewModdingAPI.Framework.ContentManagers;
+using StardewModdingAPI.Framework.Exceptions;
+using StardewValley;
+
+namespace StardewModdingAPI.Framework.ModHelpers
+{
+    /// <inheritdoc cref="IGameContentHelper"/>
+    internal class GameContentHelper : BaseHelper, IGameContentHelper
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>SMAPI's core content logic.</summary>
+        private readonly ContentCoordinator ContentCore;
+
+        /// <summary>The underlying game content manager.</summary>
+        private readonly IContentManager GameContentManager;
+
+        /// <summary>The friendly mod name for use in errors.</summary>
+        private readonly string ModName;
+
+        /// <summary>Encapsulates monitoring and logging.</summary>
+        private readonly IMonitor Monitor;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <inheritdoc />
+        public string CurrentLocale => this.GameContentManager.GetLocale();
+
+        /// <inheritdoc />
+        public LocalizedContentManager.LanguageCode CurrentLocaleConstant => this.GameContentManager.Language;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="contentCore">SMAPI's core content logic.</param>
+        /// <param name="modID">The unique ID of the relevant mod.</param>
+        /// <param name="modName">The friendly mod name for use in errors.</param>
+        /// <param name="monitor">Encapsulates monitoring and logging.</param>
+        public GameContentHelper(ContentCoordinator contentCore, string modID, string modName, IMonitor monitor)
+            : base(modID)
+        {
+            string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
+
+            this.ContentCore = contentCore;
+            this.GameContentManager = contentCore.CreateGameContentManager(managedAssetPrefix + ".content");
+            this.ModName = modName;
+            this.Monitor = monitor;
+        }
+
+        /// <inheritdoc />
+        public IAssetName ParseAssetName(string rawName)
+        {
+            return this.ContentCore.ParseAssetName(rawName);
+        }
+
+        /// <inheritdoc />
+        public T Load<T>(string key)
+        {
+            IAssetName assetName = this.ContentCore.ParseAssetName(key);
+            return this.Load<T>(assetName);
+        }
+
+        /// <inheritdoc />
+        public T Load<T>(IAssetName assetName)
+        {
+            try
+            {
+                return this.GameContentManager.LoadLocalized<T>(assetName, this.CurrentLocaleConstant, useCache: false);
+            }
+            catch (Exception ex) when (ex is not SContentLoadException)
+            {
+                throw new SContentLoadException($"{this.ModName} failed loading content asset '{assetName}' from the game content.", ex);
+            }
+        }
+
+        /// <inheritdoc />
+        public bool InvalidateCache(string key)
+        {
+            IAssetName assetName = this.ParseAssetName(key);
+            return this.InvalidateCache(assetName);
+        }
+
+        /// <inheritdoc />
+        public bool InvalidateCache(IAssetName assetName)
+        {
+            this.Monitor.Log($"Requested cache invalidation for '{assetName}'.");
+            return this.ContentCore.InvalidateCache(asset => asset.Name.IsEquivalentTo(assetName)).Any();
+        }
+
+        /// <inheritdoc />
+        public bool InvalidateCache<T>()
+        {
+            this.Monitor.Log($"Requested cache invalidation for all assets of type {typeof(T)}. This is an expensive operation and should be avoided if possible.");
+            return this.ContentCore.InvalidateCache((_, _, type) => typeof(T).IsAssignableFrom(type)).Any();
+        }
+
+        /// <inheritdoc />
+        public bool InvalidateCache(Func<IAssetInfo, bool> predicate)
+        {
+            this.Monitor.Log("Requested cache invalidation for all assets matching a predicate.");
+            return this.ContentCore.InvalidateCache(predicate).Any();
+        }
+
+        /// <inheritdoc />
+        public IAssetData GetPatchHelper<T>(T data, string assetName = null)
+        {
+            if (data == null)
+                throw new ArgumentNullException(nameof(data), "Can't get a patch helper for a null value.");
+
+            assetName ??= $"temp/{Guid.NewGuid():N}";
+
+            return new AssetDataForObject(this.CurrentLocale, this.ContentCore.ParseAssetName(assetName), data, key => this.ParseAssetName(key).Name);
+        }
+
+        /// <summary>Get the underlying game content manager.</summary>
+        internal IContentManager GetUnderlyingContentManager()
+        {
+            return this.GameContentManager;
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
new file mode 100644
index 00000000..45899dd7
--- /dev/null
+++ b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
@@ -0,0 +1,75 @@
+using System;
+using StardewModdingAPI.Framework.Content;
+using StardewModdingAPI.Framework.ContentManagers;
+using StardewModdingAPI.Framework.Exceptions;
+
+namespace StardewModdingAPI.Framework.ModHelpers
+{
+    /// <inheritdoc cref="IModContentHelper"/>
+    internal class ModContentHelper : BaseHelper, IModContentHelper
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>SMAPI's core content logic.</summary>
+        private readonly ContentCoordinator ContentCore;
+
+        /// <summary>A content manager for this mod which manages files from the mod's folder.</summary>
+        private readonly ModContentManager ModContentManager;
+
+        /// <summary>The friendly mod name for use in errors.</summary>
+        private readonly string ModName;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="contentCore">SMAPI's core content logic.</param>
+        /// <param name="modFolderPath">The absolute path to the mod folder.</param>
+        /// <param name="modID">The unique ID of the relevant mod.</param>
+        /// <param name="modName">The friendly mod name for use in errors.</param>
+        /// <param name="gameContentManager">The game content manager used for map tilesheets not provided by the mod.</param>
+        public ModContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IContentManager gameContentManager)
+            : base(modID)
+        {
+            string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
+
+            this.ContentCore = contentCore;
+            this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, modName, modFolderPath, gameContentManager);
+            this.ModName = modName;
+        }
+
+        /// <inheritdoc />
+        public T Load<T>(string relativePath)
+        {
+            IAssetName assetName = this.ContentCore.ParseAssetName(relativePath);
+
+            try
+            {
+                return this.ModContentManager.LoadExact<T>(assetName, useCache: false);
+            }
+            catch (Exception ex) when (ex is not SContentLoadException)
+            {
+                throw new SContentLoadException($"{this.ModName} failed loading content asset '{relativePath}' from its mod folder.", ex);
+            }
+        }
+
+        /// <inheritdoc />
+        public IAssetName GetInternalAssetName(string relativePath)
+        {
+            return this.ModContentManager.GetInternalAssetKey(relativePath);
+        }
+
+        /// <inheritdoc />
+        public IAssetData GetPatchHelper<T>(T data, string relativePath = null)
+        {
+            if (data == null)
+                throw new ArgumentNullException(nameof(data), "Can't get a patch helper for a null value.");
+
+            relativePath ??= $"temp/{Guid.NewGuid():N}";
+
+            return new AssetDataForObject(this.ContentCore.GetLocale(), this.ContentCore.ParseAssetName(relativePath), data, key => this.ContentCore.ParseAssetName(key).Name);
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/ModHelpers/ModHelper.cs b/src/SMAPI/Framework/ModHelpers/ModHelper.cs
index 058bff83..d28faacc 100644
--- a/src/SMAPI/Framework/ModHelpers/ModHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ModHelper.cs
@@ -8,6 +8,14 @@ namespace StardewModdingAPI.Framework.ModHelpers
     /// <summary>Provides simplified APIs for writing mods.</summary>
     internal class ModHelper : BaseHelper, IModHelper, IDisposable
     {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The backing field for <see cref="Content"/>.</summary>
+        [Obsolete]
+        private readonly IContentHelper ContentImpl;
+
+
         /*********
         ** Accessors
         *********/
@@ -18,7 +26,27 @@ namespace StardewModdingAPI.Framework.ModHelpers
         public IModEvents Events { get; }
 
         /// <inheritdoc />
-        public IContentHelper Content { get; }
+        [Obsolete]
+        public IContentHelper Content
+        {
+            get
+            {
+                SCore.DeprecationManager.Warn(
+                    source: SCore.DeprecationManager.GetSourceName(this.ModID),
+                    nounPhrase: $"{nameof(IModHelper)}.{nameof(IModHelper.Content)}",
+                    version: "3.14.0",
+                    severity: DeprecationLevel.Notice
+                );
+
+                return this.ContentImpl;
+            }
+        }
+
+        /// <inheritdoc />
+        public IGameContentHelper GameContent { get; }
+
+        /// <inheritdoc />
+        public IModContentHelper ModContent { get; }
 
         /// <inheritdoc />
         public IContentPackHelper ContentPacks { get; }
@@ -54,6 +82,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="currentInputState">Manages the game's input state for the current player instance. That may not be the main player in split-screen mode.</param>
         /// <param name="events">Manages access to events raised by SMAPI.</param>
         /// <param name="contentHelper">An API for loading content assets.</param>
+        /// <param name="gameContentHelper">An API for loading content assets from the game's <c>Content</c> folder or via <see cref="IModEvents.Content"/>.</param>
+        /// <param name="modContentHelper">An API for loading content assets from your mod's files.</param>
         /// <param name="contentPackHelper">An API for managing content packs.</param>
         /// <param name="commandHelper">An API for managing console commands.</param>
         /// <param name="dataHelper">An API for reading and writing persistent mod data.</param>
@@ -63,7 +93,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="translationHelper">An API for reading translations stored in the mod's <c>i18n</c> folder.</param>
         /// <exception cref="ArgumentNullException">An argument is null or empty.</exception>
         /// <exception cref="InvalidOperationException">The <paramref name="modDirectory"/> path does not exist on disk.</exception>
-        public ModHelper(string modID, string modDirectory, Func<SInputState> currentInputState, IModEvents events, IContentHelper contentHelper, IContentPackHelper contentPackHelper, ICommandHelper commandHelper, IDataHelper dataHelper, IModRegistry modRegistry, IReflectionHelper reflectionHelper, IMultiplayerHelper multiplayer, ITranslationHelper translationHelper)
+        public ModHelper(string modID, string modDirectory, Func<SInputState> currentInputState, IModEvents events, IContentHelper contentHelper, IGameContentHelper gameContentHelper, IModContentHelper modContentHelper, IContentPackHelper contentPackHelper, ICommandHelper commandHelper, IDataHelper dataHelper, IModRegistry modRegistry, IReflectionHelper reflectionHelper, IMultiplayerHelper multiplayer, ITranslationHelper translationHelper)
             : base(modID)
         {
             // validate directory
@@ -74,7 +104,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
 
             // initialize
             this.DirectoryPath = modDirectory;
-            this.Content = contentHelper ?? throw new ArgumentNullException(nameof(contentHelper));
+            this.ContentImpl = contentHelper ?? throw new ArgumentNullException(nameof(contentHelper));
+            this.GameContent = gameContentHelper ?? throw new ArgumentNullException(nameof(gameContentHelper));
+            this.ModContent = modContentHelper ?? throw new ArgumentNullException(nameof(modContentHelper));
             this.ContentPacks = contentPackHelper ?? throw new ArgumentNullException(nameof(contentPackHelper));
             this.Data = dataHelper ?? throw new ArgumentNullException(nameof(dataHelper));
             this.Input = new InputHelper(modID, currentInputState);
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index efdfabe7..b4aa3595 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1775,9 +1775,10 @@ namespace StardewModdingAPI.Framework
             {
                 IManifest manifest = mod.Manifest;
                 IMonitor monitor = this.LogManager.GetMonitor(mod.DisplayName);
-                IContentHelper contentHelper = new ContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor);
+                GameContentHelper gameContentHelper = new(this.ContentCore, manifest.UniqueID, mod.DisplayName, monitor);
+                IModContentHelper modContentHelper = new ModContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager());
                 TranslationHelper translationHelper = new(manifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
-                IContentPack contentPack = new ContentPack(mod.DirectoryPath, manifest, contentHelper, translationHelper, jsonHelper);
+                IContentPack contentPack = new ContentPack(mod.DirectoryPath, manifest, modContentHelper, translationHelper, jsonHelper);
                 mod.SetMod(contentPack, monitor, translationHelper);
                 this.ModRegistry.Add(mod);
 
@@ -1855,7 +1856,8 @@ namespace StardewModdingAPI.Framework
                         IContentPack CreateFakeContentPack(string packDirPath, IManifest packManifest)
                         {
                             IMonitor packMonitor = this.LogManager.GetMonitor(packManifest.Name);
-                            IContentHelper packContentHelper = new ContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, packMonitor);
+                            GameContentHelper gameContentHelper = new(contentCore, packManifest.UniqueID, packManifest.Name, packMonitor);
+                            IModContentHelper packContentHelper = new ModContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, gameContentHelper.GetUnderlyingContentManager());
                             TranslationHelper packTranslationHelper = new(packManifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
 
                             ContentPack contentPack = new(packDirPath, packManifest, packContentHelper, packTranslationHelper, this.Toolkit.JsonHelper);
@@ -1867,13 +1869,15 @@ namespace StardewModdingAPI.Framework
                         IModEvents events = new ModEvents(mod, this.EventManager);
                         ICommandHelper commandHelper = new CommandHelper(mod, this.CommandManager);
                         IContentHelper contentHelper = new ContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor);
+                        GameContentHelper gameContentHelper = new(contentCore, manifest.UniqueID, mod.DisplayName, monitor);
+                        IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager());
                         IContentPackHelper contentPackHelper = new ContentPackHelper(manifest.UniqueID, new Lazy<IContentPack[]>(GetContentPacks), CreateFakeContentPack);
                         IDataHelper dataHelper = new DataHelper(manifest.UniqueID, mod.DirectoryPath, jsonHelper);
                         IReflectionHelper reflectionHelper = new ReflectionHelper(manifest.UniqueID, mod.DisplayName, this.Reflection);
                         IModRegistry modRegistryHelper = new ModRegistryHelper(manifest.UniqueID, this.ModRegistry, proxyFactory, monitor);
                         IMultiplayerHelper multiplayerHelper = new MultiplayerHelper(manifest.UniqueID, this.Multiplayer);
 
-                        modHelper = new ModHelper(manifest.UniqueID, mod.DirectoryPath, () => this.GetCurrentGameInstance().Input, events, contentHelper, contentPackHelper, commandHelper, dataHelper, modRegistryHelper, reflectionHelper, multiplayerHelper, translationHelper);
+                        modHelper = new ModHelper(manifest.UniqueID, mod.DirectoryPath, () => this.GetCurrentGameInstance().Input, events, contentHelper, gameContentHelper, modContentHelper, contentPackHelper, commandHelper, dataHelper, modRegistryHelper, reflectionHelper, multiplayerHelper, translationHelper);
                     }
 
                     // init mod
diff --git a/src/SMAPI/IAssetName.cs b/src/SMAPI/IAssetName.cs
index 89f02adf..c91da266 100644
--- a/src/SMAPI/IAssetName.cs
+++ b/src/SMAPI/IAssetName.cs
@@ -30,6 +30,11 @@ namespace StardewModdingAPI
         /// <param name="useBaseName">Whether to compare the given name with the <see cref="BaseName"/> (if true) or <see cref="Name"/> (if false). This has no effect on any locale included in the given <paramref name="assetName"/>.</param>
         bool IsEquivalentTo(string assetName, bool useBaseName = false);
 
+        /// <summary>Get whether the given asset name is equivalent, ignoring capitalization and formatting.</summary>
+        /// <param name="assetName">The asset name to compare this instance to.</param>
+        /// <param name="useBaseName">Whether to compare the given name with the <see cref="BaseName"/> (if true) or <see cref="Name"/> (if false).</param>
+        bool IsEquivalentTo(IAssetName assetName, bool useBaseName = false);
+
         /// <summary>Get whether the asset name starts with the given value, ignoring capitalization and formatting. This can be used with a trailing slash to test for an asset folder, like <c>Data/</c>.</summary>
         /// <param name="prefix">The prefix to match.</param>
         /// <param name="allowPartialWord">Whether to match if the prefix occurs mid-word, so <c>Data/AchievementsToIgnore</c> matches prefix <c>Data/Achievements</c>. If this is false, the prefix only matches if the asset name starts with the prefix followed by a non-alphanumeric character (including <c>.</c>, <c>/</c>, or <c>\\</c>) or the end of string.</param>
diff --git a/src/SMAPI/IContentHelper.cs b/src/SMAPI/IContentHelper.cs
index 1d36abff..48f6bfd8 100644
--- a/src/SMAPI/IContentHelper.cs
+++ b/src/SMAPI/IContentHelper.cs
@@ -10,17 +10,18 @@ using xTile;
 namespace StardewModdingAPI
 {
     /// <summary>Provides an API for loading content assets.</summary>
+    [Obsolete($"Use {nameof(IMod.Helper)}.{nameof(IModHelper.GameContent)} or {nameof(IMod.Helper)}.{nameof(IModHelper.ModContent)} instead. This interface will be removed in SMAPI 4.0.0.")]
     public interface IContentHelper : IModLinked
     {
         /*********
         ** Accessors
         *********/
         /// <summary>Interceptors which provide the initial versions of matching content assets.</summary>
-        [Obsolete($"Use {nameof(IMod.Helper)}.{nameof(IModHelper.Events)}.{nameof(IModEvents.Content)} instead. This interface will be removed in SMAPI 4.0.0.")]
+        [Obsolete($"Use {nameof(IMod.Helper)}.{nameof(IModHelper.Events)}.{nameof(IModEvents.Content)} instead. This property will be removed in SMAPI 4.0.0.")]
         IList<IAssetLoader> AssetLoaders { get; }
 
         /// <summary>Interceptors which edit matching content assets after they're loaded.</summary>
-        [Obsolete($"Use {nameof(IMod.Helper)}.{nameof(IModHelper.Events)}.{nameof(IModEvents.Content)} instead. This interface will be removed in SMAPI 4.0.0.")]
+        [Obsolete($"Use {nameof(IMod.Helper)}.{nameof(IModHelper.Events)}.{nameof(IModEvents.Content)} instead. This property will be removed in SMAPI 4.0.0.")]
         IList<IAssetEditor> AssetEditors { get; }
 
         /// <summary>The game's current locale code (like <c>pt-BR</c>).</summary>
@@ -33,11 +34,6 @@ namespace StardewModdingAPI
         /*********
         ** Public methods
         *********/
-        /// <summary>Parse a raw asset name.</summary>
-        /// <param name="rawName">The raw asset name to parse.</param>
-        /// <exception cref="ArgumentException">The <paramref name="rawName"/> is null or empty.</exception>
-        IAssetName ParseAssetName(string rawName);
-
         /// <summary>Load content from the game folder or mod folder (if not already cached), and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
         /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
         /// <param name="key">The asset key to fetch (if the <paramref name="source"/> is <see cref="ContentSource.GameContent"/>), or the local path to a content file relative to the mod folder.</param>
diff --git a/src/SMAPI/IContentPack.cs b/src/SMAPI/IContentPack.cs
index 9cc64dcd..3c66faff 100644
--- a/src/SMAPI/IContentPack.cs
+++ b/src/SMAPI/IContentPack.cs
@@ -20,6 +20,9 @@ namespace StardewModdingAPI
         /// <summary>Provides translations stored in the content pack's <c>i18n</c> folder. See <see cref="IModHelper.Translation"/> for more info.</summary>
         ITranslationHelper Translation { get; }
 
+        /// <summary>An API for loading content assets from the content pack's files.</summary>
+        IModContentHelper ModContent { get; }
+
 
         /*********
         ** Public methods
@@ -47,11 +50,13 @@ namespace StardewModdingAPI
         /// <param name="key">The relative file path within the content pack (case-insensitive).</param>
         /// <exception cref="ArgumentException">The <paramref name="key"/> is empty or contains invalid characters.</exception>
         /// <exception cref="ContentLoadException">The content asset couldn't be loaded (e.g. because it doesn't exist).</exception>
+        [Obsolete($"Use {nameof(IContentPack.ModContent)}.{nameof(IModContentHelper.Load)} instead. This method will be removed in SMAPI 4.0.0.")]
         T LoadAsset<T>(string key);
 
         /// <summary>Get the underlying key in the game's content cache for an asset. This can be used to load custom map tilesheets, but should be avoided when you can use the content API instead. This does not validate whether the asset exists.</summary>
         /// <param name="key">The relative file path within the content pack (case-insensitive).</param>
         /// <exception cref="ArgumentException">The <paramref name="key"/> is empty or contains invalid characters.</exception>
+        [Obsolete($"Use {nameof(IContentPack.ModContent)}.{nameof(IModContentHelper.GetInternalAssetName)} instead. This method will be removed in SMAPI 4.0.0.")]
         string GetActualAssetKey(string key);
     }
 }
diff --git a/src/SMAPI/IGameContentHelper.cs b/src/SMAPI/IGameContentHelper.cs
new file mode 100644
index 00000000..86bc3e0e
--- /dev/null
+++ b/src/SMAPI/IGameContentHelper.cs
@@ -0,0 +1,73 @@
+using System;
+using Microsoft.Xna.Framework.Content;
+using Microsoft.Xna.Framework.Graphics;
+using StardewModdingAPI.Events;
+using StardewValley;
+using xTile;
+
+namespace StardewModdingAPI
+{
+    /// <summary>Provides an API for loading content assets from the game's <c>Content</c> folder or via <see cref="IModEvents.Content"/>.</summary>
+    public interface IGameContentHelper : IModLinked
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The game's current locale code (like <c>pt-BR</c>).</summary>
+        string CurrentLocale { get; }
+
+        /// <summary>The game's current locale as an enum value.</summary>
+        LocalizedContentManager.LanguageCode CurrentLocaleConstant { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Parse a raw asset name.</summary>
+        /// <param name="rawName">The raw asset name to parse.</param>
+        /// <exception cref="ArgumentException">The <paramref name="rawName"/> is null or empty.</exception>
+        IAssetName ParseAssetName(string rawName);
+
+        /// <summary>Load content from the game folder or mod folder (if not already cached), and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
+        /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
+        /// <param name="assetName">The asset name to load.</param>
+        /// <exception cref="ArgumentException">The <paramref name="assetName"/> is empty or contains invalid characters.</exception>
+        /// <exception cref="ContentLoadException">The content asset couldn't be loaded (e.g. because it doesn't exist).</exception>
+        T Load<T>(string assetName);
+
+        /// <summary>Load content from the game folder or mod folder (if not already cached), and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
+        /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
+        /// <param name="assetName">The asset name to load.</param>
+        /// <exception cref="ArgumentException">The <paramref name="assetName"/> is empty or contains invalid characters.</exception>
+        /// <exception cref="ContentLoadException">The content asset couldn't be loaded (e.g. because it doesn't exist).</exception>
+        T Load<T>(IAssetName assetName);
+
+        /// <summary>Remove an asset from the content cache so it's reloaded on the next request. This will reload core game assets if needed, but references to the former asset will still show the previous content.</summary>
+        /// <param name="assetName">The asset key to invalidate in the content folder.</param>
+        /// <exception cref="ArgumentException">The <paramref name="assetName"/> is empty or contains invalid characters.</exception>
+        /// <returns>Returns whether the given asset key was cached.</returns>
+        bool InvalidateCache(string assetName);
+
+        /// <summary>Remove an asset from the content cache so it's reloaded on the next request. This will reload core game assets if needed, but references to the former asset will still show the previous content.</summary>
+        /// <param name="assetName">The asset key to invalidate in the content folder.</param>
+        /// <exception cref="ArgumentException">The <paramref name="assetName"/> is empty or contains invalid characters.</exception>
+        /// <returns>Returns whether the given asset key was cached.</returns>
+        bool InvalidateCache(IAssetName assetName);
+
+        /// <summary>Remove all assets of the given type from the cache so they're reloaded on the next request. <b>This can be a very expensive operation and should only be used in very specific cases.</b> This will reload core game assets if needed, but references to the former assets will still show the previous content.</summary>
+        /// <typeparam name="T">The asset type to remove from the cache.</typeparam>
+        /// <returns>Returns whether any assets were invalidated.</returns>
+        bool InvalidateCache<T>();
+
+        /// <summary>Remove matching assets from the content cache so they're reloaded on the next request. This will reload core game assets if needed, but references to the former asset will still show the previous content.</summary>
+        /// <param name="predicate">A predicate matching the assets to invalidate.</param>
+        /// <returns>Returns whether any cache entries were invalidated.</returns>
+        bool InvalidateCache(Func<IAssetInfo, bool> predicate);
+
+        /// <summary>Get a patch helper for arbitrary data.</summary>
+        /// <typeparam name="T">The data type.</typeparam>
+        /// <param name="data">The asset data.</param>
+        /// <param name="assetName">The asset name. This is only used for tracking purposes and has no effect on the patch helper.</param>
+        IAssetData GetPatchHelper<T>(T data, string assetName = null);
+    }
+}
diff --git a/src/SMAPI/IModContentHelper.cs b/src/SMAPI/IModContentHelper.cs
new file mode 100644
index 00000000..e3431365
--- /dev/null
+++ b/src/SMAPI/IModContentHelper.cs
@@ -0,0 +1,32 @@
+using System;
+using Microsoft.Xna.Framework.Content;
+using Microsoft.Xna.Framework.Graphics;
+using xTile;
+
+namespace StardewModdingAPI
+{
+    /// <summary>Provides an API for loading content assets from the current mod's folder.</summary>
+    public interface IModContentHelper : IModLinked
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Load content from the mod folder and return it. When loading a <c>.png</c> file, this must be called outside the game's draw loop.</summary>
+        /// <typeparam name="T">The expected data type. The main supported types are <see cref="Map"/>, <see cref="Texture2D"/>, dictionaries, and lists; other types may be supported by the game's content pipeline.</typeparam>
+        /// <param name="relativePath">The local path to a content file relative to the mod folder.</param>
+        /// <exception cref="ArgumentException">The <paramref name="relativePath"/> is empty or contains invalid characters.</exception>
+        /// <exception cref="ContentLoadException">The content asset couldn't be loaded (e.g. because it doesn't exist).</exception>
+        T Load<T>(string relativePath);
+
+        /// <summary>Get the internal asset name which allows loading a mod file through any of the game's content managers. This can be used when passing asset names directly to the game (e.g. for map tilesheets), but should be avoided if you can use <see cref="Load{T}"/> instead. This does not validate whether the asset exists.</summary>
+        /// <param name="relativePath">The local path to a content file relative to the mod folder.</param>
+        /// <exception cref="ArgumentException">The <paramref name="relativePath"/> is empty or contains invalid characters.</exception>
+        IAssetName GetInternalAssetName(string relativePath);
+
+        /// <summary>Get a patch helper for arbitrary data.</summary>
+        /// <typeparam name="T">The data type.</typeparam>
+        /// <param name="data">The asset data.</param>
+        /// <param name="relativePath">The local path to the content file being edited relative to the mod folder. This is only used for tracking purposes and has no effect on the patch helper.</param>
+        IAssetData GetPatchHelper<T>(T data, string relativePath = null);
+    }
+}
diff --git a/src/SMAPI/IModHelper.cs b/src/SMAPI/IModHelper.cs
index cd746e06..15e4ed8d 100644
--- a/src/SMAPI/IModHelper.cs
+++ b/src/SMAPI/IModHelper.cs
@@ -1,3 +1,4 @@
+using System;
 using StardewModdingAPI.Events;
 
 namespace StardewModdingAPI
@@ -17,13 +18,22 @@ namespace StardewModdingAPI
         /// <summary>An API for managing console commands.</summary>
         ICommandHelper ConsoleCommands { get; }
 
+        /// <summary>An API for loading content assets from the game's <c>Content</c> folder or using the <see cref="IModEvents.Content"/> events.</summary>
+        IGameContentHelper GameContent { get; }
+
+        /// <summary>An API for loading content assets from your mod's files.</summary>
+        /// <remarks>This API is intended for reading content assets from the mod files (like game data, images, etc); see also <see cref="Data"/> which is intended for persisting internal mod data.</remarks>
+        IModContentHelper ModContent { get; }
+
         /// <summary>An API for loading content assets.</summary>
+        [Obsolete($"Use {nameof(IGameContentHelper)} or {nameof(IModContentHelper)} instead.")]
         IContentHelper Content { get; }
 
         /// <summary>An API for managing content packs.</summary>
         IContentPackHelper ContentPacks { get; }
 
         /// <summary>An API for reading and writing persistent mod data.</summary>
+        /// <remarks>This API is intended for persisting internal mod data; see also <see cref="ModContent"/> which is intended for reading content assets (like game data, images, etc).</remarks>
         IDataHelper Data { get; }
 
         /// <summary>An API for checking and changing input state.</summary>
-- 
cgit 


From 4e2d7f2550b05e410735f51beac76ed040178cf4 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 1 Apr 2022 23:42:37 -0400
Subject: make mod file paths case-insensitive in all SMAPI APIs

---
 docs/release-notes.md                              |  15 ++-
 src/SMAPI/Framework/ContentCoordinator.cs          |  22 +++-
 .../Framework/ContentManagers/ModContentManager.cs |  14 ++-
 src/SMAPI/Framework/ContentPack.cs                 |  38 ++-----
 src/SMAPI/Framework/ModHelpers/ModContentHelper.cs |  16 ++-
 src/SMAPI/Framework/SCore.cs                       |  15 ++-
 src/SMAPI/Utilities/CaseInsensitivePathCache.cs    | 124 +++++++++++++++++++++
 7 files changed, 200 insertions(+), 44 deletions(-)
 create mode 100644 src/SMAPI/Utilities/CaseInsensitivePathCache.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2e09240c..6d505d40 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -8,6 +8,7 @@
   * Improved Linux/macOS [command-line arguments](technical/smapi.md#command-line-arguments):
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
+  * SMAPI now fixes many case-sensitive mod file path issues automatically.
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
 
 * For the Console Commands mod:
@@ -15,12 +16,14 @@
   * Fixed `set_farm_type` not updating warps.
 
 * For mod authors:
-  * **Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.**  
-    _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
-  * **Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.**
-  * **Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying** (thanks to Shockah!).  
-    _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
-  * **Deprecation warning:** The upcoming SMAPI 4.0 will remove deprecated APIs and break mods which haven't updated yet.  
+  * **Major changes as part of the upcoming SMAPI 4.0.0:**
+    * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
+      _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
+    * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
+    * Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
+      _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
+    * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
+    * **Deprecation warning:** The upcoming SMAPI 4.0 will remove deprecated APIs and break mods which haven't updated yet.  
     _See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0) for help updating your mod code. You can update your mod code now, there's no need to wait for the 4.0.0 release (which will happen in at least three months, and possibly later if needed to update open-source mods)._
   * Added `IContentPack.ModContent` property.
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 8483d45d..cd1de4a8 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -15,7 +15,7 @@ using StardewModdingAPI.Framework.Utilities;
 using StardewModdingAPI.Internal;
 using StardewModdingAPI.Metadata;
 using StardewModdingAPI.Toolkit.Serialization;
-using StardewModdingAPI.Toolkit.Utilities;
+using StardewModdingAPI.Utilities;
 using StardewValley;
 using StardewValley.GameData;
 using xTile;
@@ -80,6 +80,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>The cached asset load/edit operations to apply, indexed by asset name.</summary>
         private readonly TickCacheDictionary<IAssetName, AssetOperationGroup[]> AssetOperationsByKey = new();
 
+        /// <summary>The previously created case-insensitive path caches by root path.</summary>
+        private readonly Dictionary<string, CaseInsensitivePathCache> CaseInsensitivePathCaches = new(StringComparer.OrdinalIgnoreCase);
+
 
         /*********
         ** Accessors
@@ -91,9 +94,11 @@ namespace StardewModdingAPI.Framework
         public LocalizedContentManager.LanguageCode Language => this.MainContentManager.Language;
 
         /// <summary>Interceptors which provide the initial versions of matching assets.</summary>
+        [Obsolete]
         public IList<ModLinked<IAssetLoader>> Loaders { get; } = new List<ModLinked<IAssetLoader>>();
 
         /// <summary>Interceptors which edit matching assets after they're loaded.</summary>
+        [Obsolete]
         public IList<ModLinked<IAssetEditor>> Editors { get; } = new List<ModLinked<IAssetEditor>>();
 
         /// <summary>The absolute path to the <see cref="ContentManager.RootDirectory"/>.</summary>
@@ -205,7 +210,8 @@ namespace StardewModdingAPI.Framework
                     reflection: this.Reflection,
                     jsonHelper: this.JsonHelper,
                     onDisposing: this.OnDisposing,
-                    aggressiveMemoryOptimizations: this.AggressiveMemoryOptimizations
+                    aggressiveMemoryOptimizations: this.AggressiveMemoryOptimizations,
+                    relativePathCache: this.GetCaseInsensitivePathCache(rootDirectory)
                 );
                 this.ContentManagers.Add(manager);
                 return manager;
@@ -477,6 +483,18 @@ namespace StardewModdingAPI.Framework
             });
         }
 
+        /// <summary>Get a dictionary of relative paths within a root path, for case-insensitive file lookups.</summary>
+        /// <param name="rootPath">The root path to scan.</param>
+        public CaseInsensitivePathCache GetCaseInsensitivePathCache(string rootPath)
+        {
+            rootPath = PathUtilities.NormalizePath(rootPath);
+
+            if (!this.CaseInsensitivePathCaches.TryGetValue(rootPath, out CaseInsensitivePathCache cache))
+                this.CaseInsensitivePathCaches[rootPath] = cache = new CaseInsensitivePathCache(rootPath);
+
+            return cache;
+        }
+
         /// <summary>Get the tilesheet ID order used by the unmodified version of a map asset.</summary>
         /// <param name="assetName">The asset path relative to the loader root directory, not including the <c>.xnb</c> extension.</param>
         public TilesheetReference[] GetVanillaTilesheetIds(string assetName)
diff --git a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
index 9ed989da..a451fd7c 100644
--- a/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/ModContentManager.cs
@@ -9,7 +9,7 @@ using Microsoft.Xna.Framework.Graphics;
 using StardewModdingAPI.Framework.Exceptions;
 using StardewModdingAPI.Framework.Reflection;
 using StardewModdingAPI.Toolkit.Serialization;
-using StardewModdingAPI.Toolkit.Utilities;
+using StardewModdingAPI.Utilities;
 using StardewValley;
 using xTile;
 using xTile.Format;
@@ -32,6 +32,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>The game content manager used for map tilesheets not provided by the mod.</summary>
         private readonly IContentManager GameContentManager;
 
+        /// <summary>A case-insensitive lookup of relative paths within the <see cref="ContentManager.RootDirectory"/>.</summary>
+        private readonly CaseInsensitivePathCache RelativePathCache;
+
         /// <summary>If a map tilesheet's image source has no file extensions, the file extensions to check for in the local mod folder.</summary>
         private readonly string[] LocalTilesheetExtensions = { ".png", ".xnb" };
 
@@ -52,10 +55,12 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
         /// <param name="onDisposing">A callback to invoke when the content manager is being disposed.</param>
         /// <param name="aggressiveMemoryOptimizations">Whether to enable more aggressive memory optimizations.</param>
-        public ModContentManager(string name, IContentManager gameContentManager, IServiceProvider serviceProvider, string modName, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action<BaseContentManager> onDisposing, bool aggressiveMemoryOptimizations)
+        /// <param name="relativePathCache">A case-insensitive lookup of relative paths within the <paramref name="rootDirectory"/>.</param>
+        public ModContentManager(string name, IContentManager gameContentManager, IServiceProvider serviceProvider, string modName, string rootDirectory, CultureInfo currentCulture, ContentCoordinator coordinator, IMonitor monitor, Reflector reflection, JsonHelper jsonHelper, Action<BaseContentManager> onDisposing, bool aggressiveMemoryOptimizations, CaseInsensitivePathCache relativePathCache)
             : base(name, serviceProvider, rootDirectory, currentCulture, coordinator, monitor, reflection, onDisposing, isNamespaced: true, aggressiveMemoryOptimizations: aggressiveMemoryOptimizations)
         {
             this.GameContentManager = gameContentManager;
+            this.RelativePathCache = relativePathCache;
             this.JsonHelper = jsonHelper;
             this.ModName = modName;
 
@@ -198,7 +203,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         public IAssetName GetInternalAssetKey(string key)
         {
             FileInfo file = this.GetModFile(key);
-            string relativePath = PathUtilities.GetRelativePath(this.RootDirectory, file.FullName);
+            string relativePath = Path.GetRelativePath(this.RootDirectory, file.FullName);
             string internalKey = Path.Combine(this.Name, relativePath);
 
             return this.Coordinator.ParseAssetName(internalKey, allowLocales: false);
@@ -212,6 +217,9 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="path">The asset path relative to the content folder.</param>
         private FileInfo GetModFile(string path)
         {
+            // map to case-insensitive path if needed
+            path = this.RelativePathCache.GetFilePath(path);
+
             // try exact match
             FileInfo file = new(Path.Combine(this.FullRootDirectory, path));
 
diff --git a/src/SMAPI/Framework/ContentPack.cs b/src/SMAPI/Framework/ContentPack.cs
index 3920354e..e02ef88b 100644
--- a/src/SMAPI/Framework/ContentPack.cs
+++ b/src/SMAPI/Framework/ContentPack.cs
@@ -1,9 +1,8 @@
 using System;
-using System.Collections.Generic;
 using System.IO;
 using StardewModdingAPI.Framework.ModHelpers;
 using StardewModdingAPI.Toolkit.Serialization;
-using StardewModdingAPI.Toolkit.Utilities;
+using StardewModdingAPI.Utilities;
 
 namespace StardewModdingAPI.Framework
 {
@@ -16,8 +15,8 @@ namespace StardewModdingAPI.Framework
         /// <summary>Encapsulates SMAPI's JSON file parsing.</summary>
         private readonly JsonHelper JsonHelper;
 
-        /// <summary>A cache of case-insensitive => exact relative paths within the content pack, for case-insensitive file lookups on Linux/macOS.</summary>
-        private readonly IDictionary<string, string> RelativePaths = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        /// <summary>A case-insensitive lookup of relative paths within the <see cref="DirectoryPath"/>.</summary>
+        private readonly CaseInsensitivePathCache RelativePathCache;
 
 
         /*********
@@ -48,19 +47,15 @@ namespace StardewModdingAPI.Framework
         /// <param name="content">Provides an API for loading content assets from the content pack's folder.</param>
         /// <param name="translation">Provides translations stored in the content pack's <c>i18n</c> folder.</param>
         /// <param name="jsonHelper">Encapsulates SMAPI's JSON file parsing.</param>
-        public ContentPack(string directoryPath, IManifest manifest, IModContentHelper content, TranslationHelper translation, JsonHelper jsonHelper)
+        /// <param name="relativePathCache">A case-insensitive lookup of relative paths within the <paramref name="directoryPath"/>.</param>
+        public ContentPack(string directoryPath, IManifest manifest, IModContentHelper content, TranslationHelper translation, JsonHelper jsonHelper, CaseInsensitivePathCache relativePathCache)
         {
             this.DirectoryPath = directoryPath;
             this.Manifest = manifest;
             this.ModContent = content;
             this.TranslationImpl = translation;
             this.JsonHelper = jsonHelper;
-
-            foreach (string path in Directory.EnumerateFiles(this.DirectoryPath, "*", SearchOption.AllDirectories))
-            {
-                string relativePath = path.Substring(this.DirectoryPath.Length + 1);
-                this.RelativePaths[relativePath] = relativePath;
-            }
+            this.RelativePathCache = relativePathCache;
         }
 
         /// <inheritdoc />
@@ -90,8 +85,7 @@ namespace StardewModdingAPI.Framework
             FileInfo file = this.GetFile(path, out path);
             this.JsonHelper.WriteJsonFile(file.FullName, data);
 
-            if (!this.RelativePaths.ContainsKey(path))
-                this.RelativePaths[path] = path;
+            this.RelativePathCache.Add(path);
         }
 
         /// <inheritdoc />
@@ -112,18 +106,6 @@ namespace StardewModdingAPI.Framework
         /*********
         ** Private methods
         *********/
-        /// <summary>Get the real relative path from a case-insensitive path.</summary>
-        /// <param name="relativePath">The normalized relative path.</param>
-        private string GetCaseInsensitiveRelativePath(string relativePath)
-        {
-            if (!PathUtilities.IsSafeRelativePath(relativePath))
-                throw new InvalidOperationException($"You must call {nameof(IContentPack)} methods with a relative path.");
-
-            return !string.IsNullOrWhiteSpace(relativePath) && this.RelativePaths.TryGetValue(relativePath, out string caseInsensitivePath)
-                ? caseInsensitivePath
-                : relativePath;
-        }
-
         /// <summary>Get the underlying file info.</summary>
         /// <param name="relativePath">The normalized file path relative to the content pack directory.</param>
         private FileInfo GetFile(string relativePath)
@@ -136,7 +118,11 @@ namespace StardewModdingAPI.Framework
         /// <param name="actualRelativePath">The relative path after case-insensitive matching.</param>
         private FileInfo GetFile(string relativePath, out string actualRelativePath)
         {
-            actualRelativePath = this.GetCaseInsensitiveRelativePath(relativePath);
+            if (!PathUtilities.IsSafeRelativePath(relativePath))
+                throw new InvalidOperationException($"You must call {nameof(IContentPack)} methods with a relative path.");
+
+            actualRelativePath = this.RelativePathCache.GetFilePath(relativePath);
+
             return new FileInfo(Path.Combine(this.DirectoryPath, actualRelativePath));
         }
     }
diff --git a/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
index 2379583c..7468cda1 100644
--- a/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
@@ -1,7 +1,9 @@
 using System;
+using Microsoft.Xna.Framework.Content;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Exceptions;
+using StardewModdingAPI.Utilities;
 
 namespace StardewModdingAPI.Framework.ModHelpers
 {
@@ -20,6 +22,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <summary>The friendly mod name for use in errors.</summary>
         private readonly string ModName;
 
+        /// <summary>A case-insensitive lookup of relative paths within the <see cref="ContentManager.RootDirectory"/>.</summary>
+        private readonly CaseInsensitivePathCache RelativePathCache;
+
 
         /*********
         ** Public methods
@@ -30,7 +35,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="modID">The unique ID of the relevant mod.</param>
         /// <param name="modName">The friendly mod name for use in errors.</param>
         /// <param name="gameContentManager">The game content manager used for map tilesheets not provided by the mod.</param>
-        public ModContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IContentManager gameContentManager)
+        /// <param name="relativePathCache">A case-insensitive lookup of relative paths within the <paramref name="relativePathCache"/>.</param>
+        public ModContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IContentManager gameContentManager, CaseInsensitivePathCache relativePathCache)
             : base(modID)
         {
             string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
@@ -38,11 +44,14 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.ContentCore = contentCore;
             this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, modName, modFolderPath, gameContentManager);
             this.ModName = modName;
+            this.RelativePathCache = relativePathCache;
         }
 
         /// <inheritdoc />
         public T Load<T>(string relativePath)
         {
+            relativePath = this.RelativePathCache.GetAssetName(relativePath);
+
             IAssetName assetName = this.ContentCore.ParseAssetName(relativePath, allowLocales: false);
 
             try
@@ -58,6 +67,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <inheritdoc />
         public IAssetName GetInternalAssetName(string relativePath)
         {
+            relativePath = this.RelativePathCache.GetAssetName(relativePath);
             return this.ModContentManager.GetInternalAssetKey(relativePath);
         }
 
@@ -67,7 +77,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
             if (data == null)
                 throw new ArgumentNullException(nameof(data), "Can't get a patch helper for a null value.");
 
-            relativePath ??= $"temp/{Guid.NewGuid():N}";
+            relativePath = relativePath != null
+                ? this.RelativePathCache.GetAssetName(relativePath)
+                : $"temp/{Guid.NewGuid():N}";
 
             return new AssetDataForObject(this.ContentCore.GetLocale(), this.ContentCore.ParseAssetName(relativePath, allowLocales: false), data, key => this.ContentCore.ParseAssetName(key, allowLocales: false).Name);
         }
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index b4aa3595..7fd5bcd3 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1775,10 +1775,11 @@ namespace StardewModdingAPI.Framework
             {
                 IManifest manifest = mod.Manifest;
                 IMonitor monitor = this.LogManager.GetMonitor(mod.DisplayName);
+                CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath);
                 GameContentHelper gameContentHelper = new(this.ContentCore, manifest.UniqueID, mod.DisplayName, monitor);
-                IModContentHelper modContentHelper = new ModContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager());
+                IModContentHelper modContentHelper = new ModContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
                 TranslationHelper translationHelper = new(manifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
-                IContentPack contentPack = new ContentPack(mod.DirectoryPath, manifest, modContentHelper, translationHelper, jsonHelper);
+                IContentPack contentPack = new ContentPack(mod.DirectoryPath, manifest, modContentHelper, translationHelper, jsonHelper, relativePathCache);
                 mod.SetMod(contentPack, monitor, translationHelper);
                 this.ModRegistry.Add(mod);
 
@@ -1856,11 +1857,14 @@ namespace StardewModdingAPI.Framework
                         IContentPack CreateFakeContentPack(string packDirPath, IManifest packManifest)
                         {
                             IMonitor packMonitor = this.LogManager.GetMonitor(packManifest.Name);
+
+                            CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(packDirPath);
+
                             GameContentHelper gameContentHelper = new(contentCore, packManifest.UniqueID, packManifest.Name, packMonitor);
-                            IModContentHelper packContentHelper = new ModContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, gameContentHelper.GetUnderlyingContentManager());
+                            IModContentHelper packContentHelper = new ModContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
                             TranslationHelper packTranslationHelper = new(packManifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
 
-                            ContentPack contentPack = new(packDirPath, packManifest, packContentHelper, packTranslationHelper, this.Toolkit.JsonHelper);
+                            ContentPack contentPack = new(packDirPath, packManifest, packContentHelper, packTranslationHelper, this.Toolkit.JsonHelper, relativePathCache);
                             this.ReloadTranslationsForTemporaryContentPack(mod, contentPack);
                             mod.FakeContentPacks.Add(new WeakReference<ContentPack>(contentPack));
                             return contentPack;
@@ -1868,9 +1872,10 @@ namespace StardewModdingAPI.Framework
 
                         IModEvents events = new ModEvents(mod, this.EventManager);
                         ICommandHelper commandHelper = new CommandHelper(mod, this.CommandManager);
+                        CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath);
                         IContentHelper contentHelper = new ContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor);
                         GameContentHelper gameContentHelper = new(contentCore, manifest.UniqueID, mod.DisplayName, monitor);
-                        IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager());
+                        IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
                         IContentPackHelper contentPackHelper = new ContentPackHelper(manifest.UniqueID, new Lazy<IContentPack[]>(GetContentPacks), CreateFakeContentPack);
                         IDataHelper dataHelper = new DataHelper(manifest.UniqueID, mod.DirectoryPath, jsonHelper);
                         IReflectionHelper reflectionHelper = new ReflectionHelper(manifest.UniqueID, mod.DisplayName, this.Reflection);
diff --git a/src/SMAPI/Utilities/CaseInsensitivePathCache.cs b/src/SMAPI/Utilities/CaseInsensitivePathCache.cs
new file mode 100644
index 00000000..1d947b53
--- /dev/null
+++ b/src/SMAPI/Utilities/CaseInsensitivePathCache.cs
@@ -0,0 +1,124 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+
+namespace StardewModdingAPI.Utilities
+{
+    /// <summary>Provides an API for case-insensitive relative path lookups within a root directory.</summary>
+    internal class CaseInsensitivePathCache
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The root directory path for relative paths.</summary>
+        private readonly string RootPath;
+
+        /// <summary>A case-insensitive lookup of file paths within the <see cref="RootPath"/>. Each path is listed in both file path and asset name format, so it's usable in both contexts without needing to re-parse paths.</summary>
+        private readonly Lazy<Dictionary<string, string>> RelativePathCache;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="rootPath">The root directory path for relative paths.</param>
+        public CaseInsensitivePathCache(string rootPath)
+        {
+            this.RootPath = rootPath;
+            this.RelativePathCache = new(this.GetRelativePathCache);
+        }
+
+        /// <summary>Get the exact capitalization for a given relative file path.</summary>
+        /// <param name="relativePath">The relative path.</param>
+        /// <remarks>Returns the resolved path in file path format, else the normalized <paramref name="relativePath"/>.</remarks>
+        public string GetFilePath(string relativePath)
+        {
+            return this.GetImpl(PathUtilities.NormalizePath(relativePath));
+        }
+
+        /// <summary>Get the exact capitalization for a given asset name.</summary>
+        /// <param name="relativePath">The relative path.</param>
+        /// <remarks>Returns the resolved path in asset name format, else the normalized <paramref name="relativePath"/>.</remarks>
+        public string GetAssetName(string relativePath)
+        {
+            return this.GetImpl(PathUtilities.NormalizeAssetName(relativePath));
+        }
+
+        /// <summary>Add a relative path that was just created by a SMAPI API.</summary>
+        /// <param name="relativePath">The relative path. This must already be normalized in asset name or file path format.</param>
+        public void Add(string relativePath)
+        {
+            // skip if cache isn't created yet (no need to add files manually in that case)
+            if (!this.RelativePathCache.IsValueCreated)
+                return;
+
+            // skip if already cached
+            if (this.RelativePathCache.Value.ContainsKey(relativePath))
+                return;
+
+            // make sure path exists
+            relativePath = PathUtilities.NormalizePath(relativePath);
+            if (!File.Exists(Path.Combine(this.RootPath, relativePath)))
+                throw new InvalidOperationException($"Can't add relative path '{relativePath}' to the case-insensitive cache for '{this.RootPath}' because that file doesn't exist.");
+
+            // cache path
+            this.CacheRawPath(this.RelativePathCache.Value, relativePath);
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get the exact capitalization for a given relative path.</summary>
+        /// <param name="relativePath">The relative path. This must already be normalized into asset name or file path format (i.e. using <see cref="PathUtilities.NormalizeAssetName"/> or <see cref="PathUtilities.NormalizePath"/> respectively).</param>
+        /// <remarks>Returns the resolved path in the same format if found, else returns the path as-is.</remarks>
+        private string GetImpl(string relativePath)
+        {
+            // invalid path
+            if (string.IsNullOrWhiteSpace(relativePath))
+                return relativePath;
+
+            // already cached
+            if (this.RelativePathCache.Value.TryGetValue(relativePath, out string resolved))
+                return resolved;
+
+            // file exists but isn't cached for some reason
+            // cache it now so any later references to it are case-insensitive
+            if (File.Exists(Path.Combine(this.RootPath, relativePath)))
+            {
+                this.CacheRawPath(this.RelativePathCache.Value, relativePath);
+                return relativePath;
+            }
+
+            // no such file, keep capitalization as-is
+            return relativePath;
+        }
+
+        /// <summary>Get a case-insensitive lookup of file paths (see <see cref="RelativePathCache"/>).</summary>
+        private Dictionary<string, string> GetRelativePathCache()
+        {
+            Dictionary<string, string> cache = new(StringComparer.OrdinalIgnoreCase);
+
+            foreach (string path in Directory.EnumerateFiles(this.RootPath, "*", SearchOption.AllDirectories))
+            {
+                string relativePath = path.Substring(this.RootPath.Length + 1);
+
+                this.CacheRawPath(cache, relativePath);
+            }
+
+            return cache;
+        }
+
+        /// <summary>Add a raw relative path to the cache.</summary>
+        /// <param name="cache">The cache to update.</param>
+        /// <param name="relativePath">The relative path to cache, with its exact filesystem capitalization.</param>
+        private void CacheRawPath(IDictionary<string, string> cache, string relativePath)
+        {
+            string filePath = PathUtilities.NormalizePath(relativePath);
+            string assetName = PathUtilities.NormalizeAssetName(relativePath);
+
+            cache[filePath] = filePath;
+            cache[assetName] = assetName;
+        }
+    }
+}
-- 
cgit 


From 215a863945396d6b733654f1ba60bf04dc4db85a Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Wed, 6 Apr 2022 18:34:58 -0400
Subject: drop update checks for Stardew64Installer

---
 docs/release-notes.md                 |  1 +
 src/SMAPI/Constants.cs                | 15 ---------------
 src/SMAPI/Framework/Models/SConfig.cs |  3 ---
 src/SMAPI/Framework/SCore.cs          | 33 ---------------------------------
 src/SMAPI/SMAPI.config.json           |  5 -----
 5 files changed, 1 insertion(+), 56 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 6d505d40..732cd530 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -9,6 +9,7 @@
     * Added `--use-current-shell` to avoid opening a separate terminal window.
     * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
   * SMAPI now fixes many case-sensitive mod file path issues automatically.
+  * Dropped update checks for the unofficial 64-bit patcher (obsolete since SMAPI 3.12.6).
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
 
 * For the Console Commands mod:
diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index 6b9e9b05..2fac8c94 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -291,21 +291,6 @@ namespace StardewModdingAPI
             return new PlatformAssemblyMap(targetPlatform, removeAssemblyReferences.ToArray(), targetAssemblies.ToArray());
         }
 
-        /// <summary>Get whether the game assembly was patched by Stardew64Installer.</summary>
-        /// <param name="version">The version of Stardew64Installer which was applied to the game assembly, if any.</param>
-        internal static bool IsPatchedByStardew64Installer(out ISemanticVersion version)
-        {
-            PropertyInfo property = typeof(Game1).GetProperty("Stardew64InstallerVersion");
-            if (property == null)
-            {
-                version = null;
-                return false;
-            }
-
-            version = new SemanticVersion((string)property.GetValue(null));
-            return true;
-        }
-
 
         /*********
         ** Private methods
diff --git a/src/SMAPI/Framework/Models/SConfig.cs b/src/SMAPI/Framework/Models/SConfig.cs
index 35180df2..1e78f316 100644
--- a/src/SMAPI/Framework/Models/SConfig.cs
+++ b/src/SMAPI/Framework/Models/SConfig.cs
@@ -52,9 +52,6 @@ namespace StardewModdingAPI.Framework.Models
         /// <summary>SMAPI's GitHub project name, used to perform update checks.</summary>
         public string GitHubProjectName { get; set; }
 
-        /// <summary>Stardew64Installer's GitHub project name, used to perform update checks.</summary>
-        public string Stardew64InstallerGitHubProjectName { get; set; }
-
         /// <summary>The base URL for SMAPI's web API, used to perform update checks.</summary>
         public string WebApiBaseUrl { get; set; }
 
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index cc531de9..b471c383 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1450,39 +1450,6 @@ namespace StardewModdingAPI.Framework
                         this.LogManager.WriteUpdateMarker(updateFound.ToString(), updateUrl);
                 }
 
-                // check Stardew64Installer version
-                if (Constants.IsPatchedByStardew64Installer(out ISemanticVersion patchedByVersion))
-                {
-                    try
-                    {
-                        // fetch update check
-                        ModEntryModel response = client.GetModInfo(new[] { new ModSearchEntryModel("Steviegt6.Stardew64Installer", patchedByVersion, new[] { $"GitHub:{this.Settings.Stardew64InstallerGitHubProjectName}" }) }, apiVersion: Constants.ApiVersion, gameVersion: Constants.GameVersion, platform: Constants.Platform).Single().Value;
-                        ISemanticVersion updateFound = response.SuggestedUpdate?.Version;
-                        string updateUrl = response.SuggestedUpdate?.Url ?? Constants.HomePageUrl;
-
-                        // log message
-                        if (updateFound != null)
-                            this.Monitor.Log($"You can update Stardew64Installer to {updateFound}: {updateUrl}", LogLevel.Alert);
-                        else
-                            this.Monitor.Log("   Stardew64Installer okay.");
-
-                        // show errors
-                        if (response.Errors.Any())
-                        {
-                            this.Monitor.Log("Couldn't check for a new version of Stardew64Installer. This won't affect your game, but you may not be notified of new versions if this keeps happening.", LogLevel.Warn);
-                            this.Monitor.Log($"Error: {string.Join("\n", response.Errors)}");
-                        }
-                    }
-                    catch (Exception ex)
-                    {
-                        this.Monitor.Log("Couldn't check for a new version of Stardew64Installer. This won't affect your game, but you won't be notified of new versions if this keeps happening.", LogLevel.Warn);
-                        this.Monitor.Log(ex is WebException && ex.InnerException == null
-                            ? $"Error: {ex.Message}"
-                            : $"Error: {ex.GetLogSummary()}"
-                        );
-                    }
-                }
-
                 // check mod versions
                 if (mods.Any())
                 {
diff --git a/src/SMAPI/SMAPI.config.json b/src/SMAPI/SMAPI.config.json
index e62c8880..49056e83 100644
--- a/src/SMAPI/SMAPI.config.json
+++ b/src/SMAPI/SMAPI.config.json
@@ -69,11 +69,6 @@ copy all the settings, or you may cause bugs due to overridden changes in future
      */
     "GitHubProjectName": "Pathoschild/SMAPI",
 
-    /**
-     * Stardew64Installer's GitHub project name, used to perform update checks.
-     */
-    "Stardew64InstallerGitHubProjectName": "Steviegt6/Stardew64Installer",
-
     /**
      * The base URL for SMAPI's web API, used to perform update checks.
      */
-- 
cgit 


From b4e979cc991a0c2a45ad986210108edd2d43e43d Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Wed, 6 Apr 2022 22:46:19 -0400
Subject: fix all warnings to simplify migration to nullable annotations (#837)

---
 docs/technical/mod-package.md                      |  1 +
 .../Framework/DiagnosticVerifier.Helper.cs         | 24 ++++++++---------
 .../Framework/DiagnosticVerifier.cs                | 30 +++++++++++-----------
 .../AnalyzerReleases.Shipped.md                    |  7 +++++
 .../SMAPI.ModBuildConfig.Analyzer.csproj           |  4 +++
 .../SMAPI.ModBuildConfig.csproj                    |  1 +
 src/SMAPI.Tests/Core/AssetNameTests.cs             |  1 -
 src/SMAPI/Framework/ContentCoordinator.cs          |  2 ++
 .../Framework/ContentManagers/IContentManager.cs   |  1 +
 src/SMAPI/Framework/ModHelpers/ModHelper.cs        | 10 +++++++-
 src/SMAPI/Framework/SCore.cs                       |  4 +++
 11 files changed, 56 insertions(+), 29 deletions(-)
 create mode 100644 src/SMAPI.ModBuildConfig.Analyzer/AnalyzerReleases.Shipped.md

(limited to 'docs')

diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
index 5e408168..4c31f69b 100644
--- a/docs/technical/mod-package.md
+++ b/docs/technical/mod-package.md
@@ -414,6 +414,7 @@ when you compile it.
 ## Release notes
 ## Upcoming release
 * Added detection for Xbox app game folders.
+* Internal refactoring.
 
 ## 4.0.0
 Released 30 November 2021.
diff --git a/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.Helper.cs b/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.Helper.cs
index 8d72fea1..68a892a9 100644
--- a/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.Helper.cs
+++ b/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.Helper.cs
@@ -53,17 +53,17 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
         protected static Diagnostic[] GetSortedDiagnosticsFromDocuments(DiagnosticAnalyzer analyzer, Document[] documents)
         {
             var projects = new HashSet<Project>();
-            foreach (var document in documents)
+            foreach (Document document in documents)
             {
                 projects.Add(document.Project);
             }
 
             var diagnostics = new List<Diagnostic>();
-            foreach (var project in projects)
+            foreach (Project project in projects)
             {
-                var compilationWithAnalyzers = project.GetCompilationAsync().Result.WithAnalyzers(ImmutableArray.Create(analyzer));
+                CompilationWithAnalyzers compilationWithAnalyzers = project.GetCompilationAsync().Result.WithAnalyzers(ImmutableArray.Create(analyzer));
                 var diags = compilationWithAnalyzers.GetAnalyzerDiagnosticsAsync().Result;
-                foreach (var diag in diags)
+                foreach (Diagnostic diag in diags)
                 {
                     if (diag.Location == Location.None || diag.Location.IsInMetadata)
                     {
@@ -73,8 +73,8 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                     {
                         for (int i = 0; i < documents.Length; i++)
                         {
-                            var document = documents[i];
-                            var tree = document.GetSyntaxTreeAsync().Result;
+                            Document document = documents[i];
+                            SyntaxTree tree = document.GetSyntaxTreeAsync().Result;
                             if (tree == diag.Location.SourceTree)
                             {
                                 diagnostics.Add(diag);
@@ -115,7 +115,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                 throw new ArgumentException("Unsupported Language");
             }
 
-            var project = CreateProject(sources, language);
+            Project project = CreateProject(sources, language);
             var documents = project.Documents.ToArray();
 
             if (sources.Length != documents.Length)
@@ -148,9 +148,9 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
             string fileNamePrefix = DefaultFilePathPrefix;
             string fileExt = language == LanguageNames.CSharp ? CSharpDefaultFileExt : VisualBasicDefaultExt;
 
-            var projectId = ProjectId.CreateNewId(debugName: TestProjectName);
+            ProjectId projectId = ProjectId.CreateNewId(debugName: TestProjectName);
 
-            var solution = new AdhocWorkspace()
+            Solution solution = new AdhocWorkspace()
                 .CurrentSolution
                 .AddProject(projectId, TestProjectName, TestProjectName, language)
                 .AddMetadataReference(projectId, DiagnosticVerifier.SelfReference)
@@ -160,10 +160,10 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                 .AddMetadataReference(projectId, CodeAnalysisReference);
 
             int count = 0;
-            foreach (var source in sources)
+            foreach (string source in sources)
             {
-                var newFileName = fileNamePrefix + count + "." + fileExt;
-                var documentId = DocumentId.CreateNewId(projectId, debugName: newFileName);
+                string newFileName = fileNamePrefix + count + "." + fileExt;
+                DocumentId documentId = DocumentId.CreateNewId(projectId, debugName: newFileName);
                 solution = solution.AddDocument(documentId, newFileName, SourceText.From(source));
                 count++;
             }
diff --git a/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.cs b/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.cs
index 09d3a3f8..4170042d 100644
--- a/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.cs
+++ b/src/SMAPI.ModBuildConfig.Analyzer.Tests/Framework/DiagnosticVerifier.cs
@@ -43,7 +43,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
         /// <param name="expected"> DiagnosticResults that should appear after the analyzer is run on the source</param>
         protected void VerifyCSharpDiagnostic(string source, params DiagnosticResult[] expected)
         {
-            VerifyDiagnostics(new[] { source }, LanguageNames.CSharp, GetCSharpDiagnosticAnalyzer(), expected);
+            this.VerifyDiagnostics(new[] { source }, LanguageNames.CSharp, this.GetCSharpDiagnosticAnalyzer(), expected);
         }
 
         /// <summary>
@@ -54,7 +54,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
         /// <param name="expected">DiagnosticResults that should appear after the analyzer is run on the sources</param>
         protected void VerifyCSharpDiagnostic(string[] sources, params DiagnosticResult[] expected)
         {
-            VerifyDiagnostics(sources, LanguageNames.CSharp, GetCSharpDiagnosticAnalyzer(), expected);
+            this.VerifyDiagnostics(sources, LanguageNames.CSharp, this.GetCSharpDiagnosticAnalyzer(), expected);
         }
 
         /// <summary>
@@ -67,8 +67,8 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
         /// <param name="expected">DiagnosticResults that should appear after the analyzer is run on the sources</param>
         private void VerifyDiagnostics(string[] sources, string language, DiagnosticAnalyzer analyzer, params DiagnosticResult[] expected)
         {
-            var diagnostics = GetSortedDiagnostics(sources, language, analyzer);
-            VerifyDiagnosticResults(diagnostics, analyzer, expected);
+            var diagnostics = DiagnosticVerifier.GetSortedDiagnostics(sources, language, analyzer);
+            DiagnosticVerifier.VerifyDiagnosticResults(diagnostics, analyzer, expected);
         }
 
         #endregion
@@ -88,7 +88,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
 
             if (expectedCount != actualCount)
             {
-                string diagnosticsOutput = actualResults.Any() ? FormatDiagnostics(analyzer, actualResults.ToArray()) : "    NONE.";
+                string diagnosticsOutput = actualResults.Any() ? DiagnosticVerifier.FormatDiagnostics(analyzer, actualResults.ToArray()) : "    NONE.";
 
                 Assert.IsTrue(false,
                     string.Format("Mismatch between number of diagnostics returned, expected \"{0}\" actual \"{1}\"\r\n\r\nDiagnostics:\r\n{2}\r\n", expectedCount, actualCount, diagnosticsOutput));
@@ -105,12 +105,12 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                     {
                         Assert.IsTrue(false,
                             string.Format("Expected:\nA project diagnostic with No location\nActual:\n{0}",
-                            FormatDiagnostics(analyzer, actual)));
+                            DiagnosticVerifier.FormatDiagnostics(analyzer, actual)));
                     }
                 }
                 else
                 {
-                    VerifyDiagnosticLocation(analyzer, actual, actual.Location, expected.Locations.First());
+                    DiagnosticVerifier.VerifyDiagnosticLocation(analyzer, actual, actual.Location, expected.Locations.First());
                     var additionalLocations = actual.AdditionalLocations.ToArray();
 
                     if (additionalLocations.Length != expected.Locations.Length - 1)
@@ -118,12 +118,12 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                         Assert.IsTrue(false,
                             string.Format("Expected {0} additional locations but got {1} for Diagnostic:\r\n    {2}\r\n",
                                 expected.Locations.Length - 1, additionalLocations.Length,
-                                FormatDiagnostics(analyzer, actual)));
+                                DiagnosticVerifier.FormatDiagnostics(analyzer, actual)));
                     }
 
                     for (int j = 0; j < additionalLocations.Length; ++j)
                     {
-                        VerifyDiagnosticLocation(analyzer, actual, additionalLocations[j], expected.Locations[j + 1]);
+                        DiagnosticVerifier.VerifyDiagnosticLocation(analyzer, actual, additionalLocations[j], expected.Locations[j + 1]);
                     }
                 }
 
@@ -131,21 +131,21 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                 {
                     Assert.IsTrue(false,
                         string.Format("Expected diagnostic id to be \"{0}\" was \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                            expected.Id, actual.Id, FormatDiagnostics(analyzer, actual)));
+                            expected.Id, actual.Id, DiagnosticVerifier.FormatDiagnostics(analyzer, actual)));
                 }
 
                 if (actual.Severity != expected.Severity)
                 {
                     Assert.IsTrue(false,
                         string.Format("Expected diagnostic severity to be \"{0}\" was \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                            expected.Severity, actual.Severity, FormatDiagnostics(analyzer, actual)));
+                            expected.Severity, actual.Severity, DiagnosticVerifier.FormatDiagnostics(analyzer, actual)));
                 }
 
                 if (actual.GetMessage() != expected.Message)
                 {
                     Assert.IsTrue(false,
                         string.Format("Expected diagnostic message to be \"{0}\" was \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                            expected.Message, actual.GetMessage(), FormatDiagnostics(analyzer, actual)));
+                            expected.Message, actual.GetMessage(), DiagnosticVerifier.FormatDiagnostics(analyzer, actual)));
                 }
             }
         }
@@ -163,7 +163,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
 
             Assert.IsTrue(actualSpan.Path == expected.Path || (actualSpan.Path != null && actualSpan.Path.Contains("Test0.") && expected.Path.Contains("Test.")),
                 string.Format("Expected diagnostic to be in file \"{0}\" was actually in file \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                    expected.Path, actualSpan.Path, FormatDiagnostics(analyzer, diagnostic)));
+                    expected.Path, actualSpan.Path, DiagnosticVerifier.FormatDiagnostics(analyzer, diagnostic)));
 
             var actualLinePosition = actualSpan.StartLinePosition;
 
@@ -174,7 +174,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                 {
                     Assert.IsTrue(false,
                         string.Format("Expected diagnostic to be on line \"{0}\" was actually on line \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                            expected.Line, actualLinePosition.Line + 1, FormatDiagnostics(analyzer, diagnostic)));
+                            expected.Line, actualLinePosition.Line + 1, DiagnosticVerifier.FormatDiagnostics(analyzer, diagnostic)));
                 }
             }
 
@@ -185,7 +185,7 @@ namespace SMAPI.ModBuildConfig.Analyzer.Tests.Framework
                 {
                     Assert.IsTrue(false,
                         string.Format("Expected diagnostic to start at column \"{0}\" was actually at column \"{1}\"\r\n\r\nDiagnostic:\r\n    {2}\r\n",
-                            expected.Column, actualLinePosition.Character + 1, FormatDiagnostics(analyzer, diagnostic)));
+                            expected.Column, actualLinePosition.Character + 1, DiagnosticVerifier.FormatDiagnostics(analyzer, diagnostic)));
                 }
             }
         }
diff --git a/src/SMAPI.ModBuildConfig.Analyzer/AnalyzerReleases.Shipped.md b/src/SMAPI.ModBuildConfig.Analyzer/AnalyzerReleases.Shipped.md
new file mode 100644
index 00000000..9a46676d
--- /dev/null
+++ b/src/SMAPI.ModBuildConfig.Analyzer/AnalyzerReleases.Shipped.md
@@ -0,0 +1,7 @@
+## Release 2.1.0
+### New Rules
+Rule ID                   | Category           | Severity | Notes
+------------------------- | ------------------ | -------- | ------------------------------------------------------------
+AvoidImplicitNetFieldCast | SMAPI.CommonErrors | Warning  | See [documentation](https://smapi.io/package/code-warnings).
+AvoidNetField             | SMAPI.CommonErrors | Warning  | See [documentation](https://smapi.io/package/code-warnings).
+AvoidObsoleteField        | SMAPI.CommonErrors | Warning  | See [documentation](https://smapi.io/package/code-warnings).
diff --git a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
index 3fadc37a..7ac3277e 100644
--- a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
+++ b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
@@ -12,6 +12,10 @@
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="3.10.0" />
   </ItemGroup>
 
+  <ItemGroup>
+    <AdditionalFiles Include="AnalyzerReleases.Shipped.md" />
+  </ItemGroup>
+
   <ItemGroup>
     <None Include="$(OutputPath)\$(AssemblyName).dll" Pack="true" PackagePath="analyzers/dotnet/cs" Visible="false" />
   </ItemGroup>
diff --git a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
index 0bc8c45e..82eac7f6 100644
--- a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
+++ b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
@@ -5,6 +5,7 @@
     <TargetFramework>netstandard2.0</TargetFramework>
     <LangVersion>latest</LangVersion>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
 
     <!--NuGet package-->
     <PackageId>Pathoschild.Stardew.ModBuildConfig</PackageId>
diff --git a/src/SMAPI.Tests/Core/AssetNameTests.cs b/src/SMAPI.Tests/Core/AssetNameTests.cs
index b7e34191..ef8a08ef 100644
--- a/src/SMAPI.Tests/Core/AssetNameTests.cs
+++ b/src/SMAPI.Tests/Core/AssetNameTests.cs
@@ -34,7 +34,6 @@ namespace SMAPI.Tests.Core
             name = PathUtilities.NormalizeAssetName(name);
 
             // act
-            string calledWithLocale = null;
             IAssetName assetName = AssetName.Parse(name, parseLocale: _ => expectedLanguageCode);
 
             // assert
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index bfde649a..81820b05 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -610,6 +610,7 @@ namespace StardewModdingAPI.Framework
                 yield return group;
 
             // legacy load operations
+#pragma warning disable CS0612, CS0618 // deprecated code
             foreach (ModLinked<IAssetLoader> loader in this.Loaders)
             {
                 // check if loader applies
@@ -695,6 +696,7 @@ namespace StardewModdingAPI.Framework
                     }
                 );
             }
+#pragma warning restore CS0612, CS0618
         }
 
         /// <summary>Get an asset info compatible with legacy <see cref="IAssetLoader"/> and <see cref="IAssetEditor"/> instances, which always expect the base name.</summary>
diff --git a/src/SMAPI/Framework/ContentManagers/IContentManager.cs b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
index c4625761..c8b2ae64 100644
--- a/src/SMAPI/Framework/ContentManagers/IContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/IContentManager.cs
@@ -38,6 +38,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <summary>Load an asset through the content pipeline, using a localized variant of the <paramref name="assetName"/> if available.</summary>
         /// <typeparam name="T">The type of asset to load.</typeparam>
         /// <param name="assetName">The asset name relative to the loader root directory.</param>
+        /// <param name="language">The language for which to load the asset.</param>
         /// <param name="useCache">Whether to read/write the loaded asset to the asset cache.</param>
         T LoadLocalized<T>(IAssetName assetName, LocalizedContentManager.LanguageCode language, bool useCache);
 
diff --git a/src/SMAPI/Framework/ModHelpers/ModHelper.cs b/src/SMAPI/Framework/ModHelpers/ModHelper.cs
index 2a8aeb3a..3cfe52bf 100644
--- a/src/SMAPI/Framework/ModHelpers/ModHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ModHelper.cs
@@ -95,7 +95,13 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="translationHelper">An API for reading translations stored in the mod's <c>i18n</c> folder.</param>
         /// <exception cref="ArgumentNullException">An argument is null or empty.</exception>
         /// <exception cref="InvalidOperationException">The <paramref name="modDirectory"/> path does not exist on disk.</exception>
-        public ModHelper(string modID, string modDirectory, Func<SInputState> currentInputState, IModEvents events, ContentHelper contentHelper, IGameContentHelper gameContentHelper, IModContentHelper modContentHelper, IContentPackHelper contentPackHelper, ICommandHelper commandHelper, IDataHelper dataHelper, IModRegistry modRegistry, IReflectionHelper reflectionHelper, IMultiplayerHelper multiplayer, ITranslationHelper translationHelper)
+        public ModHelper(
+            string modID, string modDirectory, Func<SInputState> currentInputState, IModEvents events,
+#pragma warning disable CS0612 // deprecated code
+            ContentHelper contentHelper,
+#pragma warning restore CS0612
+            IGameContentHelper gameContentHelper, IModContentHelper modContentHelper, IContentPackHelper contentPackHelper, ICommandHelper commandHelper, IDataHelper dataHelper, IModRegistry modRegistry, IReflectionHelper reflectionHelper, IMultiplayerHelper multiplayer, ITranslationHelper translationHelper
+        )
             : base(modID)
         {
             // validate directory
@@ -106,7 +112,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
 
             // initialize
             this.DirectoryPath = modDirectory;
+#pragma warning disable CS0612 // deprecated code
             this.ContentImpl = contentHelper ?? throw new ArgumentNullException(nameof(contentHelper));
+#pragma warning restore CS0612
             this.GameContent = gameContentHelper ?? throw new ArgumentNullException(nameof(gameContentHelper));
             this.ModContent = modContentHelper ?? throw new ArgumentNullException(nameof(modContentHelper));
             this.ContentPacks = contentPackHelper ?? throw new ArgumentNullException(nameof(contentPackHelper));
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index 8a5c10f6..6ca463a2 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1593,6 +1593,7 @@ namespace StardewModdingAPI.Framework
 
             // initialize loaded non-content-pack mods
             this.Monitor.Log("Launching mods...", LogLevel.Debug);
+#pragma warning disable CS0612, CS0618 // deprecated code
             foreach (IModMetadata metadata in loadedMods)
             {
                 // add interceptors
@@ -1628,6 +1629,7 @@ namespace StardewModdingAPI.Framework
                     content.ObservableAssetEditors.CollectionChanged += (_, e) => this.OnAssetInterceptorsChanged(metadata, e.NewItems?.Cast<IAssetEditor>(), e.OldItems?.Cast<IAssetEditor>(), this.ContentCore.Editors);
                     content.ObservableAssetLoaders.CollectionChanged += (_, e) => this.OnAssetInterceptorsChanged(metadata, e.NewItems?.Cast<IAssetLoader>(), e.OldItems?.Cast<IAssetLoader>(), this.ContentCore.Loaders);
                 }
+#pragma warning restore CS0612, CS0618
 
                 // call entry method
                 try
@@ -1847,7 +1849,9 @@ namespace StardewModdingAPI.Framework
                         IModEvents events = new ModEvents(mod, this.EventManager);
                         ICommandHelper commandHelper = new CommandHelper(mod, this.CommandManager);
                         CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath);
+#pragma warning disable CS0612 // deprecated code
                         ContentHelper contentHelper = new(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor);
+#pragma warning restore CS0612
                         GameContentHelper gameContentHelper = new(contentCore, manifest.UniqueID, mod.DisplayName, monitor);
                         IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
                         IContentPackHelper contentPackHelper = new ContentPackHelper(manifest.UniqueID, new Lazy<IContentPack[]>(GetContentPacks), CreateFakeContentPack);
-- 
cgit 


From d1a7194bf604ac9f960c45de0c82e6eaddd5ff5a Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Wed, 6 Apr 2022 23:47:12 -0400
Subject: allow null values in ISemanticVersion compare methods (#837)

---
 docs/release-notes.md                             |  1 +
 src/SMAPI.Tests/Utilities/SemanticVersionTests.cs | 39 +++++++++++++++++------
 src/SMAPI.Toolkit/SemanticVersion.cs              | 27 ++++++++++++----
 3 files changed, 52 insertions(+), 15 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 732cd530..96a236ad 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -32,6 +32,7 @@
     _This adds methods for working with asset names, parsed locales, etc._
   * Added `helper.Content.ParseAssetName` to get an `IAssetName` for an arbitrary asset key.
   * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
+  * The `ISemanticVersion` comparison methods (`CompareTo`, `IsBetween`, `IsNewerThan`, and `IsOlderThan`) now allow null values. A null version is always considered smaller than any non-null version per [best practices](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable-1.compareto#remarks).
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
diff --git a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
index 66181ea6..599ac839 100644
--- a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
+++ b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
@@ -219,11 +219,16 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta.2", "1.0-beta.1", ExpectedResult = 1)]
         [TestCase("1.0-beta.10", "1.0-beta.2", ExpectedResult = 1)]
         [TestCase("1.0-beta-10", "1.0-beta-2", ExpectedResult = 1)]
+
+        // null
+        [TestCase("1.0.0", null, ExpectedResult = 1)] // null is always less than any value per CompareTo remarks
         public int CompareTo(string versionStrA, string versionStrB)
         {
             // arrange
             ISemanticVersion versionA = new SemanticVersion(versionStrA);
-            ISemanticVersion versionB = new SemanticVersion(versionStrB);
+            ISemanticVersion versionB = versionStrB != null
+                ? new SemanticVersion(versionStrB)
+                : null;
 
             // assert
             return versionA.CompareTo(versionB);
@@ -262,14 +267,19 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta.2", "1.0-beta.1", ExpectedResult = false)]
         [TestCase("1.0-beta.10", "1.0-beta.2", ExpectedResult = false)]
         [TestCase("1.0-beta-10", "1.0-beta-2", ExpectedResult = false)]
+
+        // null
+        [TestCase("1.0.0", null, ExpectedResult = false)] // null is always less than any value per CompareTo remarks
         public bool IsOlderThan(string versionStrA, string versionStrB)
         {
             // arrange
             ISemanticVersion versionA = new SemanticVersion(versionStrA);
-            ISemanticVersion versionB = new SemanticVersion(versionStrB);
+            ISemanticVersion versionB = versionStrB != null
+                ? new SemanticVersion(versionStrB)
+                : null;
 
             // assert
-            Assert.AreEqual(versionA.IsOlderThan(versionB), versionA.IsOlderThan(versionB.ToString()), "The two signatures returned different results.");
+            Assert.AreEqual(versionA.IsOlderThan(versionB), versionA.IsOlderThan(versionB?.ToString()), "The two signatures returned different results.");
             return versionA.IsOlderThan(versionB);
         }
 
@@ -306,14 +316,19 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta.2", "1.0-beta.1", ExpectedResult = true)]
         [TestCase("1.0-beta.10", "1.0-beta.2", ExpectedResult = true)]
         [TestCase("1.0-beta-10", "1.0-beta-2", ExpectedResult = true)]
+
+        // null
+        [TestCase("1.0.0", null, ExpectedResult = true)] // null is always less than any value per CompareTo remarks
         public bool IsNewerThan(string versionStrA, string versionStrB)
         {
             // arrange
             ISemanticVersion versionA = new SemanticVersion(versionStrA);
-            ISemanticVersion versionB = new SemanticVersion(versionStrB);
+            ISemanticVersion versionB = versionStrB != null
+                ? new SemanticVersion(versionStrB)
+                : null;
 
             // assert
-            Assert.AreEqual(versionA.IsNewerThan(versionB), versionA.IsNewerThan(versionB.ToString()), "The two signatures returned different results.");
+            Assert.AreEqual(versionA.IsNewerThan(versionB), versionA.IsNewerThan(versionB?.ToString()), "The two signatures returned different results.");
             return versionA.IsNewerThan(versionB);
         }
 
@@ -324,7 +339,7 @@ namespace SMAPI.Tests.Utilities
         /// <param name="versionStr">The main version.</param>
         /// <param name="lowerStr">The lower version number.</param>
         /// <param name="upperStr">The upper version number.</param>
-        [Test(Description = "Assert that version.IsNewerThan returns the expected value.")]
+        [Test(Description = "Assert that version.IsBetween returns the expected value.")]
         // is between
         [TestCase("0.5.7-beta.3", "0.5.7-beta.3", "0.5.7-beta.3", ExpectedResult = true)]
         [TestCase("1.0", "1.0", "1.1", ExpectedResult = true)]
@@ -332,6 +347,7 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0", "0.5", "1.1", ExpectedResult = true)]
         [TestCase("1.0-beta.2", "1.0-beta.1", "1.0-beta.3", ExpectedResult = true)]
         [TestCase("1.0-beta-2", "1.0-beta-1", "1.0-beta-3", ExpectedResult = true)]
+        [TestCase("1.0.0", null, "1.0.0", ExpectedResult = true)] // null is always less than any value per CompareTo remarks
 
         // is not between
         [TestCase("1.0-beta", "1.0", "1.1", ExpectedResult = false)]
@@ -339,15 +355,20 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta.2", "1.1", "1.0", ExpectedResult = false)]
         [TestCase("1.0-beta.2", "1.0-beta.10", "1.0-beta.3", ExpectedResult = false)]
         [TestCase("1.0-beta-2", "1.0-beta-10", "1.0-beta-3", ExpectedResult = false)]
+        [TestCase("1.0.0", "1.0.0", null, ExpectedResult = false)] // null is always less than any value per CompareTo remarks
         public bool IsBetween(string versionStr, string lowerStr, string upperStr)
         {
             // arrange
-            ISemanticVersion lower = new SemanticVersion(lowerStr);
-            ISemanticVersion upper = new SemanticVersion(upperStr);
+            ISemanticVersion lower = lowerStr != null
+                ? new SemanticVersion(lowerStr)
+                : null;
+            ISemanticVersion upper = upperStr != null
+                ? new SemanticVersion(upperStr)
+                : null;
             ISemanticVersion version = new SemanticVersion(versionStr);
 
             // assert
-            Assert.AreEqual(version.IsBetween(lower, upper), version.IsBetween(lower.ToString(), upper.ToString()), "The two signatures returned different results.");
+            Assert.AreEqual(version.IsBetween(lower, upper), version.IsBetween(lower?.ToString(), upper?.ToString()), "The two signatures returned different results.");
             return version.IsBetween(lower, upper);
         }
 
diff --git a/src/SMAPI.Toolkit/SemanticVersion.cs b/src/SMAPI.Toolkit/SemanticVersion.cs
index 97b92555..41ae12eb 100644
--- a/src/SMAPI.Toolkit/SemanticVersion.cs
+++ b/src/SMAPI.Toolkit/SemanticVersion.cs
@@ -108,9 +108,9 @@ namespace StardewModdingAPI.Toolkit
         /// <inheritdoc />
         public int CompareTo(ISemanticVersion other)
         {
-            if (other == null)
-                throw new ArgumentNullException(nameof(other));
-            return this.CompareTo(other.MajorVersion, other.MinorVersion, other.PatchVersion, (other as SemanticVersion)?.PlatformRelease ?? 0, other.PrereleaseTag);
+            return other == null
+                ? 1
+                : this.CompareTo(other.MajorVersion, other.MinorVersion, other.PatchVersion, (other as SemanticVersion)?.PlatformRelease ?? 0, other.PrereleaseTag);
         }
 
         /// <inheritdoc />
@@ -134,7 +134,11 @@ namespace StardewModdingAPI.Toolkit
         /// <inheritdoc />
         public bool IsOlderThan(string other)
         {
-            return this.IsOlderThan(new SemanticVersion(other, allowNonStandard: true));
+            ISemanticVersion otherVersion = other != null
+                ? new SemanticVersion(other, allowNonStandard: true)
+                : null;
+
+            return this.IsOlderThan(otherVersion);
         }
 
         /// <inheritdoc />
@@ -146,7 +150,11 @@ namespace StardewModdingAPI.Toolkit
         /// <inheritdoc />
         public bool IsNewerThan(string other)
         {
-            return this.IsNewerThan(new SemanticVersion(other, allowNonStandard: true));
+            ISemanticVersion otherVersion = other != null
+                ? new SemanticVersion(other, allowNonStandard: true)
+                : null;
+
+            return this.IsNewerThan(otherVersion);
         }
 
         /// <inheritdoc />
@@ -158,7 +166,14 @@ namespace StardewModdingAPI.Toolkit
         /// <inheritdoc />
         public bool IsBetween(string min, string max)
         {
-            return this.IsBetween(new SemanticVersion(min, allowNonStandard: true), new SemanticVersion(max, allowNonStandard: true));
+            ISemanticVersion minVersion = min != null
+                ? new SemanticVersion(min, allowNonStandard: true)
+                : null;
+            ISemanticVersion maxVersion = max != null
+                ? new SemanticVersion(max, allowNonStandard: true)
+                : null;
+
+            return this.IsBetween(minVersion, maxVersion);
         }
 
         /// <inheritdoc cref="ISemanticVersion.ToString" />
-- 
cgit 


From 3f9b412beda2d9c9168473089f201149cb27f755 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 7 Apr 2022 00:26:28 -0400
Subject: expand & reorganize 3.14.0 release notes

---
 docs/release-notes.md | 64 +++++++++++++++++++++++++++++----------------------
 1 file changed, 37 insertions(+), 27 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 96a236ad..bb30f31a 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -2,46 +2,56 @@
 
 # Release notes
 ## Upcoming release
-* For players:
-  * Fixed support for `_international` content assets (used in the movie theater).
-  * Fixed the warning text when a mod causes an asset load conflict with itself.
-  * Improved Linux/macOS [command-line arguments](technical/smapi.md#command-line-arguments):
-    * Added `--use-current-shell` to avoid opening a separate terminal window.
-    * Fixed `--no-terminal` still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
-  * SMAPI now fixes many case-sensitive mod file path issues automatically.
+### For players
+* Changes:
+  * On Linux, SMAPI now fixes many issues with case-sensitive mod paths automatically.
+  * On Linux/macOS, added `--use-current-shell` [command-line argument](technical/smapi.md#command-line-arguments) to avoid opening a separate terminal window.
   * Dropped update checks for the unofficial 64-bit patcher (obsolete since SMAPI 3.12.6).
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+* Fixes:
+  * Fixed some movie theater textures not translated when loaded through SMAPI (specifically assets with the `_international` suffix).
+  * Fixed the warning text when a mod causes an asset load conflict with itself.
+  * Fixed `--no-terminal` [command-line argument](technical/smapi.md#command-line-arguments) on Linux/macOS still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
+  * Fixed `player_add` console command not handling journal scraps and secret notes correctly.
+  * Fixed `set_farm_type` console command not updating warps.
 
-* For the Console Commands mod:
-  * Fixed `player_add` not handling journal scraps and secret notes correctly.
-  * Fixed `set_farm_type` not updating warps.
-
-* For mod authors:
-  * **Major changes as part of the upcoming SMAPI 4.0.0:**
-    * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
-      _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
-    * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
-    * Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
-      _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
-    * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
-    * **Deprecation warning:** The upcoming SMAPI 4.0 will remove deprecated APIs and break mods which haven't updated yet.  
-    _See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0) for help updating your mod code. You can update your mod code now, there's no need to wait for the 4.0.0 release (which will happen in at least three months, and possibly later if needed to update open-source mods)._
+### For the web UI
+* Updated the JSON validator/schema for Content Patcher 1.25.0.
+* Added `data-*` attributes to the log parser page for external tools.
+* Fixed JSON validator showing incorrect error for update keys without a subkey.
+
+
+### For mod authors
+This is a big release that includes the new APIs planned for SMAPI 4.0.0, alongside the old ones.
+
+For C# mod authors: SMAPI 4.0.0 will release _no sooner_ than August 2022 (and later if needed to
+update open-source mods). At that point it will **remove all deprecated APIs and break C# mods
+which haven't updated yet**. See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0)
+for help updating your mod code. (You can update now, there's no need to wait for 4.0.0.)
+
+For content pack authors: SMAPI 4.0.0 won't affect content packs. They should work fine as long as
+the C# mod that loads them is updated.
+
+* Major changes:
+  * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
+    _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
+  * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
+  * Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
+    _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
+  * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
+* Other improvements:
   * Added `IContentPack.ModContent` property.
   * Added `Constants.ContentPath`.
   * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
     _This adds methods for working with asset names, parsed locales, etc._
   * Added `helper.Content.ParseAssetName` to get an `IAssetName` for an arbitrary asset key.
   * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
-  * The `ISemanticVersion` comparison methods (`CompareTo`, `IsBetween`, `IsNewerThan`, and `IsOlderThan`) now allow null values. A null version is always considered smaller than any non-null version per [best practices](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable-1.compareto#remarks).
+  * The `ISemanticVersion` comparison methods (`CompareTo`, `IsBetween`, `IsNewerThan`, and `IsOlderThan`) now allow null values. A null version is always considered older than any non-null version per [best practices](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable-1.compareto#remarks).
+* Fixes:
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
 
-* For the web UI:
-  * Updated the JSON validator/schema for Content Patcher 1.25.0.
-  * Added `data-*` attributes to log parser page for external tools.
-  * Fixed JSON validator warning shown for update keys without a subkey.
-
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
 
-- 
cgit 


From 6b05296e71c32abd158f354eeeaf1e135e72e6e2 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 7 Apr 2022 01:51:50 -0400
Subject: migrate mod build package to .NET 5 to allow full nullable
 annotations (#837)

---
 docs/technical/mod-package.md                      | 10 ++++++
 .../SMAPI.ModBuildConfig.Analyzer.csproj           |  2 +-
 .../SMAPI.ModBuildConfig.csproj                    |  2 +-
 .../SMAPI.Toolkit.CoreInterfaces.csproj            |  2 +-
 src/SMAPI.Toolkit/SMAPI.Toolkit.csproj             |  2 +-
 src/SMAPI.Toolkit/SemanticVersion.cs               | 14 ++-------
 src/SMAPI.Toolkit/Serialization/Models/Manifest.cs |  2 --
 .../Serialization/Models/ManifestContentPackFor.cs |  2 --
 .../Serialization/Models/ManifestDependency.cs     |  2 --
 src/SMAPI.Toolkit/Utilities/PathUtilities.cs       | 36 ----------------------
 10 files changed, 16 insertions(+), 58 deletions(-)

(limited to 'docs')

diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
index 4c31f69b..6123b28f 100644
--- a/docs/technical/mod-package.md
+++ b/docs/technical/mod-package.md
@@ -413,9 +413,19 @@ when you compile it.
 
 ## Release notes
 ## Upcoming release
+* Migrated from .NET Standard 2.0 to .NET 5.0.  
 * Added detection for Xbox app game folders.
 * Internal refactoring.
 
+**Troubleshooting:**  
+Due to the framework change, you might see build errors like _task failed unexpectedly_ that mentions `System.Runtime Version=5.0.0`. If so:
+
+1. Make sure you have Visual Studio 2022 or later.
+2. Exit all instances of Visual Studio.
+3. Delete the hidden `.vs` folder in your solution folder.
+4. Delete the `bin` and `obj` folders in each project folder.
+5. Reopen the solution and rebuild, and now it should work fine.
+
 ## 4.0.0
 Released 30 November 2021.
 
diff --git a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
index 7ac3277e..69fd3dbd 100644
--- a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
+++ b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI.ModBuildConfig.Analyzer</RootNamespace>
     <Version>3.0.0</Version>
-    <TargetFramework>netstandard2.0</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>
     <IncludeBuildOutput>false</IncludeBuildOutput>
     <OutputPath>bin</OutputPath>
     <LangVersion>latest</LangVersion>
diff --git a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
index 82eac7f6..8e70293e 100644
--- a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
+++ b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <!--build-->
     <RootNamespace>StardewModdingAPI.ModBuildConfig</RootNamespace>
-    <TargetFramework>netstandard2.0</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>
     <LangVersion>latest</LangVersion>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
diff --git a/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj b/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
index 4c92b4db..d69d53d5 100644
--- a/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
+++ b/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI</RootNamespace>
     <Description>Provides toolkit interfaces which are available to SMAPI mods.</Description>
-    <TargetFrameworks>net5.0; netstandard2.0</TargetFrameworks>
+    <TargetFrameworks>net5.0</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
diff --git a/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj b/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
index ec27bf79..6a8c4c43 100644
--- a/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
+++ b/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI.Toolkit</RootNamespace>
     <Description>A library which encapsulates mod-handling logic for mod managers and tools. Not intended for use by mods.</Description>
-    <TargetFrameworks>net5.0; netstandard2.0</TargetFrameworks>
+    <TargetFrameworks>net5.0</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
diff --git a/src/SMAPI.Toolkit/SemanticVersion.cs b/src/SMAPI.Toolkit/SemanticVersion.cs
index cea8c447..ca9d15f5 100644
--- a/src/SMAPI.Toolkit/SemanticVersion.cs
+++ b/src/SMAPI.Toolkit/SemanticVersion.cs
@@ -198,12 +198,7 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="version">The version string.</param>
         /// <param name="parsed">The parsed representation.</param>
         /// <returns>Returns whether parsing the version succeeded.</returns>
-        public static bool TryParse(string? version,
-#if NET5_0_OR_GREATER
-            [NotNullWhen(true)]
-#endif
-            out ISemanticVersion? parsed
-        )
+        public static bool TryParse(string? version, [NotNullWhen(true)] out ISemanticVersion? parsed)
         {
             return SemanticVersion.TryParse(version, allowNonStandard: false, out parsed);
         }
@@ -213,12 +208,7 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="allowNonStandard">Whether to allow non-standard extensions to semantic versioning.</param>
         /// <param name="parsed">The parsed representation.</param>
         /// <returns>Returns whether parsing the version succeeded.</returns>
-        public static bool TryParse(string? version, bool allowNonStandard,
-#if NET5_0_OR_GREATER
-            [NotNullWhen(true)]
-#endif
-            out ISemanticVersion? parsed
-        )
+        public static bool TryParse(string? version, bool allowNonStandard, [NotNullWhen(true)] out ISemanticVersion? parsed)
         {
             if (version == null)
             {
diff --git a/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs b/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
index 01010602..3ab5edfb 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
@@ -115,9 +115,7 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
-#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
-#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input
diff --git a/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs b/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
index f7dc8aa8..dcdbcf74 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
@@ -33,9 +33,7 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
-#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
-#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input?.Trim();
diff --git a/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs b/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
index e7acf71d..64725818 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
@@ -54,9 +54,7 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
-#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
-#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input?.Trim();
diff --git a/src/SMAPI.Toolkit/Utilities/PathUtilities.cs b/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
index 9a0e2ea7..d035d4cd 100644
--- a/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
+++ b/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
@@ -92,43 +92,7 @@ namespace StardewModdingAPI.Toolkit.Utilities
         [Pure]
         public static string GetRelativePath(string sourceDir, string targetPath)
         {
-#if NET5_0
             return Path.GetRelativePath(sourceDir, targetPath);
-#else
-            // NOTE:
-            // this is a heuristic implementation that works in the cases SMAPI needs it for, but it
-            // doesn't handle all edge cases (e.g. case-sensitivity on Linux, or traversing between
-            // UNC paths on Windows). SMAPI and mods will use the more robust .NET 5 version anyway
-            // though, this is only for compatibility with the mod build package.
-
-            // convert to URIs
-            Uri from = new(sourceDir.TrimEnd(PathUtilities.PossiblePathSeparators) + "/");
-            Uri to = new(targetPath.TrimEnd(PathUtilities.PossiblePathSeparators) + "/");
-            if (from.Scheme != to.Scheme)
-                throw new InvalidOperationException($"Can't get path for '{targetPath}' relative to '{sourceDir}'.");
-
-            // get relative path
-            string rawUrl = Uri.UnescapeDataString(from.MakeRelativeUri(to).ToString());
-            if (rawUrl.StartsWith("file://"))
-                rawUrl = PathUtilities.WindowsUncRoot + rawUrl.Substring("file://".Length);
-            string relative = PathUtilities.NormalizePath(rawUrl);
-
-            // normalize
-            if (relative == "")
-                relative = ".";
-            else
-            {
-                // trim trailing slash from URL
-                if (relative.EndsWith(PathUtilities.PreferredPathSeparator.ToString()))
-                    relative = relative.Substring(0, relative.Length - 1);
-
-                // fix root
-                if (relative.StartsWith("file:") && !targetPath.Contains("file:"))
-                    relative = relative.Substring("file:".Length);
-            }
-
-            return relative;
-#endif
         }
 
         /// <summary>Get whether a path is relative and doesn't try to climb out of its containing folder (e.g. doesn't contain <c>../</c>).</summary>
-- 
cgit 


From 238045ba9c5937f684cad3c55a8f9b9c2733e45f Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 7 Apr 2022 22:19:48 -0400
Subject: reverse mod build package migration to .NET 5 (#837)

The migrated package didn't work consistently in VIsual Studio, so this suppresses nullable annotations in .NET Standard instead.
---
 build/common.targets                               |  5 ++-
 docs/technical/mod-package.md                      | 10 ------
 .../SMAPI.ModBuildConfig.Analyzer.csproj           |  2 +-
 .../SMAPI.ModBuildConfig.csproj                    |  2 +-
 .../SMAPI.Toolkit.CoreInterfaces.csproj            |  2 +-
 .../Framework/SemanticVersionReader.cs             |  7 +++-
 .../Framework/UpdateData/UpdateKey.cs              |  2 ++
 src/SMAPI.Toolkit/SMAPI.Toolkit.csproj             |  2 +-
 src/SMAPI.Toolkit/SemanticVersion.cs               | 14 ++++++--
 src/SMAPI.Toolkit/Serialization/JsonHelper.cs      |  7 +++-
 src/SMAPI.Toolkit/Serialization/Models/Manifest.cs |  2 ++
 .../Serialization/Models/ManifestContentPackFor.cs |  2 ++
 .../Serialization/Models/ManifestDependency.cs     |  2 ++
 src/SMAPI.Toolkit/Utilities/PathUtilities.cs       | 42 +++++++++++++++++++++-
 14 files changed, 81 insertions(+), 20 deletions(-)

(limited to 'docs')

diff --git a/build/common.targets b/build/common.targets
index 258b48f2..c227190a 100644
--- a/build/common.targets
+++ b/build/common.targets
@@ -5,7 +5,10 @@
     <Product>SMAPI</Product>
     <LangVersion>latest</LangVersion>
     <AssemblySearchPaths>$(AssemblySearchPaths);{GAC}</AssemblySearchPaths>
-    <Nullable>enable</Nullable>
+
+    <!--enable nullable annotations, except in .NET Standard 2.0 where they aren't supported-->
+    <Nullable Condition="'$(TargetFramework)' == 'net5.0'">enable</Nullable>
+    <NoWarn Condition="'$(TargetFramework)' != 'net5.0'">$(NoWarn);CS8632</NoWarn>
 
     <!--set platform-->
     <DefineConstants Condition="$(OS) == 'Windows_NT'">$(DefineConstants);SMAPI_FOR_WINDOWS</DefineConstants>
diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
index 6123b28f..4c31f69b 100644
--- a/docs/technical/mod-package.md
+++ b/docs/technical/mod-package.md
@@ -413,19 +413,9 @@ when you compile it.
 
 ## Release notes
 ## Upcoming release
-* Migrated from .NET Standard 2.0 to .NET 5.0.  
 * Added detection for Xbox app game folders.
 * Internal refactoring.
 
-**Troubleshooting:**  
-Due to the framework change, you might see build errors like _task failed unexpectedly_ that mentions `System.Runtime Version=5.0.0`. If so:
-
-1. Make sure you have Visual Studio 2022 or later.
-2. Exit all instances of Visual Studio.
-3. Delete the hidden `.vs` folder in your solution folder.
-4. Delete the `bin` and `obj` folders in each project folder.
-5. Reopen the solution and rebuild, and now it should work fine.
-
 ## 4.0.0
 Released 30 November 2021.
 
diff --git a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
index 69fd3dbd..7ac3277e 100644
--- a/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
+++ b/src/SMAPI.ModBuildConfig.Analyzer/SMAPI.ModBuildConfig.Analyzer.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI.ModBuildConfig.Analyzer</RootNamespace>
     <Version>3.0.0</Version>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>netstandard2.0</TargetFramework>
     <IncludeBuildOutput>false</IncludeBuildOutput>
     <OutputPath>bin</OutputPath>
     <LangVersion>latest</LangVersion>
diff --git a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
index 8e70293e..82eac7f6 100644
--- a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
+++ b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <!--build-->
     <RootNamespace>StardewModdingAPI.ModBuildConfig</RootNamespace>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>netstandard2.0</TargetFramework>
     <LangVersion>latest</LangVersion>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
diff --git a/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj b/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
index d69d53d5..4c92b4db 100644
--- a/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
+++ b/src/SMAPI.Toolkit.CoreInterfaces/SMAPI.Toolkit.CoreInterfaces.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI</RootNamespace>
     <Description>Provides toolkit interfaces which are available to SMAPI mods.</Description>
-    <TargetFrameworks>net5.0</TargetFrameworks>
+    <TargetFrameworks>net5.0; netstandard2.0</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
diff --git a/src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs b/src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs
index 836b1134..939be771 100644
--- a/src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs
+++ b/src/SMAPI.Toolkit/Framework/SemanticVersionReader.cs
@@ -105,7 +105,12 @@ namespace StardewModdingAPI.Toolkit.Framework
         /// <param name="raw">The raw characters to parse.</param>
         /// <param name="index">The index of the next character to read.</param>
         /// <param name="tag">The parsed tag.</param>
-        private static bool TryParseTag(char[] raw, ref int index, [NotNullWhen(true)] out string? tag)
+        private static bool TryParseTag(char[] raw, ref int index,
+#if NET5_0_OR_GREATER
+            [NotNullWhen(true)]
+#endif
+            out string? tag
+        )
         {
             // read tag length
             int length = 0;
diff --git a/src/SMAPI.Toolkit/Framework/UpdateData/UpdateKey.cs b/src/SMAPI.Toolkit/Framework/UpdateData/UpdateKey.cs
index d40d8f2b..4c9ca2ff 100644
--- a/src/SMAPI.Toolkit/Framework/UpdateData/UpdateKey.cs
+++ b/src/SMAPI.Toolkit/Framework/UpdateData/UpdateKey.cs
@@ -16,7 +16,9 @@ namespace StardewModdingAPI.Toolkit.Framework.UpdateData
         public ModSiteKey Site { get; }
 
         /// <summary>The mod ID within the repository.</summary>
+#if NET5_0_OR_GREATER
         [MemberNotNullWhen(true, nameof(LooksValid))]
+#endif
         public string? ID { get; }
 
         /// <summary>If specified, a substring in download names/descriptions to match.</summary>
diff --git a/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj b/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
index 6a8c4c43..ec27bf79 100644
--- a/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
+++ b/src/SMAPI.Toolkit/SMAPI.Toolkit.csproj
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <RootNamespace>StardewModdingAPI.Toolkit</RootNamespace>
     <Description>A library which encapsulates mod-handling logic for mod managers and tools. Not intended for use by mods.</Description>
-    <TargetFrameworks>net5.0</TargetFrameworks>
+    <TargetFrameworks>net5.0; netstandard2.0</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
diff --git a/src/SMAPI.Toolkit/SemanticVersion.cs b/src/SMAPI.Toolkit/SemanticVersion.cs
index cbdd7a85..2cb27e11 100644
--- a/src/SMAPI.Toolkit/SemanticVersion.cs
+++ b/src/SMAPI.Toolkit/SemanticVersion.cs
@@ -198,7 +198,12 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="version">The version string.</param>
         /// <param name="parsed">The parsed representation.</param>
         /// <returns>Returns whether parsing the version succeeded.</returns>
-        public static bool TryParse(string? version, [NotNullWhen(true)] out ISemanticVersion? parsed)
+        public static bool TryParse(string? version,
+#if NET5_0_OR_GREATER
+            [NotNullWhen(true)]
+#endif
+            out ISemanticVersion? parsed
+        )
         {
             return SemanticVersion.TryParse(version, allowNonStandard: false, out parsed);
         }
@@ -208,7 +213,12 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="allowNonStandard">Whether to allow non-standard extensions to semantic versioning.</param>
         /// <param name="parsed">The parsed representation.</param>
         /// <returns>Returns whether parsing the version succeeded.</returns>
-        public static bool TryParse(string? version, bool allowNonStandard, [NotNullWhen(true)] out ISemanticVersion? parsed)
+        public static bool TryParse(string? version, bool allowNonStandard,
+#if NET5_0_OR_GREATER
+            [NotNullWhen(true)]
+#endif
+            out ISemanticVersion? parsed
+        )
         {
             if (version == null)
             {
diff --git a/src/SMAPI.Toolkit/Serialization/JsonHelper.cs b/src/SMAPI.Toolkit/Serialization/JsonHelper.cs
index 7d1804e5..3c9308f2 100644
--- a/src/SMAPI.Toolkit/Serialization/JsonHelper.cs
+++ b/src/SMAPI.Toolkit/Serialization/JsonHelper.cs
@@ -37,7 +37,12 @@ namespace StardewModdingAPI.Toolkit.Serialization
         /// <returns>Returns false if the file doesn't exist, else true.</returns>
         /// <exception cref="ArgumentException">The given <paramref name="fullPath"/> is empty or invalid.</exception>
         /// <exception cref="JsonReaderException">The file contains invalid JSON.</exception>
-        public bool ReadJsonFileIfExists<TModel>(string fullPath, [NotNullWhen(true)] out TModel? result)
+        public bool ReadJsonFileIfExists<TModel>(string fullPath,
+#if NET5_0_OR_GREATER
+            [NotNullWhen(true)]
+#endif
+            out TModel? result
+        )
         {
             // validate
             if (string.IsNullOrWhiteSpace(fullPath))
diff --git a/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs b/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
index 3ab5edfb..01010602 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/Manifest.cs
@@ -115,7 +115,9 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
+#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
+#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input
diff --git a/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs b/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
index dcdbcf74..f7dc8aa8 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/ManifestContentPackFor.cs
@@ -33,7 +33,9 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
+#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
+#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input?.Trim();
diff --git a/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs b/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
index 5d1b73b1..fa254ea7 100644
--- a/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
+++ b/src/SMAPI.Toolkit/Serialization/Models/ManifestDependency.cs
@@ -54,7 +54,9 @@ namespace StardewModdingAPI.Toolkit.Serialization.Models
         *********/
         /// <summary>Normalize whitespace in a raw string.</summary>
         /// <param name="input">The input to strip.</param>
+#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("input")]
+#endif
         private string? NormalizeWhitespace(string? input)
         {
             return input?.Trim();
diff --git a/src/SMAPI.Toolkit/Utilities/PathUtilities.cs b/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
index 9b7a78a0..136279f2 100644
--- a/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
+++ b/src/SMAPI.Toolkit/Utilities/PathUtilities.cs
@@ -50,7 +50,9 @@ namespace StardewModdingAPI.Toolkit.Utilities
         /// <summary>Normalize an asset name to match how MonoGame's content APIs would normalize and cache it.</summary>
         /// <param name="assetName">The asset name to normalize.</param>
         [Pure]
+#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("assetName")]
+#endif
         public static string? NormalizeAssetName(string? assetName)
         {
             assetName = assetName?.Trim();
@@ -64,7 +66,9 @@ namespace StardewModdingAPI.Toolkit.Utilities
         /// <param name="path">The file path to normalize.</param>
         /// <remarks>This should only be used for file paths. For asset names, use <see cref="NormalizeAssetName"/> instead.</remarks>
         [Pure]
+#if NET5_0_OR_GREATER
         [return: NotNullIfNotNull("path")]
+#endif
         public static string? NormalizePath(string? path)
         {
             path = path?.Trim();
@@ -89,7 +93,7 @@ namespace StardewModdingAPI.Toolkit.Utilities
             }
 
             // keep trailing separator
-            if ((!hasRoot || segments.Any()) && PathUtilities.PossiblePathSeparators.Contains(path[^1]))
+            if ((!hasRoot || segments.Any()) && PathUtilities.PossiblePathSeparators.Contains(path[path.Length - 1]))
                 newPath += PathUtilities.PreferredPathSeparator;
 
             return newPath;
@@ -101,7 +105,43 @@ namespace StardewModdingAPI.Toolkit.Utilities
         [Pure]
         public static string GetRelativePath(string sourceDir, string targetPath)
         {
+#if NET5_0
             return Path.GetRelativePath(sourceDir, targetPath);
+#else
+            // NOTE:
+            // this is a heuristic implementation that works in the cases SMAPI needs it for, but it
+            // doesn't handle all edge cases (e.g. case-sensitivity on Linux, or traversing between
+            // UNC paths on Windows). SMAPI and mods will use the more robust .NET 5 version anyway
+            // though, this is only for compatibility with the mod build package.
+
+            // convert to URIs
+            Uri from = new(sourceDir.TrimEnd(PathUtilities.PossiblePathSeparators) + "/");
+            Uri to = new(targetPath.TrimEnd(PathUtilities.PossiblePathSeparators) + "/");
+            if (from.Scheme != to.Scheme)
+                throw new InvalidOperationException($"Can't get path for '{targetPath}' relative to '{sourceDir}'.");
+
+            // get relative path
+            string rawUrl = Uri.UnescapeDataString(from.MakeRelativeUri(to).ToString());
+            if (rawUrl.StartsWith("file://"))
+                rawUrl = PathUtilities.WindowsUncRoot + rawUrl.Substring("file://".Length);
+            string relative = PathUtilities.NormalizePath(rawUrl);
+
+            // normalize
+            if (relative == "")
+                relative = ".";
+            else
+            {
+                // trim trailing slash from URL
+                if (relative.EndsWith(PathUtilities.PreferredPathSeparator.ToString()))
+                    relative = relative.Substring(0, relative.Length - 1);
+
+                // fix root
+                if (relative.StartsWith("file:") && !targetPath.Contains("file:"))
+                    relative = relative.Substring("file:".Length);
+            }
+
+            return relative;
+#endif
         }
 
         /// <summary>Get whether a path is relative and doesn't try to climb out of its containing folder (e.g. doesn't contain <c>../</c>).</summary>
-- 
cgit 


From 288ef5dc0715339a3a0bf89975a6db7ab7408e2b Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 9 Apr 2022 12:03:30 -0400
Subject: add environment variable form of new CLI args, update docs

---
 docs/release-notes.md   | 2 +-
 docs/technical/smapi.md | 4 +++-
 src/SMAPI/Program.cs    | 6 ++++++
 3 files changed, 10 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index bb30f31a..9fc0d432 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -20,7 +20,6 @@
 * Added `data-*` attributes to the log parser page for external tools.
 * Fixed JSON validator showing incorrect error for update keys without a subkey.
 
-
 ### For mod authors
 This is a big release that includes the new APIs planned for SMAPI 4.0.0, alongside the old ones.
 
@@ -40,6 +39,7 @@ the C# mod that loads them is updated.
     _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
 * Other improvements:
+  * Added [command-line arguments](technical/smapi.md#command-line-arguments) to toggle developer mode (thanks to Tondorian!).
   * Added `IContentPack.ModContent` property.
   * Added `Constants.ContentPath`.
   * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
index 7da1e0f1..e117db2f 100644
--- a/docs/technical/smapi.md
+++ b/docs/technical/smapi.md
@@ -33,11 +33,12 @@ argument | purpose
 `--uninstall` | Preselects the uninstall action, skipping the prompt asking what the user wants to do.
 `--game-path "path"` | Specifies the full path to the folder containing the Stardew Valley executable, skipping automatic detection and any prompt to choose a path. If the path is not valid, the installer displays an error.
 
-SMAPI itself recognises two arguments **on Windows only**, but these are intended for internal use
+SMAPI itself recognises five arguments **on Windows only**, but these are intended for internal use
 or testing and may change without warning. On Linux/macOS, see _environment variables_ below.
 
 argument | purpose
 -------- | -------
+`--developer-mode`<br />`--developer-mode-off` | Enable or disable features intended for mod developers. Currently this only makes `TRACE`-level messages appear in the console.
 `--no-terminal` | The SMAPI launcher won't try to open a terminal window, and SMAPI won't log anything to the console. (Messages will still be written to the log file.)
 `--use-current-shell` | The SMAPI launcher won't try to open a terminal window, but SMAPI will still log to the console. (Messages will still be written to the log file.)
 `--mods-path` | The path to search for mods, if not the standard `Mods` folder. This can be a path relative to the game folder (like `--mods-path "Mods (test)"`) or an absolute path.
@@ -49,6 +50,7 @@ can set temporary environment variables instead. For example:
 
 environment variable | purpose
 -------------------- | -------
+`SMAPI_DEVELOPER_MODE` | Equivalent to `--developer-mode` and `--developer-mode-off` above. The value must be `true` or `false`.
 `SMAPI_MODS_PATH` | Equivalent to `--mods-path` above.
 `SMAPI_NO_TERMINAL` | Equivalent to `--no-terminal` above.
 `SMAPI_USE_CURRENT_SHELL` | Equivalent to `--use-current-shell` above.
diff --git a/src/SMAPI/Program.cs b/src/SMAPI/Program.cs
index 0c9c2d87..b2e213fe 100644
--- a/src/SMAPI/Program.cs
+++ b/src/SMAPI/Program.cs
@@ -200,6 +200,12 @@ namespace StardewModdingAPI
                 // get from environment variables
                 if (string.IsNullOrWhiteSpace(rawModsPath))
                     rawModsPath = Environment.GetEnvironmentVariable("SMAPI_MODS_PATH");
+                if (developerMode is null)
+                {
+                    string rawDeveloperMode = Environment.GetEnvironmentVariable("SMAPI_DEVELOPER_MODE");
+                    if (rawDeveloperMode != null)
+                        developerMode = bool.Parse(rawDeveloperMode);
+                }
 
                 // normalize
                 modsPath = !string.IsNullOrWhiteSpace(rawModsPath)
-- 
cgit 


From 85c769d2a28da67bcc939ec2e6c458a3db81e77c Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 9 Apr 2022 16:57:41 -0400
Subject: update release notes

---
 docs/release-notes.md | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 9fc0d432..0687b888 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -16,6 +16,12 @@
   * Fixed `set_farm_type` console command not updating warps.
 
 ### For the web UI
+* Overhauled log parser UI (thanks to KhloeLeclair!):
+  * Added pagination for big logs.
+  * Added search box to filter the log.
+  * Added option to show/hide content packs in the mod list.
+  * The filter options now stick to the top of the screen when scrolling.
+  * Rewrote rendering to improve performance.
 * Updated the JSON validator/schema for Content Patcher 1.25.0.
 * Added `data-*` attributes to the log parser page for external tools.
 * Fixed JSON validator showing incorrect error for update keys without a subkey.
-- 
cgit 


From 1e61309d3dce484d5b646b1a8d15c825beac813f Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Mon, 11 Apr 2022 22:56:14 -0400
Subject: add IAssetDataForMap.ExtendMap

---
 docs/release-notes.md                              |  1 +
 src/SMAPI/Framework/Content/AssetDataForMap.cs     | 54 +++++++++++++++++++++-
 src/SMAPI/Framework/Content/AssetDataForObject.cs  | 23 +++++++--
 src/SMAPI/Framework/ContentCoordinator.cs          |  3 +-
 .../ContentManagers/BaseContentManager.cs          |  4 ++
 .../ContentManagers/GameContentManager.cs          |  6 +--
 src/SMAPI/Framework/ModHelpers/ContentHelper.cs    | 16 ++++++-
 .../Framework/ModHelpers/GameContentHelper.cs      | 16 ++++++-
 src/SMAPI/Framework/ModHelpers/ModContentHelper.cs | 16 ++++++-
 src/SMAPI/Framework/SCore.cs                       | 14 +++---
 src/SMAPI/IAssetDataForImage.cs                    |  4 +-
 src/SMAPI/IAssetDataForMap.cs                      |  7 +++
 12 files changed, 138 insertions(+), 26 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 0687b888..7379cba3 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -45,6 +45,7 @@ the C# mod that loads them is updated.
     _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
 * Other improvements:
+  * Added `IAssetDataForImage.ExtendMap` to resize maps in asset editors.
   * Added [command-line arguments](technical/smapi.md#command-line-arguments) to toggle developer mode (thanks to Tondorian!).
   * Added `IContentPack.ModContent` property.
   * Added `Constants.ContentPath`.
diff --git a/src/SMAPI/Framework/Content/AssetDataForMap.cs b/src/SMAPI/Framework/Content/AssetDataForMap.cs
index 0425e195..93148277 100644
--- a/src/SMAPI/Framework/Content/AssetDataForMap.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForMap.cs
@@ -4,17 +4,27 @@ using System;
 using System.Collections.Generic;
 using System.Linq;
 using Microsoft.Xna.Framework;
+using StardewModdingAPI.Framework.Reflection;
 using StardewModdingAPI.Toolkit.Utilities;
 using StardewValley;
 using xTile;
+using xTile.Dimensions;
 using xTile.Layers;
 using xTile.Tiles;
+using Rectangle = Microsoft.Xna.Framework.Rectangle;
 
 namespace StardewModdingAPI.Framework.Content
 {
     /// <summary>Encapsulates access and changes to image content being read from a data file.</summary>
     internal class AssetDataForMap : AssetData<Map>, IAssetDataForMap
     {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>Simplifies access to private code.</summary>
+        private readonly Reflector Reflection;
+
+
         /*********
         ** Public methods
         *********/
@@ -24,8 +34,12 @@ 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>
         /// <param name="onDataReplaced">A callback to invoke when the data is replaced (if any).</param>
-        public AssetDataForMap(string locale, IAssetName assetName, Map data, Func<string, string> getNormalizedPath, Action<Map> onDataReplaced)
-            : base(locale, assetName, data, getNormalizedPath, onDataReplaced) { }
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public AssetDataForMap(string locale, IAssetName assetName, Map data, Func<string, string> getNormalizedPath, Action<Map> onDataReplaced, Reflector reflection)
+            : base(locale, assetName, data, getNormalizedPath, onDataReplaced)
+        {
+            this.Reflection = reflection;
+        }
 
         /// <inheritdoc />
         /// <remarks>Derived from <see cref="GameLocation.ApplyMapOverride(Map,string,Rectangle?,Rectangle?)"/> with a few changes:
@@ -137,6 +151,42 @@ namespace StardewModdingAPI.Framework.Content
             }
         }
 
+        /// <inheritdoc />
+        public bool ExtendMap(Map map, int minWidth, int minHeight)
+        {
+            bool resized = false;
+
+            // resize layers
+            foreach (Layer layer in map.Layers)
+            {
+                // check if resize needed
+                if (layer.LayerWidth >= minWidth && layer.LayerHeight >= minHeight)
+                    continue;
+                resized = true;
+
+                // build new tile matrix
+                int width = Math.Max(minWidth, layer.LayerWidth);
+                int height = Math.Max(minHeight, layer.LayerHeight);
+                Tile[,] tiles = new Tile[width, height];
+                for (int x = 0; x < layer.LayerWidth; x++)
+                {
+                    for (int y = 0; y < layer.LayerHeight; y++)
+                        tiles[x, y] = layer.Tiles[x, y];
+                }
+
+                // update fields
+                this.Reflection.GetField<Tile[,]>(layer, "m_tiles").SetValue(tiles);
+                this.Reflection.GetField<TileArray>(layer, "m_tileArray").SetValue(new TileArray(layer, tiles));
+                this.Reflection.GetField<Size>(layer, "m_layerSize").SetValue(new Size(width, height));
+            }
+
+            // resize map
+            if (resized)
+                this.Reflection.GetMethod(map, "UpdateDisplaySize").Invoke();
+
+            return resized;
+        }
+
 
         /*********
         ** Private methods
diff --git a/src/SMAPI/Framework/Content/AssetDataForObject.cs b/src/SMAPI/Framework/Content/AssetDataForObject.cs
index 4a6df64b..bb3966b9 100644
--- a/src/SMAPI/Framework/Content/AssetDataForObject.cs
+++ b/src/SMAPI/Framework/Content/AssetDataForObject.cs
@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Generic;
 using Microsoft.Xna.Framework.Graphics;
+using StardewModdingAPI.Framework.Reflection;
 using xTile;
 
 namespace StardewModdingAPI.Framework.Content
@@ -10,6 +11,13 @@ namespace StardewModdingAPI.Framework.Content
     /// <summary>Encapsulates access and changes to content being read from a data file.</summary>
     internal class AssetDataForObject : AssetData<object>, IAssetData
     {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>Simplifies access to private code.</summary>
+        private readonly Reflector Reflection;
+
+
         /*********
         ** Public methods
         *********/
@@ -18,15 +26,20 @@ namespace StardewModdingAPI.Framework.Content
         /// <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, IAssetName assetName, object data, Func<string, string> getNormalizedPath)
-            : base(locale, assetName, data, getNormalizedPath, onDataReplaced: null) { }
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public AssetDataForObject(string locale, IAssetName assetName, object data, Func<string, string> getNormalizedPath, Reflector reflection)
+            : base(locale, assetName, data, getNormalizedPath, onDataReplaced: null)
+        {
+            this.Reflection = reflection;
+        }
 
         /// <summary>Construct an instance.</summary>
         /// <param name="info">The asset metadata.</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(IAssetInfo info, object data, Func<string, string> getNormalizedPath)
-            : this(info.Locale, info.Name, data, getNormalizedPath) { }
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public AssetDataForObject(IAssetInfo info, object data, Func<string, string> getNormalizedPath, Reflector reflection)
+            : this(info.Locale, info.Name, data, getNormalizedPath, reflection) { }
 
         /// <inheritdoc />
         public IAssetDataForDictionary<TKey, TValue> AsDictionary<TKey, TValue>()
@@ -43,7 +56,7 @@ namespace StardewModdingAPI.Framework.Content
         /// <inheritdoc />
         public IAssetDataForMap AsMap()
         {
-            return new AssetDataForMap(this.Locale, this.Name, this.GetData<Map>(), this.GetNormalizedPath, this.ReplaceWith);
+            return new AssetDataForMap(this.Locale, this.Name, this.GetData<Map>(), this.GetNormalizedPath, this.ReplaceWith, this.Reflection);
         }
 
         /// <inheritdoc />
diff --git a/src/SMAPI/Framework/ContentCoordinator.cs b/src/SMAPI/Framework/ContentCoordinator.cs
index 81820b05..4e48b08c 100644
--- a/src/SMAPI/Framework/ContentCoordinator.cs
+++ b/src/SMAPI/Framework/ContentCoordinator.cs
@@ -727,7 +727,8 @@ namespace StardewModdingAPI.Framework
                     locale: null,
                     assetName: legacyName,
                     data: asset.Data,
-                    getNormalizedPath: this.MainContentManager.AssertAndNormalizeAssetName
+                    getNormalizedPath: this.MainContentManager.AssertAndNormalizeAssetName,
+                    reflection: this.Reflection
                 );
         }
 
diff --git a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
index 4594d235..f1ccab48 100644
--- a/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/BaseContentManager.cs
@@ -32,6 +32,9 @@ 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;
 
@@ -90,6 +93,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
             this.Coordinator = coordinator ?? throw new ArgumentNullException(nameof(coordinator));
             this.Cache = new ContentCache(this, reflection);
             this.Monitor = monitor ?? throw new ArgumentNullException(nameof(monitor));
+            this.Reflection = reflection;
             this.OnDisposing = onDisposing;
             this.IsNamespaced = isNamespaced;
             this.AggressiveMemoryOptimizations = aggressiveMemoryOptimizations;
diff --git a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
index f4e1bda4..e494559d 100644
--- a/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
+++ b/src/SMAPI/Framework/ContentManagers/GameContentManager.cs
@@ -124,7 +124,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
                     IAssetInfo info = new AssetInfo(assetName.LocaleCode, assetName, typeof(T), this.AssertAndNormalizeAssetName);
                     IAssetData asset =
                         this.ApplyLoader<T>(info)
-                        ?? new AssetDataForObject(info, this.RawLoad<T>(assetName, 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;
                 });
@@ -187,7 +187,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
 
             // return matched asset
             return this.TryFixAndValidateLoadedAsset(info, data, loader)
-                ? new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName)
+                ? new AssetDataForObject(info, data, this.AssertAndNormalizeAssetName, this.Reflection)
                 : null;
         }
 
@@ -197,7 +197,7 @@ namespace StardewModdingAPI.Framework.ContentManagers
         /// <param name="asset">The loaded asset.</param>
         private IAssetData ApplyEditors<T>(IAssetInfo info, IAssetData asset)
         {
-            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.
             {
diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
index e72e397e..12ef0439 100644
--- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs
@@ -10,6 +10,7 @@ using System.Linq;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Exceptions;
+using StardewModdingAPI.Framework.Reflection;
 using StardewValley;
 
 namespace StardewModdingAPI.Framework.ModHelpers
@@ -36,6 +37,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <summary>Encapsulates monitoring and logging.</summary>
         private readonly IMonitor Monitor;
 
+        /// <summary>Simplifies access to private code.</summary>
+        private readonly Reflector Reflection;
+
 
         /*********
         ** Accessors
@@ -94,7 +98,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="modID">The unique ID of the relevant mod.</param>
         /// <param name="modName">The friendly mod name for use in errors.</param>
         /// <param name="monitor">Encapsulates monitoring and logging.</param>
-        public ContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IMonitor monitor)
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public ContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IMonitor monitor, Reflector reflection)
             : base(modID)
         {
             string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
@@ -104,6 +109,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, modName, modFolderPath, this.GameContentManager);
             this.ModName = modName;
             this.Monitor = monitor;
+            this.Reflection = reflection;
         }
 
         /// <inheritdoc />
@@ -185,7 +191,13 @@ namespace StardewModdingAPI.Framework.ModHelpers
 
             assetName ??= $"temp/{Guid.NewGuid():N}";
 
-            return new AssetDataForObject(this.CurrentLocale, this.ContentCore.ParseAssetName(assetName, allowLocales: true/* no way to know if it's a game or mod asset here*/), data, this.NormalizeAssetName);
+            return new AssetDataForObject(
+                locale: this.CurrentLocale,
+                assetName: this.ContentCore.ParseAssetName(assetName, allowLocales: true/* no way to know if it's a game or mod asset here*/),
+                data: data,
+                getNormalizedPath: this.NormalizeAssetName,
+                reflection: this.Reflection
+            );
         }
 
 
diff --git a/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs b/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
index 956bac7f..6d0c2f5f 100644
--- a/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/GameContentHelper.cs
@@ -5,6 +5,7 @@ using System.Linq;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Exceptions;
+using StardewModdingAPI.Framework.Reflection;
 using StardewValley;
 
 namespace StardewModdingAPI.Framework.ModHelpers
@@ -27,6 +28,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <summary>Encapsulates monitoring and logging.</summary>
         private readonly IMonitor Monitor;
 
+        /// <summary>Simplifies access to private code.</summary>
+        private readonly Reflector Reflection;
+
 
         /*********
         ** Accessors
@@ -46,7 +50,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="modID">The unique ID of the relevant mod.</param>
         /// <param name="modName">The friendly mod name for use in errors.</param>
         /// <param name="monitor">Encapsulates monitoring and logging.</param>
-        public GameContentHelper(ContentCoordinator contentCore, string modID, string modName, IMonitor monitor)
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public GameContentHelper(ContentCoordinator contentCore, string modID, string modName, IMonitor monitor, Reflector reflection)
             : base(modID)
         {
             string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
@@ -55,6 +60,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.GameContentManager = contentCore.CreateGameContentManager(managedAssetPrefix + ".content");
             this.ModName = modName;
             this.Monitor = monitor;
+            this.Reflection = reflection;
         }
 
         /// <inheritdoc />
@@ -119,7 +125,13 @@ namespace StardewModdingAPI.Framework.ModHelpers
 
             assetName ??= $"temp/{Guid.NewGuid():N}";
 
-            return new AssetDataForObject(this.CurrentLocale, this.ContentCore.ParseAssetName(assetName, allowLocales: true), data, key => this.ParseAssetName(key).Name);
+            return new AssetDataForObject(
+                locale: this.CurrentLocale,
+                assetName: this.ContentCore.ParseAssetName(assetName, allowLocales: true),
+                data: data,
+                getNormalizedPath: key => this.ParseAssetName(key).Name,
+                reflection: this.Reflection
+            );
         }
 
         /// <summary>Get the underlying game content manager.</summary>
diff --git a/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
index 90064354..b149ed82 100644
--- a/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
+++ b/src/SMAPI/Framework/ModHelpers/ModContentHelper.cs
@@ -5,6 +5,7 @@ using Microsoft.Xna.Framework.Content;
 using StardewModdingAPI.Framework.Content;
 using StardewModdingAPI.Framework.ContentManagers;
 using StardewModdingAPI.Framework.Exceptions;
+using StardewModdingAPI.Framework.Reflection;
 using StardewModdingAPI.Utilities;
 
 namespace StardewModdingAPI.Framework.ModHelpers
@@ -27,6 +28,9 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <summary>A case-insensitive lookup of relative paths within the <see cref="ContentManager.RootDirectory"/>.</summary>
         private readonly CaseInsensitivePathCache RelativePathCache;
 
+        /// <summary>Simplifies access to private code.</summary>
+        private readonly Reflector Reflection;
+
 
         /*********
         ** Public methods
@@ -38,7 +42,8 @@ namespace StardewModdingAPI.Framework.ModHelpers
         /// <param name="modName">The friendly mod name for use in errors.</param>
         /// <param name="gameContentManager">The game content manager used for map tilesheets not provided by the mod.</param>
         /// <param name="relativePathCache">A case-insensitive lookup of relative paths within the <paramref name="relativePathCache"/>.</param>
-        public ModContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IContentManager gameContentManager, CaseInsensitivePathCache relativePathCache)
+        /// <param name="reflection">Simplifies access to private code.</param>
+        public ModContentHelper(ContentCoordinator contentCore, string modFolderPath, string modID, string modName, IContentManager gameContentManager, CaseInsensitivePathCache relativePathCache, Reflector reflection)
             : base(modID)
         {
             string managedAssetPrefix = contentCore.GetManagedAssetPrefix(modID);
@@ -47,6 +52,7 @@ namespace StardewModdingAPI.Framework.ModHelpers
             this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, modName, modFolderPath, gameContentManager);
             this.ModName = modName;
             this.RelativePathCache = relativePathCache;
+            this.Reflection = reflection;
         }
 
         /// <inheritdoc />
@@ -83,7 +89,13 @@ namespace StardewModdingAPI.Framework.ModHelpers
                 ? this.RelativePathCache.GetAssetName(relativePath)
                 : $"temp/{Guid.NewGuid():N}";
 
-            return new AssetDataForObject(this.ContentCore.GetLocale(), this.ContentCore.ParseAssetName(relativePath, allowLocales: false), data, key => this.ContentCore.ParseAssetName(key, allowLocales: false).Name);
+            return new AssetDataForObject(
+                locale: this.ContentCore.GetLocale(),
+                assetName: this.ContentCore.ParseAssetName(relativePath, allowLocales: false),
+                data: data,
+                getNormalizedPath: key => this.ContentCore.ParseAssetName(key, allowLocales: false).Name,
+                reflection: this.Reflection
+            );
         }
     }
 }
diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs
index 1a58d84b..364a7632 100644
--- a/src/SMAPI/Framework/SCore.cs
+++ b/src/SMAPI/Framework/SCore.cs
@@ -1754,8 +1754,8 @@ namespace StardewModdingAPI.Framework
                 IManifest manifest = mod.Manifest;
                 IMonitor monitor = this.LogManager.GetMonitor(mod.DisplayName);
                 CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath);
-                GameContentHelper gameContentHelper = new(this.ContentCore, manifest.UniqueID, mod.DisplayName, monitor);
-                IModContentHelper modContentHelper = new ModContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
+                GameContentHelper gameContentHelper = new(this.ContentCore, manifest.UniqueID, mod.DisplayName, monitor, this.Reflection);
+                IModContentHelper modContentHelper = new ModContentHelper(this.ContentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache, this.Reflection);
                 TranslationHelper translationHelper = new(manifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
                 IContentPack contentPack = new ContentPack(mod.DirectoryPath, manifest, modContentHelper, translationHelper, jsonHelper, relativePathCache);
                 mod.SetMod(contentPack, monitor, translationHelper);
@@ -1838,8 +1838,8 @@ namespace StardewModdingAPI.Framework
 
                             CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(packDirPath);
 
-                            GameContentHelper gameContentHelper = new(contentCore, packManifest.UniqueID, packManifest.Name, packMonitor);
-                            IModContentHelper packContentHelper = new ModContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
+                            GameContentHelper gameContentHelper = new(contentCore, packManifest.UniqueID, packManifest.Name, packMonitor, this.Reflection);
+                            IModContentHelper packContentHelper = new ModContentHelper(contentCore, packDirPath, packManifest.UniqueID, packManifest.Name, gameContentHelper.GetUnderlyingContentManager(), relativePathCache, this.Reflection);
                             TranslationHelper packTranslationHelper = new(packManifest.UniqueID, contentCore.GetLocale(), contentCore.Language);
 
                             ContentPack contentPack = new(packDirPath, packManifest, packContentHelper, packTranslationHelper, this.Toolkit.JsonHelper, relativePathCache);
@@ -1852,10 +1852,10 @@ namespace StardewModdingAPI.Framework
                         ICommandHelper commandHelper = new CommandHelper(mod, this.CommandManager);
                         CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath);
 #pragma warning disable CS0612 // deprecated code
-                        ContentHelper contentHelper = new(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor);
+                        ContentHelper contentHelper = new(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, monitor, this.Reflection);
 #pragma warning restore CS0612
-                        GameContentHelper gameContentHelper = new(contentCore, manifest.UniqueID, mod.DisplayName, monitor);
-                        IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache);
+                        GameContentHelper gameContentHelper = new(contentCore, manifest.UniqueID, mod.DisplayName, monitor, this.Reflection);
+                        IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, manifest.UniqueID, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache, this.Reflection);
                         IContentPackHelper contentPackHelper = new ContentPackHelper(manifest.UniqueID, new Lazy<IContentPack[]>(GetContentPacks), CreateFakeContentPack);
                         IDataHelper dataHelper = new DataHelper(manifest.UniqueID, mod.DirectoryPath, jsonHelper);
                         IReflectionHelper reflectionHelper = new ReflectionHelper(manifest.UniqueID, mod.DisplayName, this.Reflection);
diff --git a/src/SMAPI/IAssetDataForImage.cs b/src/SMAPI/IAssetDataForImage.cs
index 388caa68..1416592e 100644
--- a/src/SMAPI/IAssetDataForImage.cs
+++ b/src/SMAPI/IAssetDataForImage.cs
@@ -23,8 +23,8 @@ namespace StardewModdingAPI
         void PatchImage(Texture2D source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMode patchMode = PatchMode.Replace);
 
         /// <summary>Extend the image if needed to fit the given size. Note that this is an expensive operation, creates a new texture instance, and that extending a spritesheet horizontally may cause game errors or bugs.</summary>
-        /// <param name="minWidth">The minimum texture width.</param>
-        /// <param name="minHeight">The minimum texture height.</param>
+        /// <param name="minWidth">The minimum texture width in pixels.</param>
+        /// <param name="minHeight">The minimum texture height in pixels.</param>
         /// <returns>Whether the texture was resized.</returns>
         bool ExtendImage(int minWidth, int minHeight);
     }
diff --git a/src/SMAPI/IAssetDataForMap.cs b/src/SMAPI/IAssetDataForMap.cs
index 89ee28f2..0b637baf 100644
--- a/src/SMAPI/IAssetDataForMap.cs
+++ b/src/SMAPI/IAssetDataForMap.cs
@@ -17,5 +17,12 @@ namespace StardewModdingAPI
         /// <param name="targetArea">The tile area within the target map to overwrite, or <c>null</c> to patch the whole map. The original content within this area will be erased. This must be within the bounds of the existing map.</param>
         /// <param name="patchMode">Indicates how the map should be patched.</param>
         void PatchMap(Map source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMapMode patchMode = PatchMapMode.Overlay);
+
+        /// <summary>Extend the map if needed to fit the given size. Note that this is an expensive operation and resizes the map in-place.</summary>
+        /// <param name="map">The map to resize.</param>
+        /// <param name="minWidth">The minimum map width in tiles.</param>
+        /// <param name="minHeight">The minimum map height in tiles.</param>
+        /// <returns>Whether the map was resized.</returns>
+        bool ExtendMap(Map map, int minWidth, int minHeight);
     }
 }
-- 
cgit 


From 045e4ddf2df278f740903294057a67cac8c95052 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Wed, 13 Apr 2022 22:58:47 -0400
Subject: update release notes (#837)

---
 docs/release-notes.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 7379cba3..2e7b26e1 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -40,10 +40,12 @@ the C# mod that loads them is updated.
 * Major changes:
   * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
     _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
+  * Added [nullable reference type annotations](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0#Nullable_reference_type_annotations) for all APIs.
   * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
   * Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
     _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
+  * Enabled deprecation notices for all deprecated APIs. These will only be shown in `TRACE` logs for at least a month after SMAPI 3.14.0 releases.
 * Other improvements:
   * Added `IAssetDataForImage.ExtendMap` to resize maps in asset editors.
   * Added [command-line arguments](technical/smapi.md#command-line-arguments) to toggle developer mode (thanks to Tondorian!).
@@ -58,6 +60,7 @@ the C# mod that loads them is updated.
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
+  * Fixed null handling in various edge cases.
 
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
-- 
cgit 


From eb125f1994c605704be384ffdcf4da64b88d9405 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 14 Apr 2022 18:14:08 -0400
Subject: fix assembly version conflict error in mod build package

---
 docs/technical/mod-package.md                        | 1 +
 src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj | 6 ++++++
 2 files changed, 7 insertions(+)

(limited to 'docs')

diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
index 4c31f69b..b29f3f72 100644
--- a/docs/technical/mod-package.md
+++ b/docs/technical/mod-package.md
@@ -414,6 +414,7 @@ when you compile it.
 ## Release notes
 ## Upcoming release
 * Added detection for Xbox app game folders.
+* Fixed "_conflicts between different versions of Microsoft.Win32.Registry_" warnings in recent SMAPI versions.
 * Internal refactoring.
 
 ## 4.0.0
diff --git a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
index 82eac7f6..09792d3c 100644
--- a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
+++ b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
@@ -25,6 +25,12 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Build.Utilities.Core" Version="16.10" />
     <PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
+
+    <!--
+      This is imported through Microsoft.Build.Utilities.Core. When installed by a mod, NuGet
+      otherwise imports version 4.3.0 instead of 5.0.0, which conflicts with SMAPI's version.
+    -->
+    <PackageReference Include="Microsoft.Win32.Registry" Version="5.0.0" />
   </ItemGroup>
 
   <ItemGroup>
-- 
cgit 


From 3a777a511d65c1a99237937dce789f98d0dd1933 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 14 Apr 2022 18:15:02 -0400
Subject: update release notes

---
 docs/release-notes.md | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 2e7b26e1..fed92d8d 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -4,6 +4,7 @@
 ## Upcoming release
 ### For players
 * Changes:
+  * When scanning for mod folders, dot-prefixed files are now ignored (thanks to Nuztalgia!).
   * On Linux, SMAPI now fixes many issues with case-sensitive mod paths automatically.
   * On Linux/macOS, added `--use-current-shell` [command-line argument](technical/smapi.md#command-line-arguments) to avoid opening a separate terminal window.
   * Dropped update checks for the unofficial 64-bit patcher (obsolete since SMAPI 3.12.6).
-- 
cgit 


From 43c875c4c225ad248790c29f3abcb787cbbd2d7f Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 14 Apr 2022 19:21:18 -0400
Subject: prepare mod build package 4.0.1 for release

---
 docs/technical/mod-package.md                        | 4 +++-
 src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
index b29f3f72..c632af84 100644
--- a/docs/technical/mod-package.md
+++ b/docs/technical/mod-package.md
@@ -412,7 +412,9 @@ The NuGet package is generated automatically in `StardewModdingAPI.ModBuildConfi
 when you compile it.
 
 ## Release notes
-## Upcoming release
+## 4.0.1
+Released 14 April 2022.
+
 * Added detection for Xbox app game folders.
 * Fixed "_conflicts between different versions of Microsoft.Win32.Registry_" warnings in recent SMAPI versions.
 * Internal refactoring.
diff --git a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
index 09792d3c..c5790186 100644
--- a/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
+++ b/src/SMAPI.ModBuildConfig/SMAPI.ModBuildConfig.csproj
@@ -10,7 +10,7 @@
     <!--NuGet package-->
     <PackageId>Pathoschild.Stardew.ModBuildConfig</PackageId>
     <Title>Build package for SMAPI mods</Title>
-    <Version>4.0.0</Version>
+    <Version>4.0.1</Version>
     <Authors>Pathoschild</Authors>
     <Description>Automates the build configuration for crossplatform Stardew Valley SMAPI mods. For SMAPI 3.13.0 or later.</Description>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-- 
cgit 


From c0d0ad0282169a829ffee4808088ebf434ba498d Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 14 Apr 2022 23:55:08 -0400
Subject: show simplified stack trace for deprecation notices

---
 docs/release-notes.md                     |  1 +
 src/SMAPI/Framework/DeprecationManager.cs | 45 ++++++++++++++++++++++++++++---
 src/SMAPI/Framework/ModRegistry.cs        | 20 +++++++++-----
 3 files changed, 57 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index fed92d8d..01ba6e30 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -57,6 +57,7 @@ the C# mod that loads them is updated.
   * Added `helper.Content.ParseAssetName` to get an `IAssetName` for an arbitrary asset key.
   * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
   * The `ISemanticVersion` comparison methods (`CompareTo`, `IsBetween`, `IsNewerThan`, and `IsOlderThan`) now allow null values. A null version is always considered older than any non-null version per [best practices](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable-1.compareto#remarks).
+  * Deprecation notices now show a shorter stack trace in most cases, so it's clearer where the deprecated code is in the mod.
 * Fixes:
   * Fixed the `SDate` constructor being case-sensitive.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
diff --git a/src/SMAPI/Framework/DeprecationManager.cs b/src/SMAPI/Framework/DeprecationManager.cs
index c80fdce7..37a5c8ef 100644
--- a/src/SMAPI/Framework/DeprecationManager.cs
+++ b/src/SMAPI/Framework/DeprecationManager.cs
@@ -2,6 +2,7 @@ using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Linq;
+using System.Text;
 
 namespace StardewModdingAPI.Framework
 {
@@ -62,7 +63,8 @@ namespace StardewModdingAPI.Framework
                 return;
 
             // queue warning
-            this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity, new StackTrace(skipFrames: 1)));
+            var stack = new StackTrace(skipFrames: 1); // skip this method
+            this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity, stack));
         }
 
         /// <summary>A placeholder method used to track deprecated code for which a separate warning will be shown.</summary>
@@ -100,11 +102,11 @@ namespace StardewModdingAPI.Framework
 
                 // log message
                 if (level == LogLevel.Trace)
-                    this.Monitor.Log($"{message}\n{warning.StackTrace}", level);
+                    this.Monitor.Log($"{message}\n{this.GetSimplifiedStackTrace(warning.StackTrace, warning.Mod)}", level);
                 else
                 {
                     this.Monitor.Log(message, level);
-                    this.Monitor.Log(warning.StackTrace.ToString(), LogLevel.Debug);
+                    this.Monitor.Log(this.GetSimplifiedStackTrace(warning.StackTrace, warning.Mod), LogLevel.Debug);
                 }
             }
 
@@ -128,5 +130,42 @@ namespace StardewModdingAPI.Framework
             this.LoggedDeprecations.Add(key);
             return true;
         }
+
+        /// <summary>Get the simplest stack trace which shows where in the mod the deprecated code was called from.</summary>
+        /// <param name="stack">The stack trace.</param>
+        /// <param name="mod">The mod for which to show a stack trace.</param>
+        private string GetSimplifiedStackTrace(StackTrace stack, IModMetadata? mod)
+        {
+            // unknown mod, show entire stack trace
+            if (mod == null)
+                return stack.ToString();
+
+            // get frame info
+            var frames = stack
+                .GetFrames()
+                .Select(frame => (Frame: frame, Mod: this.ModRegistry.GetFrom(frame)))
+                .ToArray();
+            var modIds = new HashSet<string>(
+                from frame in frames
+                let id = frame.Mod?.Manifest.UniqueID
+                where id != null
+                select id
+            );
+
+            // can't filter to the target mod
+            if (modIds.Count != 1 || !modIds.Contains(mod.Manifest.UniqueID))
+                return stack.ToString();
+
+            // get stack frames for the target mod, plus one for context
+            var framesStartingAtMod = frames.SkipWhile(p => p.Mod == null).ToArray();
+            var displayFrames = framesStartingAtMod.TakeWhile(p => p.Mod != null).ToArray();
+            displayFrames = displayFrames.Concat(framesStartingAtMod.Skip(displayFrames.Length).Take(1)).ToArray();
+
+            // build stack trace
+            StringBuilder str = new();
+            foreach (var frame in displayFrames)
+                str.Append(new StackTrace(frame.Frame));
+            return str.ToString().TrimEnd();
+        }
     }
 }
diff --git a/src/SMAPI/Framework/ModRegistry.cs b/src/SMAPI/Framework/ModRegistry.cs
index de16a780..449dccb1 100644
--- a/src/SMAPI/Framework/ModRegistry.cs
+++ b/src/SMAPI/Framework/ModRegistry.cs
@@ -59,7 +59,7 @@ namespace StardewModdingAPI.Framework
 
         /// <summary>Get metadata for a loaded mod.</summary>
         /// <param name="uniqueID">The mod's unique ID.</param>
-        /// <returns>Returns the matching mod's metadata, or <c>null</c> if not found.</returns>
+        /// <returns>Returns the mod's metadata, or <c>null</c> if not found.</returns>
         public IModMetadata? Get(string uniqueID)
         {
             // normalize search ID
@@ -73,7 +73,7 @@ namespace StardewModdingAPI.Framework
 
         /// <summary>Get the mod metadata from one of its assemblies.</summary>
         /// <param name="type">The type to check.</param>
-        /// <returns>Returns the mod name, or <c>null</c> if the type isn't part of a known mod.</returns>
+        /// <returns>Returns the mod's metadata, or <c>null</c> if the type isn't part of a known mod.</returns>
         public IModMetadata? GetFrom(Type? type)
         {
             // null
@@ -89,8 +89,17 @@ namespace StardewModdingAPI.Framework
             return null;
         }
 
-        /// <summary>Get the friendly name for the closest assembly registered as a source of deprecation warnings.</summary>
-        /// <returns>Returns the source name, or <c>null</c> if no registered assemblies were found.</returns>
+        /// <summary>Get the mod metadata from a stack frame, if any.</summary>
+        /// <param name="frame">The stack frame to check.</param>
+        /// <returns>Returns the mod's metadata, or <c>null</c> if the frame isn't part of a known mod.</returns>
+        public IModMetadata? GetFrom(StackFrame frame)
+        {
+            MethodBase? method = frame.GetMethod();
+            return this.GetFrom(method?.ReflectedType);
+        }
+
+        /// <summary>Get the mod metadata from the closest assembly registered as a source of deprecation warnings.</summary>
+        /// <returns>Returns the mod's metadata, or <c>null</c> if no registered assemblies were found.</returns>
         public IModMetadata? GetFromStack()
         {
             // get stack frames
@@ -100,8 +109,7 @@ namespace StardewModdingAPI.Framework
             // search stack for a source assembly
             foreach (StackFrame frame in frames)
             {
-                MethodBase? method = frame.GetMethod();
-                IModMetadata? mod = this.GetFrom(method?.ReflectedType);
+                IModMetadata? mod = this.GetFrom(frame);
                 if (mod != null)
                     return mod;
             }
-- 
cgit 


From 9ba06704077c32f84aa4c4aeff8b75e66e1c0486 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 16 Apr 2022 11:21:44 -0400
Subject: fix Nexus API key needed to launch web project locally

---
 docs/release-notes.md                              |  3 +++
 .../Framework/Clients/Nexus/DisabledNexusClient.cs | 31 ++++++++++++++++++++++
 src/SMAPI.Web/Startup.cs                           | 23 ++++++++++------
 3 files changed, 49 insertions(+), 8 deletions(-)
 create mode 100644 src/SMAPI.Web/Framework/Clients/Nexus/DisabledNexusClient.cs

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 01ba6e30..de30a23b 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -64,6 +64,9 @@ the C# mod that loads them is updated.
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
   * Fixed null handling in various edge cases.
 
+### For SMAPI contributors
+* You no longer need a Nexus API key to launch the SMAPI web project locally.
+
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
 
diff --git a/src/SMAPI.Web/Framework/Clients/Nexus/DisabledNexusClient.cs b/src/SMAPI.Web/Framework/Clients/Nexus/DisabledNexusClient.cs
new file mode 100644
index 00000000..6edd5f64
--- /dev/null
+++ b/src/SMAPI.Web/Framework/Clients/Nexus/DisabledNexusClient.cs
@@ -0,0 +1,31 @@
+using System.Threading.Tasks;
+using StardewModdingAPI.Toolkit.Framework.UpdateData;
+
+namespace StardewModdingAPI.Web.Framework.Clients.Nexus
+{
+    /// <summary>A client for the Nexus website which does nothing, used for local development.</summary>
+    internal class DisabledNexusClient : INexusClient
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <inheritdoc />
+        public ModSiteKey SiteKey => ModSiteKey.Nexus;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get update check info about a mod.</summary>
+        /// <param name="id">The mod ID.</param>
+        public Task<IModPage?> GetModData(string id)
+        {
+            return Task.FromResult<IModPage?>(
+                new GenericModPage(ModSiteKey.Nexus, id).SetError(RemoteModStatus.TemporaryError, "The Nexus client is currently disabled due to the configuration.")
+            );
+        }
+
+        /// <inheritdoc />
+        public void Dispose() { }
+    }
+}
diff --git a/src/SMAPI.Web/Startup.cs b/src/SMAPI.Web/Startup.cs
index 98dbca5e..2693aa90 100644
--- a/src/SMAPI.Web/Startup.cs
+++ b/src/SMAPI.Web/Startup.cs
@@ -128,14 +128,21 @@ namespace StardewModdingAPI.Web
                     modUrlFormat: api.ModDropModPageUrl
                 ));
 
-                services.AddSingleton<INexusClient>(new NexusClient(
-                    webUserAgent: userAgent,
-                    webBaseUrl: api.NexusBaseUrl,
-                    webModUrlFormat: api.NexusModUrlFormat,
-                    webModScrapeUrlFormat: api.NexusModScrapeUrlFormat,
-                    apiAppVersion: version,
-                    apiKey: api.NexusApiKey
-                ));
+                if (!string.IsNullOrWhiteSpace(api.NexusApiKey))
+                {
+                    services.AddSingleton<INexusClient>(new NexusClient(
+                        webUserAgent: userAgent,
+                        webBaseUrl: api.NexusBaseUrl,
+                        webModUrlFormat: api.NexusModUrlFormat,
+                        webModScrapeUrlFormat: api.NexusModScrapeUrlFormat,
+                        apiAppVersion: version,
+                        apiKey: api.NexusApiKey
+                    ));
+                }
+                else
+                {
+                    services.AddSingleton<INexusClient>(new DisabledNexusClient());
+                }
 
                 services.AddSingleton<IPastebinClient>(new PastebinClient(
                     baseUrl: api.PastebinBaseUrl,
-- 
cgit 


From e7fd95aafd044d7b8c95b93d0618324254db4eff Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 16 Apr 2022 13:04:16 -0400
Subject: update release notes

---
 docs/release-notes.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index de30a23b..75c1941e 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -17,10 +17,11 @@
   * Fixed `set_farm_type` console command not updating warps.
 
 ### For the web UI
-* Overhauled log parser UI (thanks to KhloeLeclair!):
+* Improved log parser UI (thanks to KhloeLeclair!):
   * Added pagination for big logs.
   * Added search box to filter the log.
   * Added option to show/hide content packs in the mod list.
+  * Added jump links in the sidebar.
   * The filter options now stick to the top of the screen when scrolling.
   * Rewrote rendering to improve performance.
 * Updated the JSON validator/schema for Content Patcher 1.25.0.
-- 
cgit 


From d486d940bae57f627fbe3210bbfa611a5586c8e8 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sat, 16 Apr 2022 19:17:16 -0400
Subject: temporarily disable Pintail by default pending out parameter fix

---
 docs/release-notes.md                 | 4 ++--
 src/SMAPI/Framework/Models/SConfig.cs | 2 +-
 src/SMAPI/SMAPI.config.json           | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 75c1941e..0c14360b 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -44,8 +44,8 @@ the C# mod that loads them is updated.
     _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
   * Added [nullable reference type annotations](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0#Nullable_reference_type_annotations) for all APIs.
   * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
-  * Overhauled [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
-    _This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
+  * Added optional overhaul of [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
+    _This is experimental (you can enable it via `UsePintail` in `smapi-internal/config.json`). This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
   * Enabled deprecation notices for all deprecated APIs. These will only be shown in `TRACE` logs for at least a month after SMAPI 3.14.0 releases.
 * Other improvements:
diff --git a/src/SMAPI/Framework/Models/SConfig.cs b/src/SMAPI/Framework/Models/SConfig.cs
index 1a43c1fc..af2e1035 100644
--- a/src/SMAPI/Framework/Models/SConfig.cs
+++ b/src/SMAPI/Framework/Models/SConfig.cs
@@ -23,7 +23,7 @@ namespace StardewModdingAPI.Framework.Models
             [nameof(LogNetworkTraffic)] = false,
             [nameof(RewriteMods)] = true,
             [nameof(AggressiveMemoryOptimizations)] = false,
-            [nameof(UsePintail)] = true
+            [nameof(UsePintail)] = false
         };
 
         /// <summary>The default values for <see cref="SuppressUpdateChecks"/>, to log changes if different.</summary>
diff --git a/src/SMAPI/SMAPI.config.json b/src/SMAPI/SMAPI.config.json
index 065dfa8c..a317e6b8 100644
--- a/src/SMAPI/SMAPI.config.json
+++ b/src/SMAPI/SMAPI.config.json
@@ -50,7 +50,7 @@ copy all the settings, or you may cause bugs due to overridden changes in future
      * Whether to use the experimental Pintail API proxying library, instead of the original
      * proxying built into SMAPI itself.
      */
-    "UsePintail": true,
+    "UsePintail": false,
 
     /**
      * Whether to add a section to the 'mod issues' list for mods which directly use potentially
-- 
cgit 


From 9939061615c41fabca004bf8f5b6f2b018a40b06 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Tue, 19 Apr 2022 19:26:12 -0400
Subject: fix typo

---
 docs/technical/smapi.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
index e117db2f..789ea20b 100644
--- a/docs/technical/smapi.md
+++ b/docs/technical/smapi.md
@@ -83,7 +83,7 @@ folder before compiling.
 ## Prepare a release
 ### On any platform
 **⚠ Ideally we'd have one set of instructions for all platforms. The instructions in this section
-will produce a fully functional release for all supported platfrms, _except_ that the application
+will produce a fully functional release for all supported platforms, _except_ that the application
 icon for SMAPI on Windows will disappear due to [.NET runtime bug
 3828](https://github.com/dotnet/runtime/issues/3828). Until that's fixed, see the _[on
 Windows](#on-windows)_ section below to create a build that retains the icon.**
-- 
cgit 


From 6a43171e9242e53e299b38dd88370d7070d9186e Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Tue, 26 Apr 2022 23:38:16 -0400
Subject: re-enable Pintail by default

---
 docs/release-notes.md                 | 4 ++--
 src/SMAPI/Framework/Models/SConfig.cs | 2 +-
 src/SMAPI/SMAPI.config.json           | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 0c14360b..fc7e4918 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -44,8 +44,8 @@ the C# mod that loads them is updated.
     _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
   * Added [nullable reference type annotations](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0#Nullable_reference_type_annotations) for all APIs.
   * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
-  * Added optional overhaul of [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
-    _This is experimental (you can enable it via `UsePintail` in `smapi-internal/config.json`). This adds support for many previously unsupported cases: proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. Existing mod APIs should work fine as-is._
+  * Improved [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
+    _This adds support for proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. This is an internal change, you don't need to do anything different in your mod code._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
   * Enabled deprecation notices for all deprecated APIs. These will only be shown in `TRACE` logs for at least a month after SMAPI 3.14.0 releases.
 * Other improvements:
diff --git a/src/SMAPI/Framework/Models/SConfig.cs b/src/SMAPI/Framework/Models/SConfig.cs
index af2e1035..1a43c1fc 100644
--- a/src/SMAPI/Framework/Models/SConfig.cs
+++ b/src/SMAPI/Framework/Models/SConfig.cs
@@ -23,7 +23,7 @@ namespace StardewModdingAPI.Framework.Models
             [nameof(LogNetworkTraffic)] = false,
             [nameof(RewriteMods)] = true,
             [nameof(AggressiveMemoryOptimizations)] = false,
-            [nameof(UsePintail)] = false
+            [nameof(UsePintail)] = true
         };
 
         /// <summary>The default values for <see cref="SuppressUpdateChecks"/>, to log changes if different.</summary>
diff --git a/src/SMAPI/SMAPI.config.json b/src/SMAPI/SMAPI.config.json
index a317e6b8..065dfa8c 100644
--- a/src/SMAPI/SMAPI.config.json
+++ b/src/SMAPI/SMAPI.config.json
@@ -50,7 +50,7 @@ copy all the settings, or you may cause bugs due to overridden changes in future
      * Whether to use the experimental Pintail API proxying library, instead of the original
      * proxying built into SMAPI itself.
      */
-    "UsePintail": false,
+    "UsePintail": true,
 
     /**
      * Whether to add a section to the 'mod issues' list for mods which directly use potentially
-- 
cgit 


From f507bd0f9cebe68fa2adf176740a0d00b3e6f884 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Fri, 29 Apr 2022 22:55:12 -0400
Subject: set SMAPI version from main build script

---
 build/unix/prepare-install-package.sh     | 21 ++++++++++++++-------
 build/windows/prepare-install-package.ps1 | 20 ++++++++++++++------
 docs/technical/smapi.md                   | 22 ++++++++++------------
 3 files changed, 38 insertions(+), 25 deletions(-)

(limited to 'docs')

diff --git a/build/unix/prepare-install-package.sh b/build/unix/prepare-install-package.sh
index 9dd24b82..e9b413b4 100755
--- a/build/unix/prepare-install-package.sh
+++ b/build/unix/prepare-install-package.sh
@@ -28,6 +28,20 @@ declare -A msBuildPlatformNames=(["linux"]="Unix" ["macOS"]="OSX" ["windows"]="W
 cd "`dirname "$0"`/../.."
 
 
+##########
+## Set version
+##########
+# get version number
+version="$1"
+if [ $# -eq 0 ]; then
+    echo "SMAPI release version (like '4.0.0'):"
+    read version
+fi
+
+# set version
+. ${0%/*}/set-smapi-version.sh "$version"
+
+
 ##########
 ## Clear old build files
 ##########
@@ -190,13 +204,6 @@ done
 ##########
 ## Create release zips
 ##########
-# get version number
-version="$1"
-if [ $# -eq 0 ]; then
-    echo "SMAPI release version (like '4.0.0'):"
-    read version
-fi
-
 # rename folders
 mv "$packagePath" "bin/SMAPI $version installer"
 mv "$packageDevPath" "bin/SMAPI $version installer for developers"
diff --git a/build/windows/prepare-install-package.ps1 b/build/windows/prepare-install-package.ps1
index b6a23124..5a1e0bcc 100644
--- a/build/windows/prepare-install-package.ps1
+++ b/build/windows/prepare-install-package.ps1
@@ -12,6 +12,20 @@
 
 . "$PSScriptRoot\lib\in-place-regex.ps1"
 
+
+##########
+## Set version
+##########
+# get version number
+$version = $args[0]
+if (!$version) {
+    $version = Read-Host "SMAPI release version (like '4.0.0')"
+}
+
+# set version
+. "$PSScriptRoot/set-smapi-version.ps1" "$version"
+
+
 ##########
 ## Constants
 ##########
@@ -197,12 +211,6 @@ foreach ($folder in $folders) {
 ###########
 ### Create release zips
 ###########
-# get version number
-$version = $args[0]
-if (!$version) {
-    $version = Read-Host "SMAPI release version (like '4.0.0')"
-}
-
 # rename folders
 mv "$packagePath" "bin/SMAPI $version installer"
 mv "$packageDevPath" "bin/SMAPI $version installer for developers"
diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
index 789ea20b..4d75aef2 100644
--- a/docs/technical/smapi.md
+++ b/docs/technical/smapi.md
@@ -120,8 +120,10 @@ Windows](#on-windows)_ section below to create a build that retains the icon.**
 2. Launch the game through the Steam UI.
 
 ### Prepare the release
-1. Run `build/unix/set-smapi-version.sh` to set the SMAPI version. Make sure you use a [semantic
-   version](https://semver.org). Recommended format:
+1. Run `build/unix/prepare-install-package.sh VERSION_HERE` to create the release package in the
+   root `bin` folder.
+
+   Make sure you use a [semantic version](https://semver.org). Recommended format:
 
    build type | format                   | example
    :--------- | :----------------------- | :------
@@ -129,9 +131,6 @@ Windows](#on-windows)_ section below to create a build that retains the icon.**
    prerelease | `<version>-beta.<date>`  | `4.0.0-beta.20251230`
    release    | `<version>`              | `4.0.0`
 
-2. Run `build/unix/prepare-install-package.sh` to create the release package in the root `bin`
-   folder.
-
 ### On Windows
 #### First-time setup
 1. Set up Windows Subsystem for Linux (WSL):
@@ -147,8 +146,10 @@ Windows](#on-windows)_ section below to create a build that retains the icon.**
    ```
 
 ### Prepare the release
-1. Run `build/windows/set-smapi-version.ps1` in PowerShell to set the SMAPI version. Make sure you
-   use a [semantic version](https://semver.org). Recommended format:
+1. Run `build/windows/prepare-install-package.ps1 VERSION_HERE` in PowerShell to create the release
+   package folders in the root `bin` folder.
+
+   Make sure you use a [semantic version](https://semver.org). Recommended format:
 
    build type | format                   | example
    :--------- | :----------------------- | :------
@@ -156,12 +157,9 @@ Windows](#on-windows)_ section below to create a build that retains the icon.**
    prerelease | `<version>-beta.<date>`  | `4.0.0-beta.20251230`
    release    | `<version>`              | `4.0.0`
 
-2. Run `build/windows/prepare-install-package.ps1` in PowerShell to create the release package
-   folders in the root `bin` folder.
-
-3. Launch WSL and run this script:
+2. Launch WSL and run this script:
    ```bash
-   # edit to match the build created in steps 1-2
+   # edit to match the build created in steps 1
    # In WSL, `/mnt/c/example` accesses `C:\example` on the Windows filesystem.
    version="4.0.0"
    binFolder="/mnt/e/source/_Stardew/SMAPI/bin"
-- 
cgit 


From 0e4aa65708df7ca4096b9019428d9fccabd37384 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sun, 1 May 2022 17:33:41 -0400
Subject: fix crossplatform build scripts

---
 build/unix/prepare-install-package.sh     | 22 ++++-------
 build/windows/prepare-install-package.ps1 | 66 +++++++++++++++++++------------
 docs/technical/smapi.md                   |  3 ++
 3 files changed, 51 insertions(+), 40 deletions(-)

(limited to 'docs')

diff --git a/build/unix/prepare-install-package.sh b/build/unix/prepare-install-package.sh
index e9b413b4..9b195f37 100755
--- a/build/unix/prepare-install-package.sh
+++ b/build/unix/prepare-install-package.sh
@@ -9,7 +9,7 @@
 
 
 ##########
-## Constants
+## Fetch values
 ##########
 # paths
 gamePath="/home/pathoschild/Stardew Valley"
@@ -21,25 +21,18 @@ folders=("linux" "macOS" "windows")
 declare -A runtimes=(["linux"]="linux-x64" ["macOS"]="osx-x64" ["windows"]="win-x64")
 declare -A msBuildPlatformNames=(["linux"]="Unix" ["macOS"]="OSX" ["windows"]="Windows_NT")
 
-
-##########
-## Move to SMAPI root
-##########
-cd "`dirname "$0"`/../.."
-
-
-##########
-## Set version
-##########
-# get version number
+# version number
 version="$1"
 if [ $# -eq 0 ]; then
     echo "SMAPI release version (like '4.0.0'):"
     read version
 fi
 
-# set version
-. ${0%/*}/set-smapi-version.sh "$version"
+
+##########
+## Move to SMAPI root
+##########
+cd "`dirname "$0"`/../.."
 
 
 ##########
@@ -56,6 +49,7 @@ echo ""
 ##########
 ## Compile files
 ##########
+. ${0%/*}/set-smapi-version.sh "$version"
 for folder in ${folders[@]}; do
     runtime=${runtimes[$folder]}
     msbuildPlatformName=${msBuildPlatformNames[$folder]}
diff --git a/build/windows/prepare-install-package.ps1 b/build/windows/prepare-install-package.ps1
index 5a1e0bcc..5e116019 100644
--- a/build/windows/prepare-install-package.ps1
+++ b/build/windows/prepare-install-package.ps1
@@ -1,33 +1,19 @@
 #
 #
 # This is the PowerShell equivalent of ../unix/prepare-install-package.sh, *except* that it doesn't
-# set Linux permissions, create the install.dat files, or create the final zip. Due to limitations
-# in PowerShell, the final changes are handled by the windows/finalize-install-package.sh file in
-# WSL.
+# set Linux permissions, create the install.dat files, or create the final zip (unless you specify
+# --windows-only). Due to limitations in PowerShell, the final changes are handled by the
+# windows/finalize-install-package.sh file in WSL.
 #
 # When making changes, make sure to update ../unix/prepare-install-package.ps1 too.
 #
 #
 
-
-. "$PSScriptRoot\lib\in-place-regex.ps1"
+. "$PSScriptRoot/lib/in-place-regex.ps1"
 
 
 ##########
-## Set version
-##########
-# get version number
-$version = $args[0]
-if (!$version) {
-    $version = Read-Host "SMAPI release version (like '4.0.0')"
-}
-
-# set version
-. "$PSScriptRoot/set-smapi-version.ps1" "$version"
-
-
-##########
-## Constants
+## Fetch values
 ##########
 # paths
 $gamePath = "C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley"
@@ -39,6 +25,23 @@ $folders = "linux", "macOS", "windows"
 $runtimes = @{ linux = "linux-x64"; macOS = "osx-x64"; windows = "win-x64" }
 $msBuildPlatformNames = @{ linux = "Unix"; macOS = "OSX"; windows = "Windows_NT" }
 
+# version number
+$version = $args[0]
+if (!$version) {
+    $version = Read-Host "SMAPI release version (like '4.0.0')"
+}
+
+# Windows-only build
+$windowsOnly = $false
+foreach ($arg in $args) {
+    if ($arg -eq "--windows-only") {
+        $windowsOnly = $true
+        $folders = "windows"
+        $runtimes = @{ windows = "win-x64" }
+        $msBuildPlatformNames = @{ windows = "Windows_NT" }
+    }
+}
+
 
 ##########
 ## Move to SMAPI root
@@ -62,7 +65,8 @@ echo ""
 ##########
 ## Compile files
 ##########
-ForEach ($folder in $folders) {
+. "$PSScriptRoot/set-smapi-version.ps1" "$version"
+foreach ($folder in $folders) {
     $runtime = $runtimes[$folder]
     $msbuildPlatformName = $msBuildPlatformNames[$folder]
 
@@ -106,6 +110,10 @@ foreach ($folder in $folders) {
 
 # copy base installer files
 foreach ($name in @("install on Linux.sh", "install on macOS.command", "install on Windows.bat", "README.txt")) {
+    if ($windowsOnly -and ($name -eq "install on Linux.sh" -or $name -eq "install on macOS.command")) {
+        continue;
+    }
+
     cp "$installAssets/$name" "$packagePath"
 }
 
@@ -199,11 +207,14 @@ foreach ($folder in $folders) {
     In-Place-Regex -Path "$packagePath/internal/$folder/bundle/smapi-internal/config.json" -Search "`"DeveloperMode`": true" -Replace "`"DeveloperMode`": false"
 
     # convert bundle folder into final 'install.dat' files
-    foreach ($path in @("$packagePath/internal/$folder", "$packageDevPath/internal/$folder"))
+    if ($windowsOnly)
     {
-        Compress-Archive -Path "$path/bundle/*" -CompressionLevel Optimal -DestinationPath "$path/install.zip"
-        mv "$path/install.zip" "$path/install.dat"
-        rm -Recurse -Force "$path/bundle"
+        foreach ($path in @("$packagePath/internal/$folder", "$packageDevPath/internal/$folder"))
+        {
+            Compress-Archive -Path "$path/bundle/*" -CompressionLevel Optimal -DestinationPath "$path/install.zip"
+            mv "$path/install.zip" "$path/install.dat"
+            rm -Recurse -Force "$path/bundle"
+        }
     }
 }
 
@@ -216,8 +227,11 @@ mv "$packagePath" "bin/SMAPI $version installer"
 mv "$packageDevPath" "bin/SMAPI $version installer for developers"
 
 # package files
-Compress-Archive -Path "bin/SMAPI $version installer" -DestinationPath "bin/SMAPI $version installer.zip" -CompressionLevel Optimal
-Compress-Archive -Path "bin/SMAPI $version installer for developers" -DestinationPath "bin/SMAPI $version installer for developers.zip" -CompressionLevel Optimal
+if ($windowsOnly)
+{
+    Compress-Archive -Path "bin/SMAPI $version installer" -DestinationPath "bin/SMAPI $version installer.zip" -CompressionLevel Optimal
+    Compress-Archive -Path "bin/SMAPI $version installer for developers" -DestinationPath "bin/SMAPI $version installer for developers.zip" -CompressionLevel Optimal
+}
 
 echo ""
 echo "Done! See docs/technical/smapi.md to create the release zips."
diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
index 4d75aef2..44b6e49f 100644
--- a/docs/technical/smapi.md
+++ b/docs/technical/smapi.md
@@ -166,5 +166,8 @@ Windows](#on-windows)_ section below to create a build that retains the icon.**
    build/windows/finalize-install-package.sh "$version" "$binFolder"
    ```
 
+Note: to prepare a test Windows-only build, you can pass `--windows-only` in the first step and
+skip the second one.
+
 ## Release notes
 See [release notes](../release-notes.md).
-- 
cgit 


From f78093bdb58d477b400cde3f19b70ffd6ddf833d Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Sun, 1 May 2022 17:39:57 -0400
Subject: prepare for release

---
 build/common.targets                         |  2 +-
 docs/release-notes.md                        | 64 ++++++++++++++--------------
 src/SMAPI.Mods.ConsoleCommands/manifest.json |  4 +-
 src/SMAPI.Mods.ErrorHandler/manifest.json    |  4 +-
 src/SMAPI.Mods.SaveBackup/manifest.json      |  4 +-
 src/SMAPI/Constants.cs                       |  2 +-
 6 files changed, 41 insertions(+), 39 deletions(-)

(limited to 'docs')

diff --git a/build/common.targets b/build/common.targets
index c04546d0..a8dda9e0 100644
--- a/build/common.targets
+++ b/build/common.targets
@@ -1,7 +1,7 @@
 <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <PropertyGroup>
     <!--set general build properties -->
-    <Version>3.13.4</Version>
+    <Version>3.14.0</Version>
     <Product>SMAPI</Product>
     <LangVersion>latest</LangVersion>
     <AssemblySearchPaths>$(AssemblySearchPaths);{GAC}</AssemblySearchPaths>
diff --git a/docs/release-notes.md b/docs/release-notes.md
index fc7e4918..499c1d9b 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,61 +1,59 @@
 ← [README](README.md)
 
 # Release notes
-## Upcoming release
+## 3.14.0
+Released 01 May 2022 for Stardew Valley 1.5.6 or later. See [release highlights](https://www.patreon.com/posts/65265507).
+
 ### For players
-* Changes:
-  * When scanning for mod folders, dot-prefixed files are now ignored (thanks to Nuztalgia!).
-  * On Linux, SMAPI now fixes many issues with case-sensitive mod paths automatically.
+This is a big update, but existing mods should all work fine. If the latest version of a mod breaks in SMAPI 3.14, please report it [on the SMAPI mod page](https://www.nexusmods.com/stardewvalley/mods/2400?tab=posts).
+
+* Improvements:
+  * SMAPI now ignores dot-prefixed files when searching for mod folders (thanks to Nuztalgia!).
+  * On Linux, SMAPI now fixes many case-sensitive mod path issues automatically.
   * On Linux/macOS, added `--use-current-shell` [command-line argument](technical/smapi.md#command-line-arguments) to avoid opening a separate terminal window.
-  * Dropped update checks for the unofficial 64-bit patcher (obsolete since SMAPI 3.12.6).
+  * Improved performance in some cases.
   * Improved translations. Thanks to ChulkyBow (updated Ukrainian)!
+  * Dropped update checks for the unofficial 64-bit patcher (obsolete since SMAPI 3.12.6).
 * Fixes:
   * Fixed some movie theater textures not translated when loaded through SMAPI (specifically assets with the `_international` suffix).
   * Fixed the warning text when a mod causes an asset load conflict with itself.
   * Fixed `--no-terminal` [command-line argument](technical/smapi.md#command-line-arguments) on Linux/macOS still opening a terminal window, even if nothing is logged to it (thanks to Ryhon0!).
   * Fixed `player_add` console command not handling journal scraps and secret notes correctly.
   * Fixed `set_farm_type` console command not updating warps.
-
-### For the web UI
-* Improved log parser UI (thanks to KhloeLeclair!):
-  * Added pagination for big logs.
-  * Added search box to filter the log.
-  * Added option to show/hide content packs in the mod list.
-  * Added jump links in the sidebar.
-  * The filter options now stick to the top of the screen when scrolling.
-  * Rewrote rendering to improve performance.
-* Updated the JSON validator/schema for Content Patcher 1.25.0.
-* Added `data-*` attributes to the log parser page for external tools.
-* Fixed JSON validator showing incorrect error for update keys without a subkey.
+* For the web UI:
+  * Improved log parser UI (thanks to KhloeLeclair!):
+    * Added pagination for big logs.
+    * Added search box to filter the log.
+    * Added option to show/hide content packs in the mod list.
+    * Added jump links in the sidebar.
+    * The filter options now stick to the top of the screen when scrolling.
+    * Rewrote rendering to improve performance.
 
 ### For mod authors
-This is a big release that includes the new APIs planned for SMAPI 4.0.0, alongside the old ones.
+This is a big release that includes the new features planned for SMAPI 4.0.0.
 
-For C# mod authors: SMAPI 4.0.0 will release _no sooner_ than August 2022 (and later if needed to
-update open-source mods). At that point it will **remove all deprecated APIs and break C# mods
-which haven't updated yet**. See [_Migrate to SMAPI 4.0_](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0)
-for help updating your mod code. (You can update now, there's no need to wait for 4.0.0.)
+For C# mod authors: your mods should still work fine in SMAPI 3.14.0. However you should review the [migration to SMAPI 4.0](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0) guide and update your mods when possible. Deprecated code will be removed when SMAPI 4.0.0 releases later this year (no sooner than August 2022), and break any mods which haven't updated by that time. You can update affected mods now, there's no need to wait for 4.0.0.
 
-For content pack authors: SMAPI 4.0.0 won't affect content packs. They should work fine as long as
+For content pack authors: SMAPI 3.14.0 and 4.0.0 don't affect content packs. They should work fine as long as
 the C# mod that loads them is updated.
 
 * Major changes:
   * Added [content events](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events#Content), which will replace `IAssetEditor` and `IAssetLoader` in SMAPI 4.0.0.  
     _These include new features not supported by the old API like load conflict resolution, edit priority, and content pack labels. They also support new cases like easily detecting when an asset has changed, and avoid data corruption issues in some edge cases._
   * Added [nullable reference type annotations](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0#Nullable_reference_type_annotations) for all APIs.
-  * Added `helper.GameContent` and `helper.ModContent`, which will replace `helper.Content` in SMAPI 4.0.0.
+  * Added [`helper.GameContent` and `helper.ModContent`](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_4.0#Content_loading_API), which will replace `helper.Content` in SMAPI 4.0.0.
   * Improved [mod-provided API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations#Mod-provided_APIs) proxying (thanks to Shockah!).  
-    _This adds support for proxied interfaces in return values or input arguments, proxied enums if their values match, generic methods, and more. This is an internal change, you don't need to do anything different in your mod code._
+    _This adds support for custom interfaces in return values or input arguments, custom enums if their values match, generic methods, and more. This is an internal change, you don't need to do anything different in your mod code._
   * Mod files loaded through SMAPI APIs (including `helper.Content.Load`) are now case-insensitive, even on Linux.
   * Enabled deprecation notices for all deprecated APIs. These will only be shown in `TRACE` logs for at least a month after SMAPI 3.14.0 releases.
 * Other improvements:
   * Added `IAssetDataForImage.ExtendMap` to resize maps in asset editors.
-  * Added [command-line arguments](technical/smapi.md#command-line-arguments) to toggle developer mode (thanks to Tondorian!).
-  * Added `IContentPack.ModContent` property.
-  * Added `Constants.ContentPath`.
-  * Added `IAssetName` fields to the info received by `IAssetEditor` and `IAssetLoader` methods.  
+  * Added `IContentPack.ModContent` property to manage content pack assets.
+  * Added `Constants.ContentPath` to get the full path to the game's `Content` folder.
+  * Added `IAssetName` fields to the info received by `IAssetEditor`, `IAssetLoader`, and content event methods.  
     _This adds methods for working with asset names, parsed locales, etc._
   * Added `helper.Content.ParseAssetName` to get an `IAssetName` for an arbitrary asset key.
+  * Added [command-line arguments](technical/smapi.md#command-line-arguments) to toggle developer mode (thanks to Tondorian!).
   * If an asset is loaded multiple times in the same tick, `IAssetLoader.CanLoad` and `IAssetEditor.CanEdit` are now cached unless invalidated by `helper.Content.InvalidateCache`.
   * The `ISemanticVersion` comparison methods (`CompareTo`, `IsBetween`, `IsNewerThan`, and `IsOlderThan`) now allow null values. A null version is always considered older than any non-null version per [best practices](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable-1.compareto#remarks).
   * Deprecation notices now show a shorter stack trace in most cases, so it's clearer where the deprecated code is in the mod.
@@ -64,9 +62,13 @@ the C# mod that loads them is updated.
   * Fixed support for using locale codes from custom languages in asset names (e.g. `Data/Achievements.eo-EU`).
   * Fixed issue where suppressing `[Left|Right]Thumbstick[Down|Left]` keys would suppress the opposite direction instead.
   * Fixed null handling in various edge cases.
+* For the web UI:
+  * Updated the JSON validator/schema for Content Patcher 1.25.0.
+  * Added `data-*` attributes to the log parser page for external tools.
+  * Fixed JSON validator showing incorrect error for update keys without a subkey.
 
 ### For SMAPI contributors
-* You no longer need a Nexus API key to launch the SMAPI web project locally.
+* You no longer need a Nexus API key to launch the `SMAPI.Web` project locally.
 
 ## 3.13.4
 Released 16 January 2022 for Stardew Valley 1.5.6 or later.
@@ -123,7 +125,7 @@ Released 30 November 2021 for Stardew Valley 1.5.5 or later.
   * Fixed installer failing on Windows when run from the game folder.
 
 ## 3.13.0
-Released 30 November 2021 for Stardew Valley 1.5.5 or later.
+Released 30 November 2021 for Stardew Valley 1.5.5 or later. See [release highlights](https://www.patreon.com/posts/59348226).
 
 * For players:
   * Updated for Stardew Valley 1.5.5.
diff --git a/src/SMAPI.Mods.ConsoleCommands/manifest.json b/src/SMAPI.Mods.ConsoleCommands/manifest.json
index fa5f6d6f..38945c5d 100644
--- a/src/SMAPI.Mods.ConsoleCommands/manifest.json
+++ b/src/SMAPI.Mods.ConsoleCommands/manifest.json
@@ -1,9 +1,9 @@
 {
     "Name": "Console Commands",
     "Author": "SMAPI",
-    "Version": "3.13.4",
+    "Version": "3.14.0",
     "Description": "Adds SMAPI console commands that let you manipulate the game.",
     "UniqueID": "SMAPI.ConsoleCommands",
     "EntryDll": "ConsoleCommands.dll",
-    "MinimumApiVersion": "3.13.4"
+    "MinimumApiVersion": "3.14.0"
 }
diff --git a/src/SMAPI.Mods.ErrorHandler/manifest.json b/src/SMAPI.Mods.ErrorHandler/manifest.json
index 11bc0b42..c082bf75 100644
--- a/src/SMAPI.Mods.ErrorHandler/manifest.json
+++ b/src/SMAPI.Mods.ErrorHandler/manifest.json
@@ -1,9 +1,9 @@
 {
     "Name": "Error Handler",
     "Author": "SMAPI",
-    "Version": "3.13.4",
+    "Version": "3.14.0",
     "Description": "Handles some common vanilla errors to log more useful info or avoid breaking the game.",
     "UniqueID": "SMAPI.ErrorHandler",
     "EntryDll": "ErrorHandler.dll",
-    "MinimumApiVersion": "3.13.4"
+    "MinimumApiVersion": "3.14.0"
 }
diff --git a/src/SMAPI.Mods.SaveBackup/manifest.json b/src/SMAPI.Mods.SaveBackup/manifest.json
index c50cff14..28bffa98 100644
--- a/src/SMAPI.Mods.SaveBackup/manifest.json
+++ b/src/SMAPI.Mods.SaveBackup/manifest.json
@@ -1,9 +1,9 @@
 {
     "Name": "Save Backup",
     "Author": "SMAPI",
-    "Version": "3.13.4",
+    "Version": "3.14.0",
     "Description": "Automatically backs up all your saves once per day into its folder.",
     "UniqueID": "SMAPI.SaveBackup",
     "EntryDll": "SaveBackup.dll",
-    "MinimumApiVersion": "3.13.4"
+    "MinimumApiVersion": "3.14.0"
 }
diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index ddb08435..f5da286a 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -50,7 +50,7 @@ namespace StardewModdingAPI
         internal static int? LogScreenId { get; set; }
 
         /// <summary>SMAPI's current raw semantic version.</summary>
-        internal static string RawApiVersion = "3.13.4";
+        internal static string RawApiVersion = "3.14.0";
     }
 
     /// <summary>Contains SMAPI's constants and assumptions.</summary>
-- 
cgit