Merge pull request #220 from SpaceWarpDev/v1.2.0

1.2.0 release

.gitattributes

@@ -0,0 +1,9 @@
+# Auto detect text files and perform LF normalization
+*          text=auto
+
+*.cs       text diff=csharp
+*.csx      text diff=csharp
+*.sln      text eol=crlf
+*.csproj   text eol=crlf
+
+*.csv      text eol=lf

.github/README.md

@@ -56,7 +56,7 @@ KSP2_Root_Folder/
 │   │   │   │   │   ├── *.bundle
 │   │   │   │   ├── images/
 │   │   │   │   │   ├── *
-│   │   │   ├── localization/
+│   │   │   ├── localizations/
 │   │   │   │   ├── *.csv
 │   │   │   ├── addressables/
 │   │   │   │   ├── catalog.json

Directory.Build.props

@@ -1,13 +1,15 @@
 <Project>
     <PropertyGroup>
-        <SpaceWarpVersion>1.1.3</SpaceWarpVersion>
-        <TargetFramework>net472</TargetFramework>
+        <SpaceWarpVersion>1.2.0</SpaceWarpVersion>
+        <TargetFramework>netstandard2.0</TargetFramework>
         <LangVersion>11</LangVersion>
         <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
         <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
         <CopyLocalLockFileAssemblies>false</CopyLocalLockFileAssemblies>
-        <!-- Disabled warning for publicizer attribute until the NuGet exists for KSP2  -->
-        <NoWarn>CS0436</NoWarn>
+        <!-- Disabled warning for publicizer attribute until the NuGet exists for KSP2,
+             and for missing documentation comments for public types and members -->
+        <NoWarn>$(NoWarn),CS0436,CS1591</NoWarn>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
 
     <!--

ExampleMod/ExampleMod.cs

@@ -42,7 +42,7 @@ public override void OnInitialized()
             // Path format [mod_id]/images/filename
             // for bundles its [mod_id]/[bundle_name]/[path to file in bundle with out assets/bundle]/filename.extension
             // There is also a try get asset function, that returns a bool on whether or not it could grab the asset
-            AssetManager.GetAsset<Texture2D>($"{SpaceWarpMetadata.ModID}/images/icon.png"),
+            AssetManager.GetAsset<Texture2D>($"{IdBySpec}/images/icon.png"),
             ToggleButton
         );
     }
@@ -73,7 +73,7 @@ public void OnGUI()
             windowRect = GUILayout.Window(
                 GUIUtility.GetControlID(FocusType.Passive),
                 windowRect,
-                FillWindow, // The method we call. 
+                FillWindow, // The method we call.
                 "Window Header",
                 GUILayout.Height(350),
                 GUILayout.Width(350)
@@ -90,7 +90,7 @@ private static void FillWindow(int windowID)
         GUILayout.Label("Example Mod - Built with Space-Warp");
         GUI.DragWindow(new Rect(0, 0, 10000, 500));
     }
-    
+
     private float lastUpdateTime = 0.0f;
     private float updateInterval = 1.0f;
 
@@ -123,9 +123,9 @@ private void LateUpdate()
         }
         else if (Game.GlobalGameState.GetState() == KSP.Game.GameState.FlightView)
         {
-            // Getting the active vessel, staging it over and over and printing out all the parts. 
+            // Getting the active vessel, staging it over and over and printing out all the parts.
             VesselComponent _activeVessel = Game.ViewController.GetActiveSimVessel();
-            
+
             if (_activeVessel != null)
             {
                 _activeVessel.ActivateNextStage();

NuGet.config

@@ -2,5 +2,6 @@
 <configuration>
   <packageSources>
     <add key="BepInEx" value="https://nuget.bepinex.dev/v3/index.json" />
+    <add key="SpaceWarp" value="https://nuget.spacewarp.org/v3/index.json" />
   </packageSources>
 </configuration>

SpaceWarp/API/Loading/Loading.cs

@@ -5,6 +5,7 @@
 using KSP.Game.Flow;
 using SpaceWarp.API.Assets;
 using SpaceWarp.API.Mods;
+using SpaceWarp.API.Mods.JSON;
 using SpaceWarp.Patching.LoadingActions;
 
 namespace SpaceWarp.API.Loading;
@@ -59,7 +60,7 @@ public static void AddAddressablesLoadingAction<T>(string name, string label, Ac
     {
         AddGeneralLoadingAction(new AddressableAction<T>(name, label, action));
     }
-    
+
 
     private static Action<BaseSpaceWarpPlugin> CreateAssetLoadingActionWithExtensions(string subfolder, Func<string, string, List<(string name, UnityObject asset)>> importFunction, string[] extensions)
     {
@@ -103,7 +104,7 @@ private static void LoadSingleAsset(Func<string, string, List<(string name, Unit
         var assets = importFunction(assetPath, file);
         foreach (var asset in assets)
         {
-            AssetManager.RegisterSingleAsset(plugin.SpaceWarpMetadata.ModID, asset.name, asset.asset);
+            AssetManager.RegisterSingleAsset(plugin.IdBySpec, asset.name, asset.asset);
         }
     }
 

SpaceWarp/API/Loading/SaveLoad.cs

@@ -1,4 +1,5 @@
-using KSP.Game.Flow;
+using System;
+using KSP.Game.Flow;
 using SpaceWarp.Patching;
 
 namespace SpaceWarp.API.Loading;

SpaceWarp/API/Mods/BaseSpaceWarpPlugin.cs

@@ -30,6 +30,8 @@ public abstract class BaseSpaceWarpPlugin : BaseUnityPlugin
     internal ManualLogSource ModLogger => Logger;
     public string PluginFolderPath { get; internal set; }
 
+    public string IdBySpec => GetGuidBySpec(Info, SpaceWarpMetadata);
+
     /// <summary>
     ///     1st stage initialization
     ///     This is called before any of the game is actually loaded, it is called as early as possible in the games bootstrap
@@ -54,4 +56,11 @@ public virtual void OnInitialized()
     public virtual void OnPostInitialized()
     {
     }
+
+    internal static string GetGuidBySpec(PluginInfo pluginInfo, ModInfo modInfo)
+    {
+        return modInfo.Spec >= SpecVersion.V1_2
+            ? pluginInfo.Metadata.GUID
+            : modInfo.ModID;
+    }
 }

SpaceWarp/API/Mods/JSON/Converters/SpecVersionConverter.cs

@@ -0,0 +1,24 @@
+using System;
+using Newtonsoft.Json;
+
+namespace SpaceWarp.API.Mods.JSON.Converters;
+
+internal class SpecVersionConverter : JsonConverter<SpecVersion>
+{
+    public override void WriteJson(JsonWriter writer, SpecVersion value, JsonSerializer serializer)
+    {
+        writer.WriteValue(value.ToString());
+    }
+
+    public override SpecVersion ReadJson(
+        JsonReader reader,
+        Type objectType,
+        SpecVersion existingValue,
+        bool hasExistingValue,
+        JsonSerializer serializer
+    )
+    {
+        var specVersion = (string)reader.Value;
+        return new SpecVersion(specVersion);
+    }
+}

SpaceWarp/API/Mods/JSON/ModInfo.cs

@@ -10,7 +10,28 @@ namespace SpaceWarp.API.Mods.JSON;
 [JsonObject(MemberSerialization.OptIn)]
 public sealed class ModInfo
 {
-    [JsonProperty("mod_id")] public string ModID { get; internal set; }
+    [JsonProperty("spec")] public SpecVersion Spec { get; internal set; } = new();
+
+    [JsonProperty("mod_id")] private string _modID;
+
+    public string ModID
+    {
+        get
+        {
+            if (Spec >= SpecVersion.V1_2)
+            {
+                throw new DeprecatedSwinfoPropertyException(nameof(ModID), SpecVersion.V1_2);
+            }
+
+            SpaceWarpManager.Logger.LogWarning(
+                "The swinfo.json \"mod_id\" property is deprecated and will be removed in a future version. " +
+                "Instead of ModID, use PluginClass.Info.Metadata.GUID in your code."
+            );
+
+            return _modID;
+        }
+        internal set => _modID = value;
+    }
 
     [JsonProperty("name")] public string Name { get; internal set; }
 
@@ -26,7 +47,10 @@ public sealed class ModInfo
 
     [JsonProperty("ksp2_version")] public SupportedVersionsInfo SupportedKsp2Versions { get; internal set; }
 
-    [JsonProperty("version_check", Required = Required.Default)]
+    [JsonProperty("version_check")]
     [CanBeNull]
     public string VersionCheck { get; internal set; }
+
+    [JsonProperty("version_check_type")]
+    public VersionCheckType VersionCheckType { get; internal set; } = VersionCheckType.SwInfo;
 }

SpaceWarp/API/Mods/JSON/SpecVersion.cs

@@ -0,0 +1,105 @@
+using System;
+using Newtonsoft.Json;
+using SpaceWarp.API.Mods.JSON.Converters;
+
+namespace SpaceWarp.API.Mods.JSON;
+
+/// <summary>
+/// Represents the version of the API specification from the swinfo.json file.
+/// </summary>
+[JsonConverter(typeof(SpecVersionConverter))]
+public sealed record SpecVersion
+{
+    private const int DefaultMajor = 1;
+    private const int DefaultMinor = 0;
+
+    public int Major { get; } = DefaultMajor;
+    public int Minor { get; } = DefaultMinor;
+
+    // ReSharper disable InconsistentNaming
+
+    /// <summary>
+    /// Specification version 1.0 (SpaceWarp &lt; 1.2), used if "spec" is not specified in the swinfo.json file.
+    /// </summary>
+    public static SpecVersion Default { get; } = new();
+
+    /// <summary>
+    /// Specification version 1.2 (SpaceWarp 1.2.x), replaces SpaceWarp's proprietary ModID with BepInEx plugin GUID.
+    /// </summary>
+    public static SpecVersion V1_2 { get; } = new(1, 2);
+
+    // ReSharper restore InconsistentNaming
+
+    /// <summary>
+    /// Creates a new SpecVersion object with the version "major.minor".
+    /// </summary>
+    /// <param name="major">Major version number</param>
+    /// <param name="minor">Minor version number</param>
+    public SpecVersion(int major, int minor)
+    {
+        Major = major;
+        Minor = minor;
+    }
+
+    /// <summary>
+    /// Creates a new SpecVersion object from a string.
+    /// </summary>
+    /// <param name="version">Specification version in the format "major.minor"</param>
+    /// <exception cref="InvalidSpecVersionException">Thrown if the string format is invalid</exception>
+    public SpecVersion(string version = null)
+    {
+        if (version == null)
+        {
+            return;
+        }
+
+        var split = version.Split('.');
+        if (split.Length != 2 || !int.TryParse(split[0], out var major) || !int.TryParse(split[1], out var minor))
+        {
+            throw new InvalidSpecVersionException(version);
+        }
+
+        Major = major;
+        Minor = minor;
+    }
+
+    public override string ToString() => $"{Major}.{Minor}";
+
+    public static bool operator <(SpecVersion a, SpecVersion b) => Compare(a, b) < 0;
+    public static bool operator >(SpecVersion a, SpecVersion b) => Compare(a, b) > 0;
+    public static bool operator <=(SpecVersion a, SpecVersion b) => Compare(a, b) <= 0;
+    public static bool operator >=(SpecVersion a, SpecVersion b) => Compare(a, b) >= 0;
+
+    private static int Compare(SpecVersion a, SpecVersion b)
+    {
+        if (a.Major != b.Major)
+        {
+            return a.Major - b.Major;
+        }
+
+        return a.Minor - b.Minor;
+    }
+}
+
+/// <summary>
+/// Thrown if the specification version string is invalid.
+/// </summary>
+public sealed class InvalidSpecVersionException : Exception
+{
+    public InvalidSpecVersionException(string version) : base(
+        $"Invalid spec version: {version}. The correct format is \"major.minor\".")
+    {
+    }
+}
+
+/// <summary>
+/// Thrown if a property is deprecated in the current specification version.
+/// </summary>
+public sealed class DeprecatedSwinfoPropertyException : Exception
+{
+    public DeprecatedSwinfoPropertyException(string property, SpecVersion deprecationVersion) : base(
+        $"The swinfo.json property \"{property}\" is deprecated in the spec version {deprecationVersion} and will be removed completely in the future."
+    )
+    {
+    }
+}

SpaceWarp/API/Mods/JSON/SupportedVersionsInfo.cs

@@ -9,17 +9,20 @@ namespace SpaceWarp.API.Mods.JSON;
 [JsonObject(MemberSerialization.OptIn)]
 public sealed class SupportedVersionsInfo
 {
-    [JsonProperty("min")] public string Min { get; internal set; } = "0.0.0";
+    internal const string DefaultMin = "0.0.0";
+    internal const string DefaultMax = "*";
 
-    [JsonProperty("max")] public string Max { get; internal set; } = "*";
+    [JsonProperty("min")] public string Min { get; internal set; } = DefaultMin;
+
+    [JsonProperty("max")] public string Max { get; internal set; } = DefaultMax;
 
     public bool IsSupported(string toCheck)
     {
-        if (VersionUtility.CompareSemanticVersionStrings(toCheck, Min) < 0)
-        {
-            return false;
-        }
+        return VersionUtility.IsSupported(toCheck, Min, Max);
+    }
 
-        return VersionUtility.CompareSemanticVersionStrings(toCheck, Max) <= 0;
+    public override string ToString()
+    {
+        return $"{Min} - {Max}";
     }
 }

SpaceWarp/API/Mods/JSON/VersionCheckType.cs

@@ -0,0 +1,14 @@
+using System.Runtime.Serialization;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+
+namespace SpaceWarp.API.Mods.JSON;
+
+[JsonConverter(typeof(StringEnumConverter))]
+public enum VersionCheckType
+{
+    [EnumMember(Value = "swinfo")]
+    SwInfo,
+    [EnumMember(Value = "csproj")]
+    Csproj
+}