Modding Basics

This page outlines the basic tools required to create a mod for Star Valor and links to useful external resources.

### Tools

#### BepInEx

Unity plugin loader. Download includes harmony, a library for patching, replacing and decorating .NET methods during runtime.

Used for creating mods. Alternatives do exist and are equally viable. If you use BepInEx to create a plugin style mod, remember to include the requirement for the user to install it in your installation instructions.

BepInEx Install Instructions and download link. - Star Valor currently requires x86 version. Recommend the latest stable release.

Harmony documentation

Once installed, it is recommended to enable the BepInEx console by opening .\steamapps\common\Star Valor\BepInEx\config\BepInEx.cfg in a text editor and changing Enabled to true in the following section:

```
[Logging.Console]
# Default value: false
Enabled = true

```

#### dnSpy

A .NET assembly manager. Primarily for exploring Assembly-CSharp.dll assembly, which contains all of the Star Valor game scripts.

Can be used by itself to modify and re-compile the assembly, but suggest this only for personal use as redistributing Star Valor code, assemblies or assets has possible legal repercussions. Additionally, an end user can install one mode distributed in this way.

dnSpy github page

#### Visual Studio Community

Microsoft's IDE. Not required, any IDE can be used (use a text editor if you like), but provides a lot of useful features and dnSpy allows export to a visual studio solution.

Visual Studio Community Edition download page

#### Unity Editor (only required for asset creation)

Unity engine editor. Only required for creating mods with custom assets (models, textures, audio).

Unity3D download page

#### git (only required for asset creation)

Required for installing Unity Editor packages from git URL. Also a widely used version control system for code bases, but this use is optional for Star Valor modding and a standalone install is not required for use with e.g. Visual Studio.

git download page

### A Simple Mod

This guide will only cover plugin style mods using BepInEx. It is very useful to have some knowledge of:

* The object oriented programming (OOP) paradigm
* The .NET library
* The Unity engine

Having some knowledge or experience with programming is highly desirable. Certainly, exploring behind the scenes of Star Valor could be a fun way to learn and some people even learn better jumping in at the deep end. The following might help with such a journey OOP basics, but this guide will not be a step-by-step for every button press.

The following resources can help with understanding these things and/or serve as a useful reference when making a mod,

* Unity Documentation
* .NET 4.8 API Documentation
* Harmony Manual

Use dnSpy to open .\SteamLibrary\steamapps\common\Star Valor\Star Valor\_Data\Managed\Assembly-CSharp.dll. I recommend saving to a Visual Studio project (File > Export to project). It's far easier to navigate. If you want to modify methods using transpilers (avoid it if you can), you will still need dnSpy to look at IL codes. If you do choose to export, don't forget to update the project after a patch.

That's all you need to do to start poking around at the guts of Star Valor. It's worth browsing this to get an understanding of how the game is organised. If you have a mod idea in mind, try to find what and where you need to change things. A personal preference, but I keep my Star Valor project open in a separate Visual Studio window and alt-tab back and forth frequently to check things, copy-paste a method name for a patch to avoid typos and so on.

In Visual Studio (or your chosen IDE), create a C# .dll library project. Target .NET version 4.7.1. Import the following .dlls as references. They can all be found in .\SteamLibrary\steamapps\common\Star Valor\Star Valor\_Data\Managed\ except for BepInEx.dll and 0Harmony.dll which come as part of the BepInEx download:

* 0Harmony.dll
* Assembly-CSharp.dll
* BepInEx.dll
* UnityEngine.CoreModule.dll
* UnityEngine.dll
* UnityEngine.SharedInternalsModule.dll

The following .dlls can also be useful. In general, if you try to reference something and Visual Studio cannot resolve the type, it is generally a class in the Unity engine that has not been referenced. The Unity API is very useful to finding where things are (and therefore which .dll you need) in such cases:

* UnityEngine.InputLegacyModule.dll
* UnityEngine.PhysicsModule.dll
* UnityEngine.TextRenderingModule.dll
* UnityEngine.UI.dll
* UnityEngine.UIModule.dll

Modding using BepInEx and Harmony involves prefixing or postfixing existing game methods to run additional code or modify parameters or outputs. The Harmony documentation describes these functions in depth.

I have uploaded a very basic BepInEx plugin Visual Studio solution to github, which you can access here. The mod changes the Star Valor BuffRefinery class such that the refine time is 0.2 seconds.

The only file here I had to edit myself was Main.cs.

All the BepInEx related stuff is right at the top:

```
[BepInPlugin(pluginGuid, pluginName, pluginVersion)]
public class Main : BaseUnityPlugin
{
 public const string pluginGuid = "mc.starvalor.fastrefining";
 public const string pluginName = "SV Fast Refining";
 public const string pluginVersion = "1.0.0";

```

So the mod's main class extends BaseUnityPlugin. The rest is just meta data for BepInEx. These strings can be whatever you like.

Below that, we have an Awake method. Note that the methods Awake, Start, Update, FixedUpdate and so on are all Unity Engine concepts. Refer to the Unity engine documentation for more information but essentially they are executed when it sounds like they are. Awake is first, then Start. Update is called every game update tick. FixedUpdate is similar, but always executes at fixed time intervals and is generally used for physics related code.

Anyway, the Awake method...

```
 public void Awake()
 {
 Harmony.CreateAndPatchAll(typeof(Main));
 }

```

This doesn't actually do anything mod-specific. Just a single line of code that tells the Harmony library to apply all of the patches I have defined in my mod.

and that patch is next:

```
 [HarmonyPatch(typeof(BuffRefinery), "Begin")]
 [HarmonyPrefix]
 private static void BuffRefineryBegin\_Pre(ref float \_\_\_refineTime)
 {
 \_\_\_refineTime = 0.2f;
 }

```
so the method doesn't start until the 3rd line here. The annotations above are for harmony.

In the first line I tell harmony I want to patch the Begin method in the BuffRefinery class. This class name and method name come from the Star Valor game code extracted from Assembly-CSharp.dll. I chose the Begin method because, I don't care what the refine time is on a refinery until it begins refining. I might have chosen "Start", but the refineTime is set by other parts of the game code to account for player skills, the refinery they have equipped on their ship and so on, so any modification at "Start" would be overridden.

The next line tells Harmony what kind of patch it is. This will generally only ever be "[HarmonyPrefix]" or "[HarmonyPostfix]" and just tells harmony to run this before or after the original method specified in the line above.

Third, we have a method signature. There are no real constraints here except that patch methods should be static. The name can be whatever you like.

I also have a parameter that does not exist in the original method (the BuffRefiner.Begin method). The refineTime variable is a field in the BuffRefinery class, so here the field name is prefixed by 3 x '\_'. This can also be used to access private fields not normally accessible to other parts of the Star Valor codebase. The "ref" keyword is only required if you want to modify the value of the object being patched. If you just want to read it, you do not need to pass the parameter by reference.

You can also access the instance of object being patched:

```
private static void BuffRefineryBegin\_Pre(BuffRefinery \_\_instance, ref float \_\_\_refineTime)

```

The new parameter \_\_instance would allow access to any public fields or methods for the instance of the BuffRefinery class currently executing this patch. If I wanted to manipulate several parameters from the original object, this might be preferable to several individual field references. You will not be able to access private or protected fields or methods without further reflection. The harmony documentation provides some examples of the Harmony.AccessTools library. It's generally easier to access private fields by adding parameters to the patch method.

Then the method body, I just set the "refineTime" field of the object being patched to 0.2 seconds.

Compile. Copy the MC\_SVFastRefining.dll from .\MC\_SVFastRefining\MC\_SVFastRefining\bin\Debug to .\SteamLibrary\steamapps\common\Star Valor\BepInEx\Plugins and run the game.

So:

* Find what you need to patch
* Find the best place to patch it
	+ It is useful to use Visual Studios "Find all references" feature (right-click, find all references) in the Star Valor project exported from dnSpy. This will show you all the places a particular field is modified throughout the Star Valor game code.
* Create the patch, compile it and stick it in the plugins folder

When distributing your mod, all you need to share is the .dll :)