Getting started with writing Code for KSA

Unofficial project

There is currently no official way to add custom code to Kitten Space Agency. The tools used in this guide are developed by the community. They are not affiliated with or endorsed by the KSA developers.

Overview

This guide explains how to add custom code execution to Kitten Space Agency.

Prerequisites

To develop mods using visual studio you need the following prerequisites

• Any Visual Studio version with c# .NET 9 development tools installed.
• A github account
• A github access token with access to package registries

Step 1: Setting up the development environment

Currently the most popular way to create mods is by using StarMap.

Before starting this guide it is recommended to set up the example mod and running it to verify StarMap is working. You can find a guide here and an example mod here

THIS GUIDE USES STARMAP 0.2.x MAKE SURE YOU HAVE THE CORRECT VERSION

Creating the Visual Studio project

1. Create a new visual studio project by pressing Create a new project.

2. Filter for the C# language

3. Select Class Library

4. Click next

5. Enter FirstMod as the name of the project

6. Select a location

7. Press next

8. Select .NET version 9 (Standard Term Support)

9. Press create

Setting up StarMap

Now that we have a working Visual Studio project it is time to setup StarMap. For this step you will need the previously mentioned github access key so make sure you have that ready.

We will have to add a custom Package Source to nuget to be able to use StarMap

1. Right click the project

2. Select Manage NuGet Packages

3. Click the cogwheel

4. Under NuGet Package Manager Select Package Sources

5. Press Add
6. Under Name write StarMap
7. Under Source write https://nuget.pkg.github.com/StarMapLoader/index.json
8. Press Save

9. Close the options tab

10. Under Package Source Select StarMap

11. Open the Browse Tab
12. A dialog box will open
13. Under username Select Personal Access Token
14. Instead of using your github password under password enter your Personal Access token.

15. Press Ok

16. Select StarMap.API

17. Press Install
18. Complete the installation process
19. StarMap should be set up

Setting up Harmony

1. Under Package Source select nuget.org again
2. Go to the Browse tab
3. Search for harmony
4. Select Lib.Harmony
5. Press Install
6. Wait for the instal to finish

Step 2: Adding dependencies

When using StarMap to mod the game you will eventually need external resources from the game itself called assemblies or .dll files. For a basic mod you only need one dependency: KSA.dll. So this first-steps guide will do just that.

1. Right click on dependencies

2. Press Add Project Reference

3. Press Browse

4. Now go to the KSA install directory (default: C:\Program Files\Kitten Space Agency) and find KSA.dll, Select it and click add
5. Press OK

Step 3: Creating a Mod class

StarMap automatically loads the class with the same name as the .dll file and that has the [StarMapMod] attribute

Our first step will be creating this class. Our example will be using the name FirstMod for the mod.

Creating the class

Create a class under the namespace FirstMod with the name FirstMod. And let it inherit from IStarMapMod

using StarMap.API;

namespace FirstMod
{
    [StarMapMod]
    public class FirstMod
    {

    }
}

The api exposes a couple of attributes but for this simple hello world example we only need one: [StarMapImmediateLoad]. The function marked with this attribute will be run when the mod is loaded. The function this attribute is assigned to does need to take in Mod definingMod as a parameter.

The Mod class needs the KSA namespace (found in KSA.dll) so we will add using KSA on the top of the file.

using StarMap.API;
using KSA;

namespace FirstMod
{
    [StarMapMod]
    public class FirstMod
    {
        [StarMapImmediateLoad]
        public void Init(Mod definingMod)
        {

        }
    }
}

Lets make a simple hello world program now.

Just add a Console.WriteLine("Hello World!")

Inside FirstMod:

[StarMapImmediateLoad]
public void Init(Mod definingMod)
{   
    Console.WriteLine("Hello World!");
}

Step 4: Creating mod.toml

A mod should always have a mod.toml file so it can be identified by StarMap. Lets Create that file.

1. Create a new file in Visual Studio and call it mod.toml.

2. Edit the file and add this inside, name should always be the name of both the dll and the class that implements IStarMapMod.

   name = "FirstMod"
   

3. Now right click on mod.toml and select Properties.

4. Under properties there is a field called Copy To Output Directory set it to Copy always.

Step 5: Compiling

If you did all steps correctly simply right clicking the project and selecting Build should build the files.

The compiled files will now be in the following directory: projectdir\FirstMod\bin\Debug\net9.0. Now follow the installation guide to test your brand new mod. If you did all the steps correctly you should see Hello World! in the console output of StarMap.exe.