Getting started, the basics of writing a plug-in.

Diazo · December 20, 2016

The basics, getting started with writing plug-ins.

Welcome to a quickstart guide on how to start writing a code plug-in for Kerbal Space Program.

This is a quick guide intended as an overview on getting started and what hooks are available in KSP where you can attach your code. It is not intended as a step-by-step tutorial, rather it is intended to make you aware of your options so you can then investigate in more detail which options you wish to use.

IDE Setup
The hooks.
1. KSPAddon
2. ScenarioModule
3. VesselModule
4. PartModule
Common Methods
Common References
On-Screen GUI
Toolbar button
GameEvents System
ConfigNode overview
Save/Load Data

1) IDE Setup

Writing a code plug-in for KSP is done in C# so we need a program (IDE) to write code in that can produce the .dll file from that code that KSP will recognize.

Any program that can make .dll files will work, this document uses Microsoft Visual Studio for its examples.

Once the IDE program is installed, start a new project and make sure you set the “.Net Version 3.5”. If you do not the project will compile for the most recent version of .Net which is 4.5 and KSP will not handle it correctly and throw errors when it tries to load.

We then need to tell the IDE where to find the References to the KSP files. In your project, add a reference to UnityEngine.dll, UnityEngine.UI.dll, Assembly-Csharp.dll, Assembly-Csharp-firstpass.dll. These files are found in the “KSP_Install\KSP_x64_Data\Managed”.

Then at the top, add a line below “using System;” that says “using UnityEngine”. Our blank project is now ready to go and we can start coding.

To test, copy-paste the following code into your program:

using System;
using UnityEngine;

namespace HelloWorld
{
    [KSPAddon(KSPAddon.Startup.MainMenu, false)]
    public class Hello : MonoBehaviour
    {
        public void Update()
        {
            Debug.Log("Hello world! " + Time.realtimeSinceStartup);
        }
    }
}

then compile your .dll file and place it in the KSP_Install\GameData folder. It can be in a sub-folder, typically you will make a sub-folder for your mod in order for the players to keep things straight.

When you start KSP and reach the main menu, if everything is setup correctly, the code above will spam "Hello world!" to the console which is toggled on with Alt-F12. It will also append the time since the game was started so you can see the lines of text change.

2) Basic hooks

In order to actually do anything, we need to hook into KSP so that our code will run. There are 4 ways to do this, which one you use will depend on what purpose your code has. Note that using multiple methods for different pieces of code is a valid approach.

KSPAddon

The KSPAddon hook is used when you want to run some code that is attached to a specific scene. Use this when you code runs and affect the Flight scene, the Tracking Station scene, the Editor scene, and so on. KSP will automatically create an instance of a class tagged this way at the start of the scene and destroy it at the end of the scene. Note: There is no integrated save/loading of data in the KSPAddon hook, you must do that manually.

Use cases: Permanent changes to how the scene works, either the game-space itself or the UI. As there is no save/loading of data, the changes need to be the same every time.

KSPAddon(Scene,Dont_Destroy)

Scene: The Scene enumerator, in which scene does an instance of this class get loaded. This takes values from the KSPAddon.Startup enum and multiple values to start in multiple scenes can be selected.

Dont_Destroy: Don’t destroy the class when the scene ends. Highly recommended to leave false until you understand how Unity creates/destorys objects in and across different scenes. Is a boolean value.

[KSPAddon(KSPAddon.Startup.Flight, false)]
public class MyKSPAddon : MonoBehavior
{
    //your code here.
}

This will tell KSP to spawn an instance of MyKSPAddon when the Flight scene starts and destroy it when the Flight scene ends. It is high recommended that the class inherit from MonoBehavior (or other class that inherits from MonoBehavior) so that the Common Methods are available to you.

ScenarioModule

The Scenario Module is used for when a mod needs to affect a large part of the game and provides the ability to Save/Load data. One caveat is that different scenes have different objects so make sure to check what scene you are in before referencing objects that exist in multiple scenes.

ScenarioModule(ScenarioCreatingOptions, Gamescene)

ScenarioCreationOptions: What type of games do we add this to? Take from the ScenarioCreateOptions enum.

GameScene: The Scene enumerator, in which scene does an instance of this class get loaded? Takes from the GameScenes enum.

[KSPScenario(ScenarioCreationOptions.AddToNewCareerGames | ScenarioCreationOptions.AddToExistingCareerGames, GameScenes.SPACECENTER)]
class MyScenario : ScenarioModule
{
	//your code here
}

This will add you ScenarioModule to all games in career mode and create an instance of this class in the Space Center scene. Note that it must inherit ScenarioModule.

VesselModule

An single instance of a VesselModule is automatically added to every vessel that exists (can be switched to in the tracking station). Note that VesselModule's will still execute for unloaded vessels which PartModules will not.

public class MyVesselModule : VesselModule
{
    //your code here.
}

A VesselModule must inherit from VesselModule and no Attribute is required on the preceding line. Note that while a VesselModule does save/load data it does not have any provision for transfer of data between two VesselModules, such as when two vessels dock and combine, or an undock happens and a single vessel becomes two.

PartModule

A PartModule is a class that gets attached to a part. This is done through the use of ModuleManager (another mod) and scripts that control which parts your PartModule gets attached to. These scripts are very flexible and you can attach only to your desired parts and attach multiple instance of your PartModule if you desire. Module Manager download, and instructions on how to use, can be found here.

public class MyPartModule : PartModule
{
    //your code here.
}

A PartModule must inherit from PartModule.

3) Common Methods

There are several common methods inside these 4 hooks that KSP will automatically execute for you. (This section assumes KSPAddon inherits from MonoBehavior.)

public void Awake() 
{
}