From 4704bc805cd4914459a574b3523402540dfd6156 Mon Sep 17 00:00:00 2001 From: Ben C Date: Wed, 11 Dec 2024 15:44:14 -0500 Subject: [PATCH 1/5] Create prepatchers.md --- docs/content/pages/guides/prepatchers.md | 53 ++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/content/pages/guides/prepatchers.md diff --git a/docs/content/pages/guides/prepatchers.md b/docs/content/pages/guides/prepatchers.md new file mode 100644 index 00000000..6f8b800a --- /dev/null +++ b/docs/content/pages/guides/prepatchers.md @@ -0,0 +1,53 @@ +--- +Title: Prepatchers +Sort_Priority: 33 +--- + +# Prepatchers + +In certain contexts you may need to edit game files before start. This is where +prepatchers come in. Prepatchers are run by OWML directly before the game starts, allowing you to modify game files you would otherwise not be able to. + +To create a prepatcher you'll need a separate project from your mod. This can be done by creating a new project in your solution with the executable type, it should automatically build to your mod folder. + +Now in your mod manifest you need to set the `patcher` field to the path of the executable relative to the root of the +mod folder. + +## Creating A Prepatcher + +A prepatcher is a simple console app that OWML executes, it's only passed the location of your mod folder. +However, it is possible to get the game's location by doing `AppDomain.CurrentDomain.BaseDirectory`: + +```csharp +public static void Main(string[] args) +{ + var modPath = args.Length > 0 ? args[0] : "."; + var gamePath = AppDomain.CurrentDomain.BaseDirectory; + + Console.WriteLine($"Mod Path: {modPath}"); + Console.WriteLine($"Game Path: {gamePath}"); + + // DoStuff(modPath, gamePath); +} +``` + +Keep in mind the `ModHelper` is not available in a prepatcher. +You'll need to have the prepatcher include libraries like Newtonsoft.Json to read and write JSON files. + +### Logging + +Due to a lack of `ModHelper`, you'll need to use `Console.WriteLine` to log information. +This **will not output to the manager window**. To test prepatchers, we recommend you launch `OWML.Launcher.exe` in a +terminal directly to properly see stdout. + +If a prepatcher errors it *should usually* be outputted to the manage window as OWML is setup to catch and +log any exceptions thrown by the prepatcher. + +### Warnings + +Due to the nature of prepatchers, the manager cannot undo changes made by them. This means the game will continue to be modified even if the +mod is uninstalled or disabled. + +The manager will try it's best to warn the user of this. If your mod has prepatcher and +is disabled or uninstalled the manager will show a dialog explaining that +your mod has modified game files in an irreversible way and encourages them to validate the game files. From 99b43b783cd14d3db204b1ffebb6b77950242a22 Mon Sep 17 00:00:00 2001 From: Ben C Date: Wed, 11 Dec 2024 18:00:24 -0500 Subject: [PATCH 2/5] Add QSB example --- docs/content/pages/guides/prepatchers.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/pages/guides/prepatchers.md b/docs/content/pages/guides/prepatchers.md index 6f8b800a..80ffdb47 100644 --- a/docs/content/pages/guides/prepatchers.md +++ b/docs/content/pages/guides/prepatchers.md @@ -34,6 +34,8 @@ public static void Main(string[] args) Keep in mind the `ModHelper` is not available in a prepatcher. You'll need to have the prepatcher include libraries like Newtonsoft.Json to read and write JSON files. +As an example, Quantum Space Buddies [utilizes a pre-patcher](https://github.com/qsb-dev/quantum-space-buddies/tree/master/QSBPatcher). You can use this as an example. Notice how it also needs to [set this as `patcher` in its manifest](https://github.com/qsb-dev/quantum-space-buddies/blob/b2e55d61e97b2e9c05b8b6e69cb349c57b59aa93/QSB/manifest.json#L18) in order for OWML to know to run it. + ### Logging Due to a lack of `ModHelper`, you'll need to use `Console.WriteLine` to log information. From cf93f7adb1a156f415ca9df75f0189c1f0ec1b2e Mon Sep 17 00:00:00 2001 From: Ben C Date: Wed, 11 Dec 2024 19:38:51 -0500 Subject: [PATCH 3/5] its --- docs/content/pages/guides/prepatchers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/pages/guides/prepatchers.md b/docs/content/pages/guides/prepatchers.md index 80ffdb47..f62faf84 100644 --- a/docs/content/pages/guides/prepatchers.md +++ b/docs/content/pages/guides/prepatchers.md @@ -15,7 +15,7 @@ mod folder. ## Creating A Prepatcher -A prepatcher is a simple console app that OWML executes, it's only passed the location of your mod folder. +A prepatcher is a simple console app that OWML executes, its only passed the location of your mod folder. However, it is possible to get the game's location by doing `AppDomain.CurrentDomain.BaseDirectory`: ```csharp From c7e937288f9257e9b53960b9806c343e0e97e351 Mon Sep 17 00:00:00 2001 From: Ben C Date: Wed, 11 Dec 2024 19:40:01 -0500 Subject: [PATCH 4/5] its 2 --- docs/content/pages/guides/prepatchers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/pages/guides/prepatchers.md b/docs/content/pages/guides/prepatchers.md index f62faf84..350c3e1a 100644 --- a/docs/content/pages/guides/prepatchers.md +++ b/docs/content/pages/guides/prepatchers.md @@ -15,7 +15,7 @@ mod folder. ## Creating A Prepatcher -A prepatcher is a simple console app that OWML executes, its only passed the location of your mod folder. +A prepatcher is a simple console app that OWML executes, it's only passed the location of your mod folder. However, it is possible to get the game's location by doing `AppDomain.CurrentDomain.BaseDirectory`: ```csharp @@ -50,6 +50,6 @@ log any exceptions thrown by the prepatcher. Due to the nature of prepatchers, the manager cannot undo changes made by them. This means the game will continue to be modified even if the mod is uninstalled or disabled. -The manager will try it's best to warn the user of this. If your mod has prepatcher and +The manager will try its best to warn the user of this. If your mod has prepatcher and is disabled or uninstalled the manager will show a dialog explaining that your mod has modified game files in an irreversible way and encourages them to validate the game files. From 75702f5974a0a550ae1ef0e557690a15f828d8ac Mon Sep 17 00:00:00 2001 From: Ben C Date: Wed, 11 Dec 2024 19:46:24 -0500 Subject: [PATCH 5/5] Update prepatchers.md --- docs/content/pages/guides/prepatchers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/pages/guides/prepatchers.md b/docs/content/pages/guides/prepatchers.md index 350c3e1a..a1c64827 100644 --- a/docs/content/pages/guides/prepatchers.md +++ b/docs/content/pages/guides/prepatchers.md @@ -42,7 +42,7 @@ Due to a lack of `ModHelper`, you'll need to use `Console.WriteLine` to log info This **will not output to the manager window**. To test prepatchers, we recommend you launch `OWML.Launcher.exe` in a terminal directly to properly see stdout. -If a prepatcher errors it *should usually* be outputted to the manage window as OWML is setup to catch and +If a prepatcher errors it *should usually* be outputted to the manager window as OWML is setup to catch and log any exceptions thrown by the prepatcher. ### Warnings