Modding Tutorials/XML file structure

< Modding Tutorials

This page was originally created by Alistaire.

In this tutorial we will start learning the XML syntax, why the base game uses it and what everything about it does.

What you'll learn

You'll learn the default structure of def files:

<?xml version="1.0" encoding="utf-8"?>
<Defs>
	<Def Name="Parent" Abstract="True">
	</Def>

	<Def ParentName="Parent">
	</Def>

	<!-- more <Def>'s -->
</Defs>

.. Along with how inheritance using Name, ParentName and Abstract works.

Default Def structure

Standard defs

Find a Def .xml file in the Core folder, for example ThingDefs_Misc/Weapons_Guns.xml:

 Core/
   Defs/
     ThingDefs_Misc/
       Weapons_Guns.xml

../Mods/Core/Defs/ThingDefs_Misc/Weapons_Guns.xml

The first thing in this file is the following line:

<?xml version="1.0" encoding="utf-8"?>

Which tells us this .xml files uses UTF-8 encoding and XML version 1.0, which are the default values for these fields - some XML editors choose to hide this line on editing and then save it on top of the document without ever asking the user about it.

After that, the structure of the file consists of <Defs> and <Def> tags:

<Defs>
	<Def>
	</Def>

	<!-- more <Def>'s -->

	<Def>
	</Def>
</Defs>

Each <Def> contains something's def (or definition), which can be used to specify each and every modifiable property, e.g for a certain thing (thingDef).

Differences in defs

If you look through some .xml files, you'll find the code is inconsistent in the use of some defs;

Several Buildings_**.xml files use the <Buildings> tag instead of the <Defs> one. They then proceed to use <thingDef>'s inside the <Buildings> tag.
Other Buildings_**.xml files use <Defs> instead of <ThingDefs>, and some even use <GameData> instead of <ThingDefs>.

This implies that the name of the beginning and ending tags isn't important. Rimworld doesn't read their names, it just looks whether they exist.

This doesn't mean that <Def> tags are interchangeable. Using "<Def>" will break the game; you will have to specify what C# class will be loaded to parse its contents.

Full code

It is important that your file follows this structure to the point where mods won't work with multiple <Defs>, or a <Def> outside of <Defs>:

<?xml version="1.0" encoding="utf-8"?>
<Defs>
	<Def>
	</Def>

	<!-- more <Def>'s -->

	<Def>
	</Def>
</Defs>

Inheritance

Summary: In XML, inheritance is used to decrease redundancy. If something has a ParentName="YourParentName", it takes all contents from Name="YourParentName". In case this ParentName is incomplete this will crash the game, and you stop it from being loaded into the game with Abstract="True".

Basegun thingDef

The first thing in Weapons_Guns.xml is a <thingDef> with a Name and Abstract type:

<ThingDef Name="BaseGun" Abstract="True">

The Abstract type means that contents of this <thingDef> will not be loaded into the game, that after reading and processing the information in this tag it (the game) will finish reading the XML file (entire mod folder as of Alpha 13) and discard this tag and its contents, leaving alone (not discarding) anything that might have copied (taken, inherited) the contents of it. All of this is done with this tag:

<ThingDef Abstract="True">

So what that means is that all the contents of <ThingDef Name="BaseGun" Abstract="True"> can be used over and over in the various guns, but BaseGun itself does not exist in the game - it's an abstract idea!

The Name type means the contents of this <thingDef> can be inherited by (read: copied by) another <thingDef>. This way you can write everything you're going to repeat a lot throughout the file in a single location, such as the following:

<category>Item</category>

Which notifies that this <thingDef> is of the Item category, as opposed to those of the Building category. Because there's a lot of tags repeated throughout every thing, this greatly compacts the XML file.
The full BaseGun parent only has to be defined once in a file, and can then be inherited (copied) with:

<ThingDef ParentName="BaseGun">

<thingDef ParentName="Parent"> inherits all contents from <thingDef Name="Parent">. It is common practice to copy the vanilla BaseGun parent and paste it on top of a mod's Weapons_Guns.xml file.
Another parent is BaseBullet which holds every standard bullet's commonly repeated properties, such as the property that bullets don't use hitpoints:

<useHitPoints>False</useHitPoints>

The last <thingDef> on top of the file is one with the Name type BaseHumanGun and the ParentName type BaseGun. It inherits the contents of BaseGun and is inherited by everything with <thingDef ParentName="BaseHumanGun">:

<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">

A list representation of how inheritance works in Rimworld's XML might help you out, either early on or to collect your thoughts after reading the above.

1. Game launches
2. Game loads mods individually:
   1. Inheritance information is taken from each tag
   2. Anything with a PARENTNAME type inherits (read: copies) and applies all content from its associated NAME type
      • Anything that gets content is a child
      • Anything that sends it is a parent
      • It's possible to be both of these
   3. Content information (read: everything between the <thingDef>) is taken and applied for each tag
      • All interfering content from parents is now overwritten
   4. Now that all <Def>s know their contents, ABSTRACT type defs are discarded and therefore ignored by the game
   5. All <Def>s and their contents finish loading
3. Game finishes loading mods
   
   

Breakdown

Let's break down the inheritance chunks of the BaseGun code:

<thingDef Name="BaseGun" Abstract="True">
</thingDef>

<thingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
</thingDef>

<thingDef Name="BaseBullet" Abstract="True">
</thingDef>

<ThingDef Name="BaseGun" Abstract="True">
<thingDef>	The name of this tag, which is read by the game and processed into a correct definition based on this name. All tags in ../Mods/Core/Defs/ThingDefs/ use the <thingDef> tag.
Name="BaseGun"	The Name type of this tag. This tag is a parent with the Name value of "BaseGun".
Abstract="True"	The Abstract type of this tag is True. This makes it so that the contents of this tag aren't instantiated, which in practice means the contents of it can only be inherited by other tags and won't be loaded into the game because its only purpose is in inheritance, in being a parent. "Is the only use of this <thingDef> to be inherited from? Yes: add Abstract="True". No: don't."
<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
ParentName="BaseGun"	The ParentName type of this tag. This tag inherits from a parent with the Name value of "BaseGun".

Full code

After the addition of inheritance, our XML file structure looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Defs>
	<Def Name="Parent" Abstract="True">
	</Def>

	<Def ParentName="Parent">
	</Def>

	<!-- more <Def>'s -->
</Defs>

• <Defs> can have any name you want;
• <Def> has to have a specific name.

Next up

• Weapons_Guns.xml continues explanations on the BaseGun parent, the tags inside its <thingDef>'s and further information on modding in weaponry.