BepInEx for KSP 2: Adding modding support to the game

[bbepis]

BepInEx for KSP 2

https://github.com/BepInEx/BepInEx

LGPL v2.1

Sourcecode

 

What is BepInEx?

BepInEx is a tool used to allow modding / custom code execution in Unity and other C# based games. As of writing KSP 2 does not support loading arbitrary mods, so the only way to run addons & load assets is through this loader.

Harmony and MonoMod.RuntimeDetour are packaged with this loader, allowing you to modify game code & functions at runtime.

BepInEx uses "plugin" to refer to the equivalent of Addons in KSP.

 

Additional features as compared to KSP 1 style modding

• Ability to modify .dll files before they are loaded, which allows for modifications not possible with Harmony.
  • Editing enums, patching static constructors, adding entirely new types to a specific assembly, immune to JIT inlining etc.
• Much earlier code execution meaning that you are able to modify the game (and Unity itself) before it even starts loading
• External console & logging so that you don't have to scour game logs for any info / error output
• Fixes certain issues with Unity operating on platforms other than Windows
• Includes dependency handling to ensure mods that rely on other mods are loaded in the correct order, or not at all if prerequistes are missing
• Has a consistent way of reading / writing / manipulating configuration per plugin
• Contains base libraries (such as Harmony) to prevent conflicts with mods providing their own, differing versions

 

Other features

• Immune to being uninstalled by game updates; no files are replaced
• Supports Windows, Linux and Mac OSX
• Has dev tools that you can use to assist in plugin development
  •  i.e. being able to reload plugins while the game is running, a UI to examine the entire loaded scene etc.

 

Getting started

For Windows:

1. Download the latest version of BepinEx v5 x64 from here (make sure not to get v6, as it has a different API contract and doesn't properly support KSP 2 yet)
2. Extract the folder such that your game looks like this:

Spoiler

You are done!

If you get stuck with the installation process, please refer to the documentation: https://docs.bepinex.dev/articles/user_guide/installation/index.html

 

For Linux/Unix/OSX:

It is more or less the same process, with some minor differences. Refer to the above documentation

 

Installing plugins

To install plugins, place them inside of your BepInEx/plugins folder. (This directory might not exist for you; launch the game once to have BepInEx generate its folder structure)

While it's possible to place every .dll file in any place in BepInEx/plugins, it's strongly recommended that you have one folder per mod to make it significantly easier to manage updates and uninstallation.

 

Creating BepInEx plugins

A guide exists here for writing your first BepInEx plugin: https://docs.bepinex.dev/articles/dev_guide/plugin_tutorial/index.html

As reference here is a pre-made C# project for an example plugin that does two things:

• Creates an in-game notification when you press F2
• Changes all of the translatable strings in the game to "Chungus" on pressing F3

Edited February 26 by bbepis

[Gargamel]

@bbepis Please include a link to the source code for this. 

[KamikazeF0X]

Ha, you were faster than the MelonLoader guys XD

But I'd honestly advice people to not rely 100% on your solution (Or Melon), I don't wanna be rude by saying that, but there is bits of mod loader code in the game already, the devs might add an official one soon enough (maybe even a workshop?)

[bbepis]

1 hour ago, KamikazeF0X said:

Ha, you were faster than the MelonLoader guys XD

But I'd honestly advice people to not rely 100% on your solution (Or Melon), I don't wanna be rude by saying that, but there is bits of mod loader code in the game already, the devs might add an official one soon enough (maybe even a workshop?)

Well you never know. There's been a few games before where they've decided against making their own modding platform and supported BepInEx officially instead

[GoldForest]

55 minutes ago, bbepis said:

Well you never know. There's been a few games before where they've decided against making their own modding platform and supported BepInEx officially instead

Official support for KSP 2 is coming, it's not an if, but a when. KSP 2 won't abandon official support. I'm fairly confident in that. 

[linuxgurugamer]

On 2/24/2023 at 11:51 AM, bbepis said:

Creating BepInEx plugins

A guide exists here for writing your first BepInEx plugin: https://docs.bepinex.dev/articles/dev_guide/plugin_tutorial/index.html

That guide is extremely generic, would be helpful if you rewrote it targeting KSP2 directly.  And, since right now KSP 2 is only on Windows, maybe target Visual Studio as well?

For example, the command I used to create my first project in this  was:

dotnet new bepinex5plugin -n MyFirstPlugin -T  net481 -U 2020.3.33

Not sure yet if this is correct, I guess I'll find out soon

 

Edit:  This didn't work, see below for a post which describes how to do this

Edited February 26 by linuxgurugamer

[Murphy Kerman]

Quote

Multiplayer/Modding: The technological developments made to the foundations of Kerbal Space Program 2 will build on the beloved modding capabilities of the original game, as well as deliver on the long-requested addition of multiplayer. Soon players will be able to share the challenges of deep space exploration. More details on these features will be revealed at a later tim

This is from the kerbalspaceprogram.com website

[bbepis]

33 minutes ago, linuxgurugamer said:

That guide is extremely generic, would be helpful if you rewrote it targeting KSP2 directly.  And, since right now KSP 2 is only on Windows, maybe target Visual Studio as well?

I'll see what I can do.

21 minutes ago, Murphy Kerman said:

This is from the kerbalspaceprogram.com website

I'm aware but are you able to add mods to the game right now through any official method?

[Murphy Kerman]

12 minutes ago, bbepis said:

I'm aware but are you able to add mods to the game right now through any official method?

No right now the only way to mod the game is through either BepInEx or SpaceWarp.

[Murphy Kerman]

For the example program, where do you get 

using KSP.Game;

and 

using I2.Loc;

?

[munix]

2 minutes ago, Murphy Kerman said:

For the example program, where do you get 

using KSP.Game;

and 

using I2.Loc;

?

You have to link the KSP2_x64_Data\Managed\Assembly-CSharp.dll library to your project

[Murphy Kerman]

Thanks!

1 minute ago, munix said:

You have to link the KSP2_x64_Data\Managed\Assembly-CSharp.dll library to your project

 

[linuxgurugamer]

Ok, so what you need to do in order to be able to compile code using BepinEx for KSP2.  These will be Visual Studio based, on Windows:

1. Install the mod manager per the instructions
2. Create a new project using Visual Studio
3. Add assembly references to the following code assemblies:
   1. 0Harmony
   2. Assembly-CSharp
   3. BepInEx
   4. System
   5. System.Core
   6. UnityEngine
   7. UnityEngine.CoreModule
   8. UnityEngine.IMGUIModule
   9. Unityengine.InputLegacyModule
4. You may not need all of these, and you may need others, but the first 7 lines are probably always going to be needed.  The code assemblies are going to be found in the following directory:

   <KSP2_DIR>\BepInEx\core\0Harmony.dll
   <KSP2_DIR>\KSP2_x64_Data\Managed\Assembly-CSharp.dll
   <KSP2_DIR>\BepInEx\core\BepInEx.dll
   <KSP2_DIR>\KSP2_x64_Data\Managed\UnityEngine.dll
   <KSP2_DIR>\KSP2_x64_Data\Managed\UnityEngine.CoreModule.dll
   <KSP2_DIR>\KSP2_x64_Data\Managed\UnityEngine.IMGUIModule.dll
   <KSP2_DIR>\KSP2_x64_Data\Managed\UnityEngine.InputLegacyModule.dll

   Replace the <KSP2_DIR> with wherever your KSP2 install is.

5. Create your plugin file, make sure the following is there:
    

   using BepInEx;
   using KSP.Game;
   using UnityEngine;
   using System.Collections.Generic;
   using System.Linq;
   
   namespace MyMod
   {
       [BepInPlugin("io.bepis.mymod", "MyMod", "1.0")]
       public class MyMod : BaseUnityPlugin
       {

   This is just an example, obviously the contents will depend on the mod you are writing.

[neocromicon]

Can i use BepInEx and SpaceWarp simultaneously? I hope yes

Edited February 26 by neocromicon

[Rofl47]

7 hours ago, neocromicon said:

Can i use BepInEx and SpaceWarp simultaneously? I hope yes

Yes and no. Found this on Spacedock by bbepis, which is supposed to be a SpaceWarp loader inside the BepInEx runtime... but I'm not able to get it to work, and I don't possess the technical know-how to even try to conceive of a workaround. At least for now you can't seem to run them simultaneously, you have to pick from either-or until this gets fixed, which should be soon considering it's only been 2 days since KSP 2 launched to when we got our mod loaders. 

Edited February 26 by Rofl47
words

[neocromicon]

3 minutes ago, Rofl47 said:

Yes and no. Found this on Spacedock by bbepis, which is supposed to be a SpaceWarp loader inside the BepInEx runtime... but I'm not able to get it to work, and I don't possess the technical know-how to even try to conceive of a workaround. At least for now you can't seem to run them simultaneously, you have to pick from either-or until this gets fixed, which should be soon considering it's only been 2 days since KSP 2 launched to when we got our mod loaders. 

Thanks! By me works it good. I have copy the Wrapper into Bep and then i have create the SpaceWarp/Mods folder an put my files. All works.

Edited February 26 by neocromicon

[Rofl47]

7 minutes ago, neocromicon said:

Thanks! By me works it good. I have copy the Wrapper into Bep and then i have create the SpaceWarp/Mods folder an put my files. All works.

Huh. Did the same thing and it doesn't seem to work, like at all. It loads Bep, but not SpaceWarp.

Ah. I can't read, apparently SW is already at 0.2, which means the loader isn't up to date.  PSA apparently: make sure the BepinLoader and SpaceWarp match, do not try to use 0.2 SpaceWarp on a 0.1 Loader.

Wait no, I jumped the gun. SpaceWarp still isn't working. Did I break something?

Edited February 26 by Rofl47
Spacewarp help

[viperfan7]

I wonder if someone can re-create advanced fly by wire for this.

The stock input manager is woefully inadequate

[lordbunson]

I see this is BepInEx 5; I was making my own mods using BepInEx 6. Is there any strong reason to use one version over the other?

EDIT: oh I see now there is some sort of compat issue (although I'm not experiencing it yet, but I've only made it as far as Hello World / Unity Explorer)

On 2/24/2023 at 9:51 AM, bbepis said:

(make sure not to get v6, as it has a different API contract and doesn't properly support KSP 2 yet)

Edited February 27 by lordbunson
Corrections

[Demcrew]

Hello everyone! 

The dawn of KSP2 has barely broken and many thanks to the dedicated modders who are already working to make our lives easier.

I have been reading with curiosity about the content of the mods, but especially about the mod loaders.
I don't know if having two types of loaders is really relevant for a KSP2 launch.
BepinEx and SpaceWarp both seem to be effective. But the community might lose out.
Then again, from what I've read, KSP2 will have an integrated loader.

So either we go with what P.D. and the development team will provide, or we go for a community approach. In the latter case, I think we should definitely simplify mod management. Starting with two different loaders doesn't strike me as the best way forward.

Finally, I don't know what limitations or opportunities one or the other brings to modding. I am also aware that there are other operating systems that need support.
However, could there be some consultation on the best way forward?

[munix]

1 hour ago, Demcrew said:

Hello everyone! 

The dawn of KSP2 has barely broken and many thanks to the dedicated modders who are already working to make our lives easier.

I have been reading with curiosity about the content of the mods, but especially about the mod loaders.
I don't know if having two types of loaders is really relevant for a KSP2 launch.
BepinEx and SpaceWarp both seem to be effective. But the community might lose out.
Then again, from what I've read, KSP2 will have an integrated loader.

So either we go with what P.D. and the development team will provide, or we go for a community approach. In the latter case, I think we should definitely simplify mod management. Starting with two different loaders doesn't strike me as the best way forward.

Finally, I don't know what limitations or opportunities one or the other brings to modding. I am also aware that there are other operating systems that need support.
However, could there be some consultation on the best way forward?

This is already being solved at the moment, with SpaceWarp transitoning to being fully just a BepInEx plugin that provides KSP-specific API wrappers and convenience stuff:

https://github.com/SpaceWarpDev/SpaceWarp/releases/tag/spacewarp-0.4.0-prerelease-1

This means that going forward all mods will be BepInEx mods with an optional dependency on SpaceWarp.

[Demcrew]

This is an amazing information!

Would it be possible to have a pinned message centralising all the information, such as for CKAN?

I'm just anticipating, since the interest would grow more and more as Mods start to spread.

 

[Motokid600]

 Y'know I gotta say after playing Valheim this is like seeing the black cat in The Matrix. Or maybe its the Spider Man meme..

Edited March 5 by Motokid600

[Dinkledash]

On 2/26/2023 at 10:21 AM, neocromicon said:

Can i use BepInEx and SpaceWarp simultaneously? I hope yes

There's a Bepin_Ex_Space_Warp_4.0 plugin

[Scarecrow71]

Is there a list of the KSP2 methods, functions, variables, etc., that we can call and use in a mod?  For example, say I wanted to write a mod that uses goofy foot (prograde is retrograde, up is down, etc.).  Is there a list of the functions I can reference?  Or would VS's Intellisense be able to show me those with the right dll references in the project?