Modding

Modding allows you to tailor Phoenix Point (Game), beyond the options offered out of the box, for a customised experience.
Example ranges from bug fixing and QoL improvements, to new features not found in base game.

If you have modding questions not answered here, try the #mods channel on the official discord.

## Disclaimer

Modding is **not** officially supported by Snapshot Games.
*All* modding tools and mods are fan-made programs that literally modify your game.
They can do funny things to your computer, which you may find not so funny.
Hackers are known to disguise their malwares as mods.

Of course, most mods are made by passionate fans, and generally safe.
But even well-intended and well-made tools and mods can brick your game or saves, if they clash with each other or an official update.
When even official patches can trash your top-tier assault rifles and destroy your inventory, what can you expect?

## Using Mods

Since modding is not supported, you need mod loaders to use mods.
Loaders and mods are well-tested for the Epic Game Store version, on Windows.
(Mac is a walled garden. Consoles even more.)

A certain level of computer literacy is required.
Most reports of mods not working are non-coding related,
such as confusing the three incompatible PPML versions,
game updates undoing mod loaders,
or mods not placed in the correct folder.

Three mod loader "families" are available:

* Modnix, by Sheepy
* PPML 0.2 and 0.3, by Ijwu
* PPML 0.1, by RealityMechania

Mod loaders don't mix well, please do not install multiple loaders.

Official game updates will undo the changes made by mod loaders.
You *must* re-setup your mod loader after every patch to "restore" the mods.

Compatibility table:

 Modnix | Yes²
 PPML 0.3 | x
 PPML 0.2 | x
 PPML 0.1 | x

Notes:

1. A mod can be both Modnix and PPML (one version), for example a mod may be Modnix + PPML 0.1.
2. Modnix has a few versions, but new versions are generally compatible with old mods.
3. Modnix 2.0 supported PPML 0.3 instead of 0.2. All other versions supports PPML 0.2.
4. Result may varies. A mod may work differently under different loaders, e.g. Skip Intro, Debug Console.
5. PPML 0.3 is incompatible with 0.2 despite its claim.
6. PPML 0.2 / 0.3 mods *always* crash PPML 0.1 since they must hard-reference the loader.

### Modnix Setup

Follow these steps to setup Modnix.

1. Make sure game is not running.
2. Download an installer from NexusMods or GitHub.
3. Run the installer. Say yes when it ask for admin rights, required for PPML compatibility.
4. If success, it will open the exe in Windows Explorer. Right click it to Pin to Start or Send to Desktop.
5. Launch Modnix. Note the Add Mod button on top, which can be used to install downloade mods.
6. The installer may now be deleted. Use the main program to re-setup after game updates.

You may find and download mods from Nexus Mods.
Some mods may have a "mirror" that allow you to download off-site, typically GitHub, BitBucket, or similar services.

### PPML Setup

Follow these steps to setup PPML (either version).

1. Make sure game is not running.
2. Find where the game is installed. Epic Game Store defaults to
```
C:\Program Files\Epic Games\PhoenixPoint\
```
 You should find `PhoenixPointWin64.exe` in this folder.
3. Decide which version to use and download. The three versions are NOT compatible.
	1. PPML v0.1, used by most mods, will *crash* if it encounters v0.2 or v0.3 mods
	2. PPML v0.2, used by some new mods, can only load v0.2 mods.
	3. PPML v0.3, used by a few mods, can load v0.1 mods and v0.3 mods.
4. Extracts contents to this game folder:
```
PhoenixPointWin64_Data\Managed\
```
 You should find `Assembly-CSharp.dll` in the folder, before extraction.
5. Run the extracted injector. The second last line should says
```
Injection complete!
```
 Try run as admin if it fails.
6. Launch the game into main menu and then quit. This creates a "Mods" folder at the game path, i.e.
```
C:\Program Files\Epic Games\PhoenixPoint\Mods\
```
 **This is the mod folder.**

Continue with #Installing Mods.

### Installing Mods

Follow these steps to install mods.

1. Find mods on Nexus Mods. **Read carefully** on their compatibilities with mod loaders.
2. Download the mods. Account required. Extract them to the mod folder.
	1. PPML 0.1 loads all 0.1 .dll that are placed at the mod folder's root, but not in subfolders.
	2. PPML 0.2 loads every 0.2 .dll in root and every sub folders.
	3. PPML 0.3 loads 0.1 and 0.3 .dll in root and every sub folders.
	4. Modnix requires that mods are placed at the root or in a subdirectory with a matching name.
	 e.g. `Mods\PowerFix-1-2\PowerFix.dll` is OK
	 e.g. `Mods\cfehunter\PowerFix.dll` is not ok.
3. Some mods may have special requirements. e.g. PPDefModifier requires its .json mods to be placed in the "PPDefModifier" subfolder of the Mods folder.

You may start with simple and easy-to-test mods (non-PPDef), such as Bulk Trade or UI Tweaks, to verify that you got the steps right.
Note that .cs and readme / license files are not required to run mods, and may be deleted or overwritten.

### Uninstalling

Individual mods can be "uninstalled" by deleting them or moving them to a different folder,
when the game is not running.

Modnix can be removed from the game using the main program.
For PPML, run the injector on command line with the "/r" switch to undo its changes.
Either way, all mods will be disabled.

If that sounds like Pandorish to you, you can run "Verity Files" through Epic Game Launcher.
This normally erase all injections and fix any corrupted files (usually *not* caused by mods).
If that doesn't work, try delete all dll files from the game and reboot your computer before verifying.

Mods and vanilla game bugs may break a save in a way that cannot be repaired by erasing mods.
Saves made with mods that add new equipments would fail to load if the mod is removed.
You have been warned.

### Troubleshooting

When *every* mod ceases to function, usually after a game update, re-run PhoenixPointModLoaderInjector.

If you suspect a mod of causing problem, deleting the mod and re-test.
If the problem is now gone, you've found the cause.
Otherwise, keep deleting more mods.

Problem that happens without any mods are most likely vanilla bugs,
which you can press F12 in game to report to the developer.
This official reporter will upload all your saves, and may take a while.

Compatibility is another issue.
Many mods declare which game version they are developed or tested in.
For mods that do not, check the release date.
The more complicated a mod is, the higher chance it would be broken by a game patch.
For example Scrap Vehicles are much more likely invalidated by an update than Skip Intro.

## Making Mods

Official mod support is planned.
That is all.

Unofficially, the game assembly and assets are unencrypted and can be modified by having the right skills.

As of writing, two kinds of mods can be made:

1. C# based dll mods that hijack the game on the run. Modnix has a Quick Start.
 Use dnSpy to read code, then use Harmony to patch.
 Most mods come with source code which you can copy and learn from.
2. PPDefModifier json mods that change live game data.
 Easy way: read existing PPDef mods and see what they can modify and how.
 Hard way: Use Asset Studio to read game data structure, and write .json as specified by PPDefModifier.

Asset mods will be depending on improved modding tools.
Because the game's art assets change location with every patch, overwriting asset file not only break fast, but actually carry a very high risk of breaking the game.