Editing Modding Tutorials/XML file structure

=What you'll learn=

You'll learn the default structure of def files:<br/>

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

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

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

.. Along with how inheritance using Name, ParentName and Abstract works.<br/><br/>

=Default Def structure=
===Standard defs===

Find a Def .xml file in the Core folder, for example thingDefs/Weapons_Guns.xml:<br/>

  Core/
    Defs/
      ThingDefs/
        Weapons_Guns.xml

<source lang="xml">../Mods/Core/Defs/ThingDefs/Weapons_Guns.xml</source><br/>

The first thing in this file is the following line:<br/>
<source lang="xml"><?xml version="1.0" encoding="utf-8"?></source><br/>

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.<br/>

After that, the structure of the file consists of '''<Defs>''' and '''<Def>''' tags:<br/>
<source lang="xml"><Defs>
	<Def>
	</Def>

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

	<Def>
	</Def>
</Defs></source><br/>

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).<br/>

===Differences in defs===

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

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

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.<br/><br/>

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.<br/><br/>

===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>:'''<br/>
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<Defs>
	<Def>
	</Def>

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

	<Def>
	</Def>
</Defs></source><br/>

=Inheritance=
===Basegun thingDef===

The first thing in ''Weapons_Guns.xml'' is a '''<thingDef>''' with a Name and Abstract ''type'':<br/>
<source lang="xml"><ThingDef Name="BaseGun" Abstract="True"></source><br/>

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:<br/>
<source lang="xml"><category>Item</category></source><br/>

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.<br/>
The full BaseGun parent only has to be defined once in a file, and can then be inherited (copied) with:<br/>
<source lang="xml"><ThingDef ParentName="BaseGun"></source><br/><br/>

'''<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.<br/>
Another parent is BaseBullet which holds every standard bullet's commonly repeated properties, such as the property that bullets don't use hitpoints:<br/>
<source lang="xml"><useHitPoints>False</useHitPoints></source><br/>

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">''':<br/>
<source lang="xml"><ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True"></source><br/><br/>

===Breakdown===

Let's break down the inheritance chunks of the BaseGun code:<br/>
<source lang="xml"><thingDef Name="BaseGun" Abstract="True">
</thingDef>

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

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

{| class="wikitable"
!colspan="2"|<ThingDef Name="BaseGun" Abstract="True">
|-
| &lt;thingDef&gt; || The name of this ''tag'', which is read by the game and processed into a correct definition based on this name.<br/>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 [https://en.wikipedia.org/wiki/Abstract_type Abstract type] of this tag is True.<br/>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.<br/><br/>"Is the only use of this '''<thingDef>''' to be inherited from? Yes: add Abstract="True". No: don't."
|-
!colspan="2"|<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".
|}<br/>

===Full code===

After the addition of inheritance, our XML file structure looks like this:<br/>

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

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

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

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

=Next up=

* [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml]] continues explanations on the BaseGun parent, the tags inside its '''<thingDef>''''s and further information on modding in weaponry.

[[Category:Modding tutorials]]