Modding Tutorials/Def classes

< Modding Tutorials

This tutorial provides you with an introduction to Def Classes in C#. It shows what effects each part of the C# code has on the XML format.

Requirements

• This tutorial requires you to know how to write custom code.
• Decompiling source code is required.
  
  

Modifying defs

There's a few ways to modify existing def formats. We'll go over writing a custom defClass, custom comp and other ways of integrating XML tags into C# for example through the use of weaponTags or apparelTags.

Vanilla defClasses

This chapter helps you develop a broad understanding of the def classes. First we take a look at tags inside <thingDef>, then we take a look at tags inside those tags and finally we take a look at <li> items.

Tags

The structure of a base game defClass might look like this:

using RimWorld;
using System;
using UnityEngine;

namespace SomeNameSpace
{
	public class SomeDef : Def
	{
		public SomeType someTagName;
		public SomeOtherType someOtherTagName;

		public SomeType someGetClass
		{
			get
			{
				return (SomeType)this.someOtherTagName;
			}
		}
	}
}

A few notes could be made about this code.

• Without the using part, you'd have to call for Namespace.Class.Method() instead of Class.Method() or ((Class)partOfClass).Method(),

  using ...;	/* this tells the compiler which namespaces to look for when searching for class and method calls. */

  
  
• The : is inheritance and means you can access all methods in the parent and you can call back to for example the Tick() method using base.Tick(),

  public class SomeDef : Def	/* inherits "everything" from Def, !! except for privates !! */

  
  
• Everything of the following format is an XML tag:

  public SomeType someTagName	/* shows up as <ThingDef><someTagName>SomeType value</someTagName></ThingDef> */

  
  
• Besides these tags there's also script-only methods in the code:

  public SomeType someGetClass	/* this is only used in C#. XML doesn't change anything about this */

  
  
• Specifically get methods are only there for easily accessing or calculating certain values:

  return ...;	/* example: "public bool IsApparel()" returns "this.apparel != null". This could be checked easily but Thing.IsApparel() is more readable sometimes */

  
  

In practice one could find the following code:

using RimWorld;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using UnityEngine;

namespace Verse
{
	public class ThingDef : BuildableDef	/* BuildableDef inherits from Def */
	{
		public bool alwaysHaulable;

		public bool designateHaulable;

		public StuffProperties stuffProps;	/* the StuffProperties class defines what this might look like in XML */

		public bool IsStuff
		{
			get
			{
				return this.stuffProps != null;	/* with some types you can check whether they're defined by checking if they're not equal to null */
			}
		}

		public bool EverHaulable
		{
			get
			{
				return this.alwaysHaulable || this.designateHaulable;	/* "return A || B" will return true if either A or B is true, and false if both are false. */
			}
		}
	}
}

<?xml version="1.0" encoding="utf-8"?>
<ThingDefs>
	<thingDef>
		<alwaysHaulable>true</alwaysHaulable>
		<stuffProps>
			<!-- whatever you'd find in StuffProperties -->
		</stuffProps>
	</thingDef>
</ThingDefs>

• Note: these are snippets of Verse.ThingDef. To find the full source please decompile the source code yourself.
  
  

Subtags

To explain how subtags work we'll take a look at (parts of) StuffProperties. The contents of the StuffProperties class, formally called Verse.StuffProperties, are very similar to the ThingDef class. The structure is mostly the same.
In case you're wondering why we didn't have to add "using Verse;" to access Verse.StuffProperties, "namespace Verse {}" basically includes a using statement.

using RimWorld;
using System;
using System.Collections.Generic;
using UnityEngine;

namespace Verse
{
	public class StuffProperties
	{
		public bool smeltable;

		public StuffAppearance appearance;

		public SoundDef soundImpactStuff;

		public List<StatModifier> statOffsets;

		public List<StuffCategoryDef> categories = new List<StuffCategoryDef>();
	}
}

• Note: These are snippets of Verse.StuffProperties. To find the full source please decompile the source code yourself.
  
  

Because SomeDef defines which subtags it has you have to modify Verse.SomeDef to alter which subtags it has (this includes modified versions of existing subtags, you have to modify SomeDef at some point).
This is one of the reasons you might be better off writing a custom comp. These can be added to an XML overwrite or injected through C#.

Lists

Some tags include a list (it contains <li> subtags). If you look at the subtags of StuffProperties you can see two List<SomeType> elements. If you look at the XML you can see a clear distinction between the two:

<?xml version="1.0" encoding="utf-8"?>
<ThingDefs>
	<thingDef>
		<stuffProps>
			<categories>
				<li>Metallic</li>	/* Metallic is a defName from a StuffCategoryDef */
			</categories>
			<statOffsets>
				<Beauty>6</Beauty>	/* Beauty is a defName from a StatDef, but the list's type is StatModifier */
			</statOffsets>
		</stuffProps>
	</thingDef>
</ThingDefs>

A clear difference between the two is that one of them defines a list and the other one doesn't. If you look at RimWorld.StatModifier you can find another cause:

using System;
using System.Xml;
using Verse;

namespace RimWorld
{
	public class StatModifier
	{
		public StatDef stat;

		public float value;

		public void LoadDataFromXmlCustom(XmlNode xmlRoot)
		{
			CrossRefLoader.RegisterObjectWantsCrossRef(this, "stat", xmlRoot.Name);
			this.value = (float)ParseHelper.FromString(xmlRoot.FirstChild.Value, typeof(float));
		}
	}
}

• Note: These are snippets of RimWorld.StatModifier. To find the full source please decompile the source code yourself.
  
  

Because of this code the two act completely differently. One is a list with integer keys and StuffCategoryDef values, the other is a list with StatDef keys and float values.

See also

• XML Def Compatibility explains compatibility from the XML side of things.
• Def Class Compatibility explains compatibility from the C# side of things.