Merge branch 'mod-package-token' into develop

Author: Pathoschild

docs/technical/mod-package-release-notes.md

@@ -1,7 +1,14 @@
 ← [mod build config](./mod-build-config.md)
 
 ## Release notes
-# 4.3.2
+## 4.4.0
+Released 13 April 2025 for SMAPI 4.1.0 or later.
+
+* Added `%ProjectVersion%` [token you can use in `manifest.json` files](mod-package.md#manifest-tokens).
+* Revamped [package documentation](mod-package.md).  
+  _This makes it easier to see the features at a glance, and collects the info for each feature into one place._
+
+## 4.3.2
 Released 09 November 2024 for SMAPI 4.1.0 or later.
 
 * Fixed `IgnoreModFilePaths` and `IgnoreModFilePatterns` not working correctly in recent versions.

docs/technical/mod-package.md

@@ -7,11 +7,7 @@
 using System.Text.RegularExpressions;
 using Microsoft.Build.Framework;
 using Microsoft.Build.Utilities;
-using Newtonsoft.Json;
 using StardewModdingAPI.ModBuildConfig.Framework;
-using StardewModdingAPI.Toolkit.Framework;
-using StardewModdingAPI.Toolkit.Serialization;
-using StardewModdingAPI.Toolkit.Serialization.Models;
 using StardewModdingAPI.Toolkit.Utilities;
 
 namespace StardewModdingAPI.ModBuildConfig;
@@ -34,6 +30,10 @@ public class DeployModTask : Task
     [Required]
     public string ModZipPath { get; set; }
 
+    /// <summary>The version number for the project assembly.</summary>
+    [Required]
+    public string ProjectVersion { get; set; }
+
     /// <summary>The folder containing the project files.</summary>
     [Required]
     public string ProjectDir { get; set; }
@@ -87,33 +87,12 @@ public override bool Execute()
         if (!this.EnableModDeploy && !this.EnableModZip)
             return true;
 
-        // validate the manifest file
-        IManifest manifest;
+        // read & validate manifest
+        string manifestPath = Path.Combine(this.ProjectDir, BundleFile.ManifestFileName);
+        if (!ManifestHelper.TryLoadManifest(manifestPath, this.ProjectVersion, out IManifest manifest, out string overrideManifestJson, out string error))
         {
-            try
-            {
-                string manifestPath = Path.Combine(this.ProjectDir, "manifest.json");
-                if (!new JsonHelper().ReadJsonFileIfExists(manifestPath, out Manifest rawManifest))
-                {
-                    this.Log.LogError("[mod build package] The mod's manifest.json file doesn't exist.");
-                    return false;
-                }
-                manifest = rawManifest;
-            }
-            catch (JsonReaderException ex)
-            {
-                // log the inner exception, otherwise the message will be generic
-                Exception exToShow = ex.InnerException ?? ex;
-                this.Log.LogError($"[mod build package] The mod's manifest.json file isn't valid JSON: {exToShow.Message}");
-                return false;
-            }
-
-            // validate manifest fields
-            if (!ManifestValidator.TryValidateFields(manifest, out string error))
-            {
-                this.Log.LogError($"[mod build package] The mod's manifest.json file is invalid: {error}");
-                return false;
-            }
+            this.Log.LogError($"[mod build package] The mod's {BundleFile.ManifestFileName} is invalid: {error}");
+            return false;
         }
 
         // deploy files
@@ -128,7 +107,7 @@ public override bool Execute()
 
             var modPackages = new Dictionary<string, IModFileManager>
             {
-                [this.ModFolderName] = new MainModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, this.ModDllName, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip)
+                [this.ModFolderName] = new MainModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, this.ModDllName, overrideManifestJson, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip)
             };
 
             if (this.ContentPacks != null)
@@ -158,7 +137,7 @@ public override bool Execute()
                     this.Log.LogMessage(MessageImportance.High, $"[mod build package] Bundling content pack: {folderName} v{version} at {contentPath}.");
                     modPackages.Add(
                         folderName,
-                        new ContentPackFileManager(this.ProjectDir, contentPath, version, ignoreFilePaths, ignoreFilePatterns, validateManifest)
+                        new ContentPackFileManager(this.ProjectDir, contentPath, this.ProjectVersion, version, ignoreFilePaths, ignoreFilePatterns, validateManifest)
                     );
                 }
             }
@@ -299,21 +278,17 @@ private IEnumerable<string> GetCustomIgnoreFilePaths(string pattern)
     /// <param name="outputPath">The folder path to create with the mod files.</param>
     private void CreateModFolder(IDictionary<string, IModFileManager> modPackages, string outputPath)
     {
-        foreach (var mod in modPackages)
+        foreach (var pair in modPackages)
         {
-            string relativePath = modPackages.Count == 1
-                ? outputPath
-                : Path.Combine(outputPath, this.EscapeInvalidFilenameCharacters(mod.Key));
-
-            foreach (var file in mod.Value.GetFiles())
-            {
-                string fromPath = file.Value.FullName;
-                string toPath = Path.Combine(relativePath, file.Key);
+            string folderName = pair.Key;
+            IModFileManager fileManager = pair.Value;
 
-                Directory.CreateDirectory(Path.GetDirectoryName(toPath)!);
+            string folderPath = modPackages.Count == 1
+                ? outputPath
+                : Path.Combine(outputPath, this.EscapeInvalidFilenameCharacters(folderName));
 
-                File.Copy(fromPath, toPath, overwrite: true);
-            }
+            foreach (BundleFile from in fileManager.GetFiles())
+                from.CopyToFolder(folderPath);
         }
     }
 
@@ -330,21 +305,19 @@ private void CreateReleaseZip(IDictionary<string, IModFileManager> modPackages,
         foreach (var mod in modPackages)
         {
             string modFolder = this.EscapeInvalidFilenameCharacters(mod.Key);
-            foreach (var file in mod.Value.GetFiles())
+            foreach (BundleFile from in mod.Value.GetFiles())
             {
-                string relativePath = file.Key;
+                string relativePath = from.RelativePath;
+
                 if (relativePath.Contains('\\'))
                     relativePath = string.Join("/", PathUtilities.GetSegments(relativePath)); // zip files use forward slashes regardless of OS
 
-                FileInfo fileInfo = file.Value;
-
                 string archivePath = modPackages.Count == 1
                     ? $"{modFolder}/{relativePath}"
                     : $"{this.ModFolderName}/{modFolder}/{relativePath}";
 
-                using Stream fileStream = new FileStream(fileInfo.FullName, FileMode.Open, FileAccess.Read);
                 using Stream fileStreamInZip = archive.CreateEntry(archivePath).Open();
-                fileStream.CopyTo(fileStreamInZip);
+                from.CopyToStream(fileStreamInZip);
             }
         }
     }

src/SMAPI.ModBuildConfig/DeployModTask.cs

@@ -0,0 +1,76 @@
+using System;
+using System.IO;
+using System.Text;
+
+namespace StardewModdingAPI.ModBuildConfig.Framework;
+
+/// <summary>A file that should be deployed or zipped as part of a mod.</summary>
+internal class BundleFile
+{
+    /*********
+    ** Accessors
+    *********/
+    /// <summary>The name of the manifest file.</summary>
+    public const string ManifestFileName = "manifest.json";
+
+    /// <summary>The file's relative path within the mod.</summary>
+    public string RelativePath { get; }
+
+    /// <summary>The file to copy from.</summary>
+    public FileInfo File { get; }
+
+    /// <summary>If set, deploy this content instead of copying the original file.</summary>
+    public string OverrideContent { get; }
+
+    /*********
+    ** Public methods
+    *********/
+    /// <summary>Construct an instance.</summary>
+    /// <param name="relativePath">The file's relative path within the mod.</param>
+    /// <param name="file">The file to copy from.</param>
+    /// <param name="overrideContent">If set, deploy this content instead of copying the original file.</param>
+    public BundleFile(string relativePath, FileInfo file, string overrideContent = null)
+    {
+        this.RelativePath = relativePath;
+        this.File = file;
+        this.OverrideContent = overrideContent;
+    }
+
+    /// <summary>Get whether this entry is for the mod's <samp>manifest.json</samp> file.</summary>
+    public bool IsModManifest()
+    {
+        return BundleFile.IsModManifest(this.RelativePath);
+    }
+
+    /// <summary>Copy the file into a destination folder.</summary>
+    /// <param name="folderPath">The folder path to use as the base for the <see cref="RelativePath"/>.</param>
+    public void CopyToFolder(string folderPath)
+    {
+        string toPath = Path.Combine(folderPath, this.RelativePath);
+
+        Directory.CreateDirectory(Path.GetDirectoryName(toPath)!);
+
+        if (this.OverrideContent != null)
+            System.IO.File.WriteAllText(toPath, this.OverrideContent, Encoding.UTF8);
+        else
+            this.File.CopyTo(toPath, overwrite: true);
+    }
+
+    /// <summary>Copy the file's contents into a stream.</summary>
+    /// <param name="stream">The stream into which to write the file's contents.</param>
+    public void CopyToStream(Stream stream)
+    {
+        using Stream fromStream = this.OverrideContent != null
+            ? new MemoryStream(Encoding.UTF8.GetBytes(this.OverrideContent))
+            : this.File.OpenRead();
+
+        fromStream.CopyTo(stream);
+    }
+
+    /// <summary>Get whether a relative path is for the mod's <samp>manifest.json</samp> file.</summary>
+    /// <param name="relativePath">The relative path within the mod folder within the mod's folder.</param>
+    public static bool IsModManifest(string relativePath)
+    {
+        return string.Equals(relativePath, BundleFile.ManifestFileName, StringComparison.OrdinalIgnoreCase);
+    }
+}

src/SMAPI.ModBuildConfig/Framework/BundleFile.cs

@@ -3,11 +3,7 @@
 using System.IO;
 using System.Linq;
 using System.Text.RegularExpressions;
-using Newtonsoft.Json;
 using StardewModdingAPI.Toolkit;
-using StardewModdingAPI.Toolkit.Framework;
-using StardewModdingAPI.Toolkit.Serialization;
-using StardewModdingAPI.Toolkit.Serialization.Models;
 using StardewModdingAPI.Toolkit.Utilities;
 
 namespace StardewModdingAPI.ModBuildConfig.Framework;
@@ -18,11 +14,8 @@ internal class ContentPackFileManager : IModFileManager
     /*********
     ** Fields
     *********/
-    /// <summary>The name of the manifest file.</summary>
-    private readonly string ManifestFileName = "manifest.json";
-
     /// <summary>The files that are part of the package.</summary>
-    private readonly Dictionary<string, FileInfo> Files = new(StringComparer.OrdinalIgnoreCase);
+    private readonly List<BundleFile> Files = [];
 
 
     /*********
@@ -31,58 +24,47 @@ internal class ContentPackFileManager : IModFileManager
     /// <summary>Construct an instance.</summary>
     /// <param name="projectDir">The folder containing the project files.</param>
     /// <param name="contentPackDir">The absolute or relative path to the content pack folder.</param>
+    /// <param name="projectVersion">The version number for the project assembly.</param>
     /// <param name="version">The mod version.</param>
     /// <param name="ignoreFilePaths">The custom relative file paths provided by the user to ignore.</param>
     /// <param name="ignoreFilePatterns">Custom regex patterns matching files to ignore when deploying or zipping the mod.</param>
     /// <param name="validateManifest">Whether to validate that the content pack's manifest is valid.</param>
     /// <exception cref="UserErrorException">The mod package isn't valid.</exception>
-    public ContentPackFileManager(string projectDir, string contentPackDir, string version, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, bool validateManifest)
+    public ContentPackFileManager(string projectDir, string contentPackDir, string projectVersion, string version, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, bool validateManifest)
     {
         // get folders
         DirectoryInfo projectDirInfo = new(Path.Combine(projectDir, contentPackDir));
         if (!projectDirInfo.Exists)
             throw GetError($"that folder doesn't exist at {projectDirInfo.FullName}");
 
+        // load manifest
+        string manifestPath = Path.Combine(contentPackDir, BundleFile.ManifestFileName);
+        if (!ManifestHelper.TryLoadManifest(manifestPath, projectVersion, out IManifest manifest, out string overrideManifestJson, out string error))
+            throw GetError($"its {BundleFile.ManifestFileName} file is invalid: {error}");
+
         // collect files
-        foreach (FileInfo entry in projectDirInfo.GetFiles("*", SearchOption.AllDirectories))
+        foreach (FileInfo file in projectDirInfo.GetFiles("*", SearchOption.AllDirectories))
         {
-            string relativePath = PathUtilities.GetRelativePath(projectDirInfo.FullName, entry.FullName);
-            FileInfo file = entry;
+            string relativePath = PathUtilities.GetRelativePath(projectDirInfo.FullName, file.FullName);
+
+            if (this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns))
+                continue;
 
-            if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns))
-                this.Files[relativePath] = file;
+            this.Files.Add(BundleFile.IsModManifest(relativePath)
+                ? new BundleFile(relativePath, file, overrideManifestJson)
+                : new BundleFile(relativePath, file)
+            );
         }
 
-        // validate manifest
+        // validate manifest version
         if (validateManifest)
         {
-            // get manifest file
-            if (!this.Files.TryGetValue(this.ManifestFileName, out FileInfo manifestFile))
-                throw GetError($"it has no {this.ManifestFileName} file");
-
-            // parse file
-            Manifest manifest;
-            try
-            {
-                new JsonHelper().ReadJsonFileIfExists(manifestFile.FullName, out Manifest rawManifest);
-                manifest = rawManifest;
-            }
-            catch (JsonReaderException ex)
-            {
-                throw GetError($"its {this.ManifestFileName} file isn't valid JSON: {ex.InnerException?.Message ?? ex.Message}");
-            }
-
-            // validate manifest fields
-            if (!ManifestValidator.TryValidateFields(manifest, out string error))
-                throw GetError($"its {this.ManifestFileName} file is invalid: {error}");
-
-            // validate version
             if (version == null)
                 throw GetError("no Version value was provided");
             if (!SemanticVersion.TryParse(version, out ISemanticVersion requiredVersion))
                 throw GetError($"the provided Version value '{version}' isn't a valid semantic version");
             if (manifest.Version.CompareTo(requiredVersion) != 0)
-                throw GetError($"its {this.ManifestFileName} has version '{manifest.Version}' instead of the required '{requiredVersion}'");
+                throw GetError($"its {BundleFile.ManifestFileName} has version '{manifest.Version}' instead of the required '{requiredVersion}'");
         }
 
         UserErrorException GetError(string reasonPhrase)
@@ -92,9 +74,9 @@ UserErrorException GetError(string reasonPhrase)
     }
 
     ///<inheritdoc/>
-    public IDictionary<string, FileInfo> GetFiles()
+    public IEnumerable<BundleFile> GetFiles()
     {
-        return new Dictionary<string, FileInfo>(this.Files, StringComparer.OrdinalIgnoreCase);
+        return this.Files;
     }
 
     /// <summary>Get whether a content file should be ignored.</summary>

src/SMAPI.ModBuildConfig/Framework/ContentPackFileManager.cs

@@ -1,11 +1,10 @@
 using System.Collections.Generic;
-using System.IO;
 
 namespace StardewModdingAPI.ModBuildConfig.Framework;
 
 /// <summary>Manages the files that are part of a mod in the release package.</summary>
-public interface IModFileManager
+internal interface IModFileManager
 {
     /// <summary>Get the files in the mod package.</summary>
-    public IDictionary<string, FileInfo> GetFiles();
+    public IEnumerable<BundleFile> GetFiles();
 }