Modding Tutorials/Writing custom code

< Modding Tutorials

This page was originally created by TheTynan. Other contributors can be found on the Credits page.

This tutorial gives you a broad idea how to work on a C# solution.

While it is possible to create many mods by modifying or creating XML, writing custom C# code, either as stand-alone classes or as Harmony patches, allows changing almost anything in the game.

Requirements

• This tutorial requires you to have set up a solution.
  
  

Creating a class

Sharpdevelop

When you start your software you'll see a Projects file explorer to the left, a Properties explorer to the right and currently opened files in the middle.

• With your solution open, create a new class inside your Projects explorer;
  1. If you don't have your solution open you can do so by clicking File -> Open -> Project/Solution.. or by choosing a recent project on the Start page in the middle;
  2. If it's not expanded, click the + next to "Solution MySolutionName". Right-click MyProjectName (this could be the same as MySolutionName or different, depending on how you set up the solution);
  3. Select Add -> New Item.. -> Categories: C# -> Templates: Class -> File Name: MyClassName.cs,

Template

Let's go over the template:

/*
 * Created by SharpDevelop.
 * User: You
 * Date: 01-01-1970
 * Time: 00:00
 * 
 * To change this template use Tools | Options | Coding | Edit Standard Headers.
 */
using System;

namespace MyNameSpace
{
	/// <summary>
	/// Description of MyClassName.
	/// </summary>
	public class MyClassName
	{
		public MyClassName()
		{
		}
	}
}

Using

The first thing you notice is using System; which indicates this class can call anything from the namespace System without calling it like System.Class.SomeDataType but rather SomeDataType. This is very useful because we don't have to worry about such calls anymore (for now).

The next section shows which namespaces you could put in using.

Namespace

Next up is the namespace MyNameSpace part - in principle everything inside of a namespace knows everything else inside of that namespace. If you were to make a folder inside of your project (MyProjectName not Solution MySolutionName), any classes inside of that folder would have the namespace MyNameSpace.MyFolderName. That's a different namespace and unless you tell other classes that it exists (using MyNameSpace.MyFolderName;) they won't accept calls to parts of that namespace without that namespace as a prefix.

Anything inside of MyNameSpace.MyFolderName does however know of everything inside MyNameSpace, just nothing about other subfolders of MyNameSpace.

By default your project knows nothing. Adding DLL references to the References folder (as done in the previous tutorial) allows you to reference them with using:

namespace MyNameSpace {}		/* Assuming MyNameSpace is your ROOT NAMESPACE (MyProjectName ->
					Properties -> Application -> Root namespace), this will compile. */

namespace MyNameSpace.MyFolderName {}	/* Assuming this class is inside of the folder MyFolderName inside of
					MyProjectName, this will compile. Other classes outside of the folder
					will have to reference this, this class will have to reference classes
					in different subfolders (but not the ones in the root folder). */

namespace RimWorld {}			/* Don't do this. It will compile if RimWorld is your root namespace
					but it's bad practice. */

namespace System {}			/* No, just no. */

You can set your project's namespace by right-clicking MyProjectName -> Properties -> Application -> Root namespace. Please take some time to make it unique so no compatibility issues will arise with other mods, for your and everyone else's sanity.

Some very useful namespaces in general are the following:

Namespace	What does it do?
System.Collections.Generic	Makes it so you can use part of the IEnumerable interface, which is used for datatypes like List<>.
System.Linq	Allows for cool operations on the IEnumerable interface such as .Where() which accepts lambda operations (oh my!).
System.Text.RegularExpressions	Introduces Regular Expressions (RegEx) to C# which allows for intricate operations on strings.
System.Collections	Holds other parts of the IEnumerable interface you will require when inheriting from that class.
System.Text	Contains the StringBuilder which accepts a list of strings and returns them in a specific way.

And the namespaces for RimWorld in particular are these:

Namespace	What does it do?
RimWorld	Many classes can be found in this namespace.
RimWorld.Planet	Everything (almost everything) having to do with the planet savefile is in here.
RimWorld.SquadAI	Holds the squad AI, clearly. You'll know it when you need this.
Verse	Sometimes more complex classes are found here.
Verse.AI	You might never have to touch this either.
Verse.Grammar	Contains functionality for the Languages folder and other things having to do with text operations such as the art flavour text generator.
Verse.Noise	Something something you'll never need this.
Verse.Sound	Much like Verse.Noise except it's required to play sounds directly with your code.
Verse.Steam	Steam integration by Tynan - it's not active so you won't need it.
UnityEngine	Contains many more methods you most likely won't need.

The difference between RimWorld and Verse is not very clear and you might as well add both using statements whenever you want.
If you want to use the exact functionality of a base game class you're best off copying all its using statements, its namespace and the namespace of its parent.

Summary

This summary is part of the template but it's not required. It can help other people understand your code better when you provide the source but besides that you really don't need it.

Class and Constructor

This is your class definition. To access anything inside of a public class you will need a reference to an instance of that class:

MyClassNamefoo = new MyClassName();

The brackets at new MyClassName() indicate you're creating this instance without parameters which is possible because your class contains a constructor (anything inside of class MyClassName which has parameters and isn't a method, often abbreviated .ctor) which accepts a call without parameters:

public class MyClassName
{
	public MyClassName()	/* No parameters */
	{
	}

	public MyClassName(string foo, int bar)	/* Required parameters of datatypes string and int */
	{
	}

	public MyClassName(string foo = "none supplied", int bar = 42)	/* Default parameters " " " */
	{
	}
}

The last implementation of the constructor (MyNameSpace.MyClassName.MyClassName inside of MyNameSpace.MyClassName) is capable of accepting zero to two parameters while the second implementation of the constructor will only accept calls with exactly two parameters.

Writing code

1. Decompile source code to take a look at the game's existing code;
   1. If you get stuck on anything, any modding questions can be asked on the subforum,
2. Compile your class into a .dll;
   1. Most IDE's, integrated development environments, have a button that says "Compile" or "Build" - there is usually a hotkey (F5, F8, etc). Compiling is entirely driven by the software, you only have to supply a location for it to compile to - as explained in Setting up a solution.
   2. Make sure your project's output type is "class library";
   3. Note: by default, Visual Studio will compile all the references of the project as well, so you’ll get a copy of UnityEngine.dll and Assembly-CSharp.dll and some others. Just take MyModName.dll and place it in the MyModName/Assemblies folder. If you have set up a solution according to the tutorial you don't have this problem,
3. Reference the classes in your .dll from the xml data in the MyModName/Defs folder;
   1. Example: Create a new ThingDef with a <thingClass> that points to a class in your .dll,
4. The game should load your class now;
   
   

See also

• Distribution details how to release your mod.
• Assembly modding example contains a small modding example.