Updated: Mod Template w/ New Upgradable Format & Standard Features

Updated: Reloaded Mod Template Wiki Page
SinjuSigne · Aug 26, 2022 · a77d602 · a77d602
1 parent 32b930b
commit a77d602
Show file tree

Hide file tree

Showing 18 changed files with 736 additions and 440 deletions.
diff --git a/docs/ModTemplate.md b/docs/ModTemplate.md
@@ -1,15 +1,8 @@
 # Mod Template Features
 
-!!! note
+!!! tip
 
     Some features are only available on newer versions of the template.  
-
-    Templates in existing mods can be updated by:  
-    - Updating template with `dotnet new update`.  
-    - Creating new mod with same name using new template.   
-    - Overwriting the files in your mod.  
-
-    If you edited the template files in your mod, you may need to replicate your changes.  
 
 ## Publish Script
 
@@ -228,3 +221,86 @@ Example repositories with this setup:
 - [Heroes.Controller.Hook](https://github.com/Sewer56/Heroes.Controller.Hook.ReloadedII)  
 - [Riders.Controller.Hook](https://github.com/Sewer56/Riders.Controller.Hook)  
 
+## Updating the Mod Template
+
+!!! tip
+
+    To update the template, you can run the command [dotnet new update](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new-update).  
+
+!!! info
+
+    If your mod was created using a template older than August 2022, [consider using the following guidance.] (#updating-from-old-template-layout).  
+
+To update the mod template, do the following actions:  
+- Create a new dummy mod (using the same project name as your existing mod).  
+- Copy all files that aren't `Mod.cs` and `Config.json` to your existing mod.  
+- [Optional] Look inside `ModConfig.json` and `.csproj` for new fields/properties (for example, `ProjectUrl` was added in August 2022). 
+
+You are done. 
+
+### Updating from Old Template Layout
+
+!!! info
+
+    Older versions of the mod template (pre Sep. 2022) encouraged editing of the template directly, newer templates take a different approach. Templates can now be swapped out and new features can be applied in `Mod.cs` and `Config.cs`.  
+    While not exhaustive, the following guidance can be used to help migrate to the new template format.  
+
+#### Check Default IMod (Program.cs) Settings
+
+!!! info
+
+    Older versions of the mod template (pre Sep. 2022) encouraged editing of the template directly, newer templates take a different approach. Templates can now be swapped out and new features can be applied in `Mod.cs` and `Config.cs`.  
+    While not exhaustive, the following guidance can be used to help migrate to the new template format.  
+
+Old Defaults:  
+- `CanSuspend`: false  
+- `CanUnload`: false  
+- `Suspend()`, `Unload()`, `Resume()`, `Disposing()`: Empty.  
+- `OnConfigurationUpdated()`: Prints to console and assigns to field.  
+
+If any of these are non-default in the old `IMod` implementation (`Program.cs`), you should move the non-default values to `Mod.cs` in the new template.  
+Mod.cs inherits from `ModBase` which exposes the old methods as overridable virtual functions.  
+
+```csharp
+// Add to Mod.cs to override old CanSuspend.
+public override bool CanSuspend() => true;
+```
+
+#### Move User Code from IMod (Program.cs)
+
+The old layout suggested placing custom code under the line which reads:  
+
+```csharp
+// Please put your mod code (in the class) below
+```
+
+If you encounter this line, move the code below this line into the constructor of `Mod.cs` in the new template.  
+
+### Configuration Migration
+
+!!! info
+
+    If your mod was created before 2022, you will need to migrate where your configurations are stored when using the newer templates.
+
+Previously mods would store configurations in their own folders, however in newer versions a separate dedicated folder is now used.  
+(You can find it in a mod's right click menu in the launcher).  
+
+To migrate your configurations, locate the `ConfiguratorMixin` class (usually in `Config.cs`), and add the following method.
+
+```csharp
+public override void Migrate(string oldDirectory, string newDirectory)
+{
+    // Replace Config.json with your original config file name.
+    TryMoveFile("Config.json");
+
+#pragma warning disable CS8321
+    void TryMoveFile(string fileName)
+    {
+        try { File.Move(Path.Combine(oldDirectory, fileName), Path.Combine(newDirectory, fileName)); }
+        catch (Exception) { /* Ignored */ }
+    }
+#pragma warning restore CS8321
+}
+```
+
+This process can also be used to handle migration for other config modifications such as when `TryRunCustomConfiguration() == true`.  
diff --git a/source/Reloaded.Mod.Template/Reloaded.Mod.Template.NuGet.csproj b/source/Reloaded.Mod.Template/Reloaded.Mod.Template.NuGet.csproj
@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <PackageType>Template</PackageType>
-    <PackageVersion>1.2.2</PackageVersion>
+    <PackageVersion>1.3.1</PackageVersion>
     <PackageId>Reloaded.Mod.Templates</PackageId>
     <Title>Reloaded-II Mod Templates</Title>
     <Authors>Sewer56</Authors>

diff --git a/source/Reloaded.Mod.Template/templates/configurable/.template.config/template.json b/source/Reloaded.Mod.Template/templates/configurable/.template.config/template.json
@@ -42,6 +42,13 @@
             "replaces": "ModAuthorValue",
             "defaultValue": "Me"
         },
+        "IncludeConfig": {
+            "type": "parameter",
+            "displayName": "Add Mod Configuration Support",
+            "dataType": "bool",
+            "defaultValue": "true"
+        }
+        ,
         "AddGitHubActions": {
             "type": "parameter",
             "displayName": "Add GitHub Actions",
@@ -57,6 +64,13 @@
                     "exclude": [
                         ".github/workflows/reloaded.yml"
                     ]
+                },
+                {
+                    "condition": "(!IncludeConfig)",
+                    "exclude": [
+                        "Config.cs",
+                        "Template/Configuration/**"
+                    ]
                 }
             ]
         }

diff --git a/source/Reloaded.Mod.Template/templates/configurable/Config.cs b/source/Reloaded.Mod.Template/templates/configurable/Config.cs
@@ -0,0 +1,73 @@
+#if (IncludeConfig)
+using System.ComponentModel;
+using Reloaded.Mod.Interfaces;
+
+namespace Reloaded.Mod.Template.Template.Configuration;
+
+public class Config : Configurable<Config>
+{
+    /*
+        User Properties:
+            - Please put all of your configurable properties here.
+    
+        By default, configuration saves as "Config.json" in mod user config folder.    
+        Need more config files/classes? See Configuration.cs
+    
+        Available Attributes:
+        - Category
+        - DisplayName
+        - Description
+        - DefaultValue
+
+        // Technically Supported but not Useful
+        - Browsable
+        - Localizable
+
+        The `DefaultValue` attribute is used as part of the `Reset` button in Reloaded-Launcher.
+    */
+
+    [DisplayName("String")]
+    [Description("This is a string.")]
+    [DefaultValue("Default Name")]
+    public string String { get; set; } = "Default Name";
+
+    [DisplayName("Int")]
+    [Description("This is an int.")]
+    [DefaultValue(42)]
+    public int Integer { get; set; } = 42;
+
+    [DisplayName("Bool")]
+    [Description("This is a bool.")]
+    [DefaultValue(true)]
+    public bool Boolean { get; set; } = true;
+
+    [DisplayName("Float")]
+    [Description("This is a floating point number.")]
+    [DefaultValue(6.987654F)]
+    public float Float { get; set; } = 6.987654F;
+
+    [DisplayName("Enum")]
+    [Description("This is an enumerable.")]
+    [DefaultValue(SampleEnum.ILoveIt)]
+    public SampleEnum Reloaded { get; set; } = SampleEnum.ILoveIt;
+
+    public enum SampleEnum
+    {
+        NoOpinion,
+        Sucks,
+        IsMediocre,
+        IsOk,
+        IsCool,
+        ILoveIt
+    }
+}
+
+/// <summary>
+/// Allows you to override certain aspects of the configuration creation process (e.g. create multiple configurations).
+/// Override elements in <see cref="ConfiguratorMixinBase"/> for finer control.
+/// </summary>
+public class ConfiguratorMixin : ConfiguratorMixinBase
+{
+    // 
+}
+#endif
diff --git a/source/Reloaded.Mod.Template/templates/configurable/Configuration/Config.cs b/source/Reloaded.Mod.Template/templates/configurable/Configuration/Config.cs