Creating your first C# Mod

This is NOT a tutorial on C#

Setup

It is recommended to use Visual Studio (Windows & Mac, free) or Rider (Windows, Mac & Linux, paid)

• Visual Studio at https://www.visualstudio.com/downloads
• Rider at https://www.jetbrains.com/rider

Creating a new Project

Visual Studio

STUB install guide here

Rider

Go to New Solution -> Select Class Library in the .Net/.Net Core category -> Make sure you target netstandard 2.0/2.1

Project Setup

Add Assembly-CSharp.dll inside colonyserver_Data as a dependency, make sure to disable any copying functionality to the dependency as you should not redistribute the game's assembly.

Currently, only server-sided mods work

Your first script

An example of your initial script.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

// The namespace can be any! It's recommended to format it as YourName.ModName
namespace MyMods.ThisMod
{
    // This attribute declares this `Main` class is a mod and will be loaded when enabled
    [ModLoader.ModManager]
    public static class Main
    {
        // Your code here...
    }
}

Now let's add some basic functionality using Callbacks! Simply add this inside the Main class and you can get the path where the DLL is located in.

    // Location of MOD .DLL file at runtime.
    public static string MODPATH;

    // ModLoader.ModCallback(Callback Type, This mod's ID)
    [ModLoader.ModCallback(ModLoader.EModCallbackType.OnAssemblyLoaded, "MyMods.ThisMod.OnAssemblyLoaded")]
    public static void OnAssemblyLoaded(string path)
    {
        MODPATH = System.IO.Path.GetDirectoryName(path).Replace("\\", "/");
    }

Callbacks

Callbacks are a key feature if you want to hook or modify game data. You can use dnspy or your IDE's builtin decompiler to check which callbacks are available in ModLoader.EModCallbackType. You can also check in the callback .md document!

You need to use the ModLoader.ModCallback(...) attribute to mark your function as a callback

You can order when your callback by using the attributes

• ModLoader.ModCallbackDependsOn(...) Waits for the targeted callback to finish
• ModLoader.ModCallbackProvidesFor(...) Runs before the targeted callback run.