Skip to content

Commit

Permalink
Docs update
Browse files Browse the repository at this point in the history
  • Loading branch information
Noggog committed Oct 27, 2024
1 parent fd73637 commit 6f1ba19
Show file tree
Hide file tree
Showing 16 changed files with 43 additions and 47 deletions.
6 changes: 3 additions & 3 deletions docs/External-Program.md → docs/External-Program-Patcher.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# External Program Patcher
This type latches on and executes any executable program (exe). It will pass along the Synthesis [command line arguments](CLI-Specification.md) to inform the program of what it should be patching, and where to put its results.
This type latches on and executes any executable program (exe). It will pass along the Synthesis [command line arguments](devs/Patcher-CLI.md) to inform the program of what it should be patching, and where to put its results.

![External Patcher](images/external-patcher.png)

## Goals and Reasons to Choose
This patcher type is meant for non-Mutagen based patcher programs that want to participate in a Synthesis patch pipeline. As long as the program can take in the [command line arguments](CLI-Specification.md), and produce a patch file in the desired location, it can be a patcher within Synthesis.
This patcher type is meant for non-Mutagen based patcher programs that want to participate in a Synthesis patch pipeline. As long as the program can take in the [command line arguments](devs/Patcher-CLI.md), and produce a patch file in the desired location, it can be a patcher within Synthesis.


!!! tip "Not for Mutagen-Based Patchers"
This is not typically used with Mutagen-based patchers, as [Git Repository](Git-Repository.md) or [Local Solution](Local-Solution.md) are better options.
This is not typically used with Mutagen-based patchers, as [Git Repository](Git-Repository-Patcher.md) or [Local Solution](Local-Solution-Patcher.md) are better options.

## Required Input
The only required input is a path to the executable file to run.
File renamed without changes.
2 changes: 1 addition & 1 deletion docs/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ Be sure to read the rest of the wiki for how to use the app.
### Are You a Developer?
There are a lot of resources on how to get started creating a patcher

[:octicons-arrow-right-24: Create a Patcher](Create-A-Patcher.md)
[:octicons-arrow-right-24: Create a Patcher](devs/Create-a-Patcher.md)
4 changes: 2 additions & 2 deletions docs/Local-Solution.md → docs/Local-Solution-Patcher.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This style uses a local C# project which is compiled and run as a patcher.
!!! tip "Preferred for Developers, When Needed"
While this is the preferred patcher choice for developers, note that running during normal development should be done from your IDE, and not through the Synthesis UI

[:octicons-arrow-right-24: Running a Patcher](Running-And-Debugging.md)
[:octicons-arrow-right-24: Running a Patcher](devs/Running-and-Debugging.md)

## Required Input
The basic input required is:
Expand All @@ -39,4 +39,4 @@ Settings you can modify:
- Patcher display name
- One line description
- Multi-line extended description
- Whether to show in the [patcher browser](https://github.com/Mutagen-Modding/Synthesis/wiki/Git-Repository#patcher-browser) by default
- Whether to show in the [patcher browser](Git-Repository-Patcher.md#patcher-browser) by default
6 changes: 1 addition & 5 deletions docs/Typical-Usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,6 @@ There are a few alternatives, but the one recommended for new users is the [Git

![Git Repository Patcher](images/git-repo-patcher.png)

You can read about the other types of patchers:

[:octicons-arrow-right-24: Patcher Types](Patcher-Types.md)

### Installing a Git Patcher
#### Browse
You can either look around in the wild yourself, or you can make use of the built in list of existing patchers. Within a `Git Repository` patcher, there is a `Browse` section with an automatically populated list:
Expand Down Expand Up @@ -64,7 +60,7 @@ You can click on any specific patcher to see specifics about it, or any errors i

Running the pipeline will export a file [per patcher group](Multiple-Output-Targets.md) to your `Data` folder.

[:octicons-arrow-right-24: Customizing Data Folder Location](Overriding-Data-Folder-Path.md)
[:octicons-arrow-right-24: Customizing Data Folder Location](DataFolder.md)

[:octicons-arrow-right-24: Multiple Output Files](Multiple-Output-Targets.md)

Expand Down
10 changes: 5 additions & 5 deletions docs/devs/Coding-a-Patcher.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Coding a Patcher
## Starting Setup
If you used a Local [Solution Patcher](Local-Solution.md) to [Create a Patcher](Create-a-Patcher.md), then you will have a project that has a minimal basic setup:
If you used a Local [Solution Patcher](../Local-Solution-Patcher.md) to [Create a Patcher](Create-a-Patcher.md), then you will have a project that has a minimal basic setup:

```cs
public static async Task<int> Main(string[] args)
Expand All @@ -26,9 +26,9 @@ Whatever changes you want to be made should be applied to the `state.PatchMod` o
The state object given to your `RunPatch` contains several important objects:

- PatchMod: The export patch mod object that all changes should be applied to
- [LoadOrder](https://github.com/Mutagen-Modding/Mutagen/wiki/Load-Orders-and-Winning-Overrides): Object containing all the readonly mod objects on the load order
- [LinkCache](https://github.com/Mutagen-Modding/Mutagen/wiki/LinkCache%3A-Record-Lookup): Link Cache created from the load order
- ExtraSettingsDataPath: Path where any custom [Internal Data](https://github.com/Mutagen-Modding/Synthesis/wiki/Internal-Data) will be located
- [LoadOrder](https://mutagen-modding.github.io/Mutagen/loadorder/): Object containing all the readonly mod objects on the load order
- [LinkCache](https://mutagen-modding.github.io/Mutagen/linkcache/): Link Cache created from the load order
- ExtraSettingsDataPath: Path where any custom [Internal Data](Internal-Data.md) will be located

## Typical Simple Code
Typical code for a Synthesis patcher consists of locating Winning Overrides for a record type, and adding them to the output patch mod with some changes. Here is a simplistic example:
Expand All @@ -53,4 +53,4 @@ The above code will shrink any Goblin-named NPCs
Two good resources for learning further details:

- A large catalogue of [existing patchers](https://github.com/Mutagen-Modding/Synthesis/network/dependents?package_id=UGFja2FnZS0xMzg1MjY1MjYz) to look at for examples
- In-depth Mutagen documentation found on the [Mutagen wiki](https://github.com/Mutagen-Modding/Mutagen/wiki).
- In-depth Mutagen documentation found on the [Mutagen wiki](https://mutagen-modding.github.io/Mutagen/).
4 changes: 2 additions & 2 deletions docs/devs/Configuring-a-Patcher-at-Startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,13 @@ You can also pass `SetTypicalOpen` any C# Action, which will give you the abilit
Capstone call to the SynthesisPipeline builder which takes in the arguments given to your app when it started and runs the patcher given the rules you've specified. The program will do nothing if this is missing.

## SetAutogeneratedSettings
Associates a settings file with a settings object. This allows you to get [easy autogenerated settings](https://github.com/Mutagen-Modding/Synthesis/wiki/User-Input#automatic-settings-ui-system) provided by Synthesis.
Associates a settings file with a settings object. This allows you to get [easy autogenerated settings](User-Input.md#automatic-settings-ui-system) provided by Synthesis.

The main method just passes the arguments given your program to the Synthesis systems, which handles all the various commands that could be passed in. Generally, the main method can be left as-is.

## AddRunnabilityCheck
Provides a callback to check if your patcher sees itself as having all the necessary things it needs to run, and block execution until those requirements are satisfied.
[Read More](https://github.com/Mutagen-Modding/Synthesis/wiki/Required-Mods-and-Runnability-Checks)
[Read More](Runnability-Checks.md)

## SetOpenForSettings
This is a more advanced option, which allows your patcher to be opened as a settings editor. It requires you to modify your patcher project a lot, so that it is simultaneously a patcher executable as well as a UI application. If that is set up, then this call provides the entry point to know when to open your application as a UI for settings input.
8 changes: 4 additions & 4 deletions docs/devs/Create-a-Patcher.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You will also need the [DotNet SDK](https://dotnet.microsoft.com/download), but
## Solution Patcher
Synthesis provides bootstrapping functionality to get new Mutagen patchers off the ground fairly easily.

These systems can be found by creating a new [Local Solution patcher](Local-Solution.md), which is the preferred patcher type for developers.
These systems can be found by creating a new [Local Solution patcher](../Local-Solution-Patcher.md), which is the preferred patcher type for developers.

![Solution Patcher](../images/solution-patcher.png)

Expand All @@ -24,14 +24,14 @@ When creating a new patcher, Synthesis will construct and set up several default
- Creates a solution
- Creates a project, with both Synthesis and Mutagen imported
- Creates a default main method, which is hooked into the standard Synthesis pipeline.
- Enables [nullability compiler features](https://github.com/Mutagen-Modding/Mutagen/wiki/Classes%2C-Interfaces%2C-and-Record-Presence#nullability-to-indicate-record-presence), which are very important when utilizing Mutagen
- Enables [nullability compiler features](https://mutagen-modding.github.io/Mutagen/familiar/Nullability-to-Indicate-Record-Presence/), which are very important when utilizing Mutagen
- Default gitignore
- Hides/upgrades some specific error types

!!! tip "Prefer IDE"
The solution patcher should not be used to execute your program during normal development. Run through your IDE instead while you're writing code to get debugging features.

[:octicons-arrow-right-24: Running a Patcher](Running-And-Debugging.md)
[:octicons-arrow-right-24: Running a Patcher](Running-and-Debugging.md)

## Locating the Code
The Local Solution Patcher can open your preferred IDE, or you can navigate and open the solution yourself.
Expand Down Expand Up @@ -71,4 +71,4 @@ Patchers that are listed on the store use a meta json file to specify some custo

[:octicons-arrow-right-24: Coding a Patcher](Coding-a-Patcher.md)

[:octicons-arrow-right-24: Running a Patcher](Running-And-Debugging.md)
[:octicons-arrow-right-24: Running a Patcher](Running-and-Debugging.md)
8 changes: 4 additions & 4 deletions docs/devs/Nexus-Integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ Typically mods are uploaded straight to the Nexus. However, Synthesis mods are
- Easily browsable source code
- Ability for others to contribute fixes/upgrades as Pull Requests

Additionally, the Synthesis system leverages these [Git Patchers](https://github.com/Mutagen-Modding/Synthesis/wiki/Git-Repository) to fulfill many other features:
Additionally, the Synthesis system leverages these [Git Patchers](../Git-Repository-Patcher.md) to fulfill many other features:

- Automatic listing in the Synthesis search systems
- Automatic upgrades over time via the [Versioning System](https://github.com/Mutagen-Modding/Synthesis/wiki/Versioning), which reduces the need for maintenance on your end.
- Automatic upgrades over time via the [Versioning System](../Versioning.md), which reduces the need for maintenance on your end.

## Create a .Synth File
Synthesis offers a `.synth` file that acts as a convenience installer. The concept is unnecessary if users are familiar with the [Git Repository Browser](Typical-Usage.md#browse) systems. However, for Nexus, it allows us to create a file that we can upload for our mod listing.
Synthesis offers a `.synth` file that acts as a convenience installer. The concept is unnecessary if users are familiar with the [Git Repository Browser](../Typical-Usage.md#browse) systems. However, for Nexus, it allows us to create a file that we can upload for our mod listing.

Please refer to the [.synth File](Synth-File.md) page for more details
Please refer to the [.synth File](../Synth-File.md) page for more details

## Uploading Exes
One alternative is to compile the exe yourself, and upload that to the Nexus. This is undesirable for a few reasons:
Expand Down
3 changes: 2 additions & 1 deletion docs/devs/Patcher-CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ Most of the documentation so far has been focused on making Mutagen-based patche
- Shut down

## Run Patcher CLI
The Synthesis pipeline passes in [command line arguments](https://github.com/Mutagen-Modding/Synthesis/blob/release/Synthesis.Bethesda/CLI/RunSynthesisPatcher.cs) to request a patch to be made.
The Synthesis pipeline passes in [command line arguments](https://github.com/Mutagen-Modding/Synthesis/blob/dev/Synthesis.Bethesda/Commands/RunSynthesisPatcher.cs) to request a patch to be made.

- `-s`/`--SourcePath`: Optional path to the previous patch file to build onto
- `-o`/`--OutputPath`: Path an output patch is expected to be written to
- `-g`/`--GameRelease`: The game the patch is expected to be run on (SkyrimSE/SkyrimLE/Oblivion/etc)
Expand Down
17 changes: 8 additions & 9 deletions docs/devs/Publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ Once you have a patcher that you want to share with the world, there are a few o
Uploading to Github is the preferred route for publishing a patcher.

- Automatically listed in the Patcher Browser registration systems.
- Still can be used with the [Nexus](https://github.com/Mutagen-Modding/Synthesis/wiki/Nexus-Integration)
- Easy versioning via [tags](https://github.com/Mutagen-Modding/Synthesis/wiki/Publishing-a-Patcher#versioned-tags-to-mark-releases)
- Easy exposure of "experimental" versions to willing users via [branches](https://github.com/Mutagen-Modding/Synthesis/wiki/Publishing-a-Patcher#branches)
- Gives your end users ability to [upgrade to newer Mutagen/Synthesis versions](https://github.com/Mutagen-Modding/Synthesis/wiki/Git-Repository#mutagensynthesis-version) without bugging you
- Still can be used with the [Nexus](Nexus-Integration.md)
- Easy versioning via [tags](Publishing.md#versioned-tags-to-mark-releases)
- Easy exposure of "experimental" versions to willing users via [branches](Publishing.md#branches)
- Gives your end users ability to [upgrade to newer Mutagen/Synthesis versions](../Git-Repository-Patcher.md#versioning) without bugging you
- Will hook in to [systems](https://github.com/Mutagen-Modding/Synthesis/issues/42) to improve overall patching speed, that will be developed in the future
- Source code is viewable, and people can help improve it with PRs

Expand Down Expand Up @@ -96,17 +96,16 @@ In order to be found/listed there are a few requirements:
- In a git repository uploaded to GitHub.com
- Solution is top level (#211)
- At least one patcher project which imports the `Mutagen.Bethesda.Synthesis` NuGet package
- (Optional) Patcher meta json file specifying description and other information. These can be made easily by utilizing the [Solution Patcher](https://github.com/Mutagen-Modding/Synthesis/wiki/Local-Solution) system made for devs
- (Optional) Patcher meta json file specifying description and other information. These can be made easily by utilizing the [Solution Patcher](../Local-Solution-Patcher.md) system made for devs

The [Local Solution patcher wizard](https://github.com/Mutagen-Modding/Synthesis/wiki/Local-Solution) will create an automatically compatible setup **EXCEPT** the first step of creating and uploading to GitHub. This responsibility is on the patcher developer to create their Github presence.
The [Local Solution patcher wizard](../Local-Solution-Patcher.md#new-patcher-wizard) will create an automatically compatible setup **EXCEPT** the first step of creating and uploading to GitHub. This responsibility is on the patcher developer to create their Github presence.

**NOTE:**
It is possible to have a single solution with several patcher projects underneath. Whether you prefer a separate solution and repository per patcher, or one large repository with several patchers is up to personal preference.

### Troubleshooting Registration
### Github Dependency Graph
The scraper tech functions by looking at the GitHub dependency graph systems. The list can be found here:
<https://github.com/Mutagen-Modding/Synthesis/network/dependents>
The scraper tech functions by looking at the GitHub dependency graph systems. [The list can be found here](https://github.com/Mutagen-Modding/Synthesis/network/dependents)

There is also a list on your patcher side, where it shows what it is dependent on. This will be in the same area, just in your own repo.

Expand All @@ -120,4 +119,4 @@ Sometimes there can be error during the scraping event. The scraper system tri
If you see your patcher with an error, see if it makes sense and if you can adjust for what it's complaining about.

## Build Executable
You can also build an executable, and distribute the `exe` directly for users. They would then add it as an [External Program Patcher](https://github.com/Mutagen-Modding/Synthesis/wiki/External-Program)
You can also build an executable, and distribute the `exe` directly for users. They would then add it as an [External Program Patcher](../External-Program-Patcher.md)
4 changes: 2 additions & 2 deletions docs/devs/Running-and-Debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The `SetTypicalOpen` call that comes with the typical template informs your patc
#### Explicit Side Environment
A typical run will look to your default Plugins.txt and Data folder, which may or may not contain content you want to test against. One route for testing against a specific load order is to set up a secondary side `Data` folder and `Plugins.txt` load order file.

To tell your patcher to latch onto that side environment, you can utilize the [CLI Arguments](CLI-Specification.md) to give it the details to use. Here is an example set of arguments:
To tell your patcher to latch onto that side environment, you can utilize the [CLI Arguments](Patcher-CLI.md) to give it the details to use. Here is an example set of arguments:

```
run-patcher --GameRelease SkyrimSE --DataFolderPath "Path/To/Side/Data"
Expand All @@ -23,7 +23,7 @@ run-patcher --GameRelease SkyrimSE --DataFolderPath "Path/To/Side/Data"


### Solution Patchers via Synthesis GUI
Patcher solutions can be run from inside the Synthesis GUI, by adding them as a Synthesis patcher. The recommended type is [Solution](https://github.com/Mutagen-Modding/Synthesis/wiki/Local-Solution) patchers, but [External Program](https://github.com/Mutagen-Modding/Synthesis/wiki/External-Program) can be used, too.
Patcher solutions can be run from inside the Synthesis GUI, by adding them as a Synthesis patcher. The recommended type is [Solution](../Local-Solution-Patcher.md) patchers, but [External Program](../External-Program-Patcher.md) can be used, too.

Notes:
- Lets you run your in-development patcher alongside several other patchers to see their combined results
Expand Down
4 changes: 2 additions & 2 deletions docs/devs/Supporting-Multiple-Games.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Supporting Multiple Games

## Supporting Multiple Games
By adding a [2nd (or more) AddPatch commands](https://github.com/Mutagen-Modding/Synthesis/wiki/Configuring-a-Patcher-at-Startup#addpatch) to your SynthesisPipeline you can have your patcher support different game categories. Note that the generics will be for a different Mod object, and so a 2nd RunPatch callback with the appropriate mod will be required as an entry point
By adding a [2nd (or more) AddPatch commands](Configuring-a-Patcher-at-Startup.md#addpatch) to your SynthesisPipeline you can have your patcher support different game categories. Note that the generics will be for a different Mod object, and so a 2nd RunPatch callback with the appropriate mod will be required as an entry point
```cs
public static async Task<int> Main(string[] args)
{
Expand All @@ -26,6 +26,6 @@ public static void RunPatch(IPatcherState<IFallout4Mod, IFallout4ModGetter> stat
At this point, your patcher supports multiple game types, and can respond accordingly when it is run with either game.

## Code Reuse
The entry points as shown above make it easy to "support" multiple games, but it is still a challenge to properly develop your code in a way that it can be reused for both. It requires more advanced knowledge of [generics](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/types/generics), [Aspect Interfaces](https://github.com/Mutagen-Modding/Mutagen/wiki/Interfaces-%28Aspect-Link-Getters%29#aspect-interfaces), [Reflection](https://www.tutorialspoint.com/csharp/csharp_reflection.htm), and other similar concepts.
The entry points as shown above make it easy to "support" multiple games, but it is still a challenge to properly develop your code in a way that it can be reused for both. It requires more advanced knowledge of [generics](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/types/generics), [Aspect Interfaces](https://mutagen-modding.github.io/Mutagen/plugins/Interfaces/), [Reflection](https://www.tutorialspoint.com/csharp/csharp_reflection.htm), and other similar concepts.

Making multi-game support easier to code without dipping into as many of those advanced concepts is a frontier topic of Mutagen, so feel free to stop by the discord and chat and brainstorm!
Loading

0 comments on commit 6f1ba19

Please sign in to comment.