Editing Modding Tutorials/XML file structure

Jump to navigation Jump to search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
−
{{BackToTutorials}}
 
−
<br/>
 
−
 
−
In this tutorial we will start learning the XML syntax, why the base game uses it and what everything about it does.<br/><br/>
 
−
 
 
=What you'll learn=
 
=What you'll learn=
  
Line 24: Line 19:
 
===Standard defs===
 
===Standard defs===
  
−
Find a Def .xml file in the Core folder, for example ThingDefs_Misc/Weapons_Guns.xml:<br/>
+
Find a Def .xml file in the Core folder, for example thingDefs/Weapons_Guns.xml:<br/>
  
 
   Core/
 
   Core/
 
     Defs/
 
     Defs/
−
       ThingDefs_Misc/
+
       ThingDefs/
 
         Weapons_Guns.xml
 
         Weapons_Guns.xml
  
−
<source lang="xml">../Mods/Core/Defs/ThingDefs_Misc/Weapons_Guns.xml</source><br/>
+
<source lang="xml">../Mods/Core/Defs/ThingDefs/Weapons_Guns.xml</source><br/>
  
 
The first thing in this file is the following line:<br/>
 
The first thing in this file is the following line:<br/>
Line 49: Line 44:
 
</Defs></source><br/>
 
</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). The rootnode of every ''def'' in the game is '''<Defs>''', followed by the exact type of ''def'' (e.g. ThingDef, RecipeDef, BiomeDef, etc).<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===
 
===Full code===
Line 64: Line 70:
 
</Def>
 
</Def>
 
</Defs></source><br/>
 
</Defs></source><br/>
−
 
−
===Syntax and Keywords===
 
−
 
−
You have surely noticed that some of the words in the XML files seem to be used repeatedly. Take note of the words '''Abstract''', '''Name''', and '''Class'''. These words are called keywords and they make up part of the languages syntax. A word that is given the role of keyword implies that it has an intended purpose and it's use is reserved only as a keyword. For this reason, there are some rules you should be aware of as the breaking of these rules is a common cause for bugs and errors when starting out.<br/>
 
−
 
−
When you write a keyword, it should be written exactly the same each time it's used. A common mistake is to unintentionally use a different casing. '''abstract''' is NOT the same as '''Abstract''' when it comes to the '''Abstract''' keyword and making that mistake will cause issues.<br/>
 
−
 
−
In general, you should avoid using a keyword as a property when editing or creating a new '''<Def>'''. It's almost certain that doing so will lead to problems so you're better off avoiding using a keyword outside of it's intended purpose as a keyword.<br/>
 
  
 
=Inheritance=
 
=Inheritance=
 +
===Basegun thingDef===
  
−
''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".<br/><br/>
+
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/>
  
−
'''Note that after update A15, abstracts have been directly inheritable from the core and from other mods. Redefining the core abstracts is common cause for mod compatibility issues, because any mod loaded after the abstract has been redefined will use the modified version instead of the core. Therefore, when defining abstracts for a mod, it's advisable to try to avoid overwriting the core abstracts and to instead use unique names that are unlikely to be accidentally used by other mods.'''
+
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 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:<br/>
 +
<source lang="xml"><ThingDef Abstract="True"><br/>
  
−
===Basegun ThingDef===
+
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/>
−
 
 
−
The first thing in ''ThingDefs_Misc\Weapons\BaseWeapons.xml'' is a '''<ThingDef>''' with a Name and Abstract ''type'':<br/>
 
−
<source lang="xml"><ThingDef Abstract="True" Name="BaseWeapon"></source><br/>
 
−
 
 
−
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 files 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:<br/>
 
−
<source lang="xml"><ThingDef Abstract="True"></source><br/>
 
−
 
 
−
So what that means is that all the ''contents'' of <code lang="xml"><ThingDef Abstract="True" Name="BaseWeapon"></code> can be used over and over in the various guns, but '''BaseWeapon''' itself does not exist in the game - it's an abstract idea!<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/>
 
<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/>
+
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 BaseWeapon parent only has to be defined once in a file, and can then be inherited (copied) with:<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="BaseWeapon"></source><br/><br/>
+
<source lang="xml"><ThingDef ParentName="BaseGun"></source><br/><br/>
  
−
'''<ThingDef ParentName="Parent">''' inherits all contents from '''<ThingDef Name="Parent">'''. <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/>
 
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/>
 
<source lang="xml"><useHitPoints>False</useHitPoints></source><br/>
  
−
The next '''<ThingDef>''' in the file is one with the Name type ''BaseGun'' and the ParentName type ''BaseWeapon''. It inherits the contents of BaseWeapon and is inherited by everything with '''<ThingDef ParentName="BaseGun">''':<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="BaseGun" Abstract="True" ParentName="BaseWeapon"></source><br/><br/>
+
<source lang="xml"><ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True"></source><br/><br/>
−
 
 
−
It might help to think of each ''<ThingDef Name ="...">'' as a sort of template. BaseWeapon contains the basic information which is true for all weapons: they can be hauled, equipped, selected. BaseGun contains the information which is true for all guns: they're part of the WeaponsRanged category, they can be smelted, they can have art. BaseMakeableGun in turn contains info to make the gun.
 
  
 
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.<br/><br/>
 
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.<br/><br/>
  
 
# Game launches
 
# Game launches
−
# Game loads mods individually:
+
# Game loads XML files:
 
## Inheritance information is taken from each tag
 
## Inheritance information is taken from each tag
 
## Anything with a PARENTNAME type inherits (read: copies) and applies all content from its associated NAME type
 
## Anything with a PARENTNAME type inherits (read: copies) and applies all content from its associated NAME type
Line 114: Line 103:
 
##* Anything that sends it is a parent
 
##* Anything that sends it is a parent
 
##* It's possible to be both of these
 
##* It's possible to be both of these
−
## Content information (read: everything between the <ThingDef>) is taken and applied for each tag
+
## Content information (read: everything between the <thingDef>) is taken and applied for each tag
 
##* All interfering content from parents is now overwritten
 
##* All interfering content from parents is now overwritten
 
## Now that all <Def>s know their contents, ABSTRACT type defs are discarded and therefore ignored by the game
 
## Now that all <Def>s know their contents, ABSTRACT type defs are discarded and therefore ignored by the game
−
## All <Def>s and their contents finish loading
+
## All <Def>s and their contents finish loading
−
# Game finishes loading mods<br/><br/>
+
# Game finishes loading XML files<br/><br/>
  
 
===Breakdown===
 
===Breakdown===
−
{| class="wikitable"
 
−
|-
 
−
! What you write !! What the game sees
 
−
|-
 
−
| <source lang="xml"><ThingDef Name="BaseGun" Abstract="True">
 
−
    <exampleTagOne>true</exampleTagOne>
 
−
</ThingDef>
 
  
−
<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
+
Let's break down the inheritance chunks of the BaseGun code:<br/>
−
    <someOtherTag>12</someOtherTag>
+
<source lang="xml"><thingDef Name="BaseGun" Abstract="True">
−
</ThingDef>
+
</thingDef>
−
</source>|| <source lang="xml"><ThingDef Name="BaseGun" Abstract="True">
 
−
    <exampleTagOne>true</exampleTagOne>
 
−
</ThingDef>
 
  
−
<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
+
<thingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
−
    <exampleTagOne>true</exampleTagOne>
+
</thingDef>
−
    <someOtherTag>12</someOtherTag>
 
−
</ThingDef>
 
−
</source>
 
−
|}
 
  
 +
<thingDef Name="BaseBullet" Abstract="True">
 +
</thingDef></source>
  
 
{| class="wikitable"
 
{| class="wikitable"
 
!colspan="2"|<ThingDef Name="BaseGun" Abstract="True">
 
!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.
+
| &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".
 
| 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."
+
| 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">
 
!colspan="2"|<ThingDef Name="BaseHumanGun" ParentName="BaseGun" Abstract="True">
Line 173: Line 150:
 
</Defs></source><br/>
 
</Defs></source><br/>
  
−
* '''<Defs>''' is the rootnode and this uniformity is enforced.
+
* '''<Defs>''' can have any name you want;
−
* '''<Def>''' has to have a specific name, matching a Type in C#.
+
* '''<Def>''' has to have a specific name.
−
 
 
−
===Stopping inheritance===
 
−
There are cases where you don't want your child to use the values specified in the parent. You can tell your child not to inherit the content from its parent's tag by specifying ''Inherit="False"'' in the child's tag, like this example taken from the SniperRifle:
 
−
<source lang="xml">
 
−
<weaponTags Inherit="False">
 
−
  <li>SniperRifle</li>
 
−
</weaponTags></source>
 
−
The above example would only have ''SniperRifle'' as a weaponTag, none of the parent's weaponTags. This is particularly useful for lists, because lists add to the parent whereas other tags overwrite.
 
−
 
 
−
The advantage of this is that you can leave the parent intact and still inherit from it, but let the child select which properties to inherit.
 
−
 
 
−
====Example====
 
−
<source lang ="xml">
 
−
<ThingDef Name="ThingOne" Abstract="True">
 
−
  <comps>
 
−
    <li Class = "CompOne">
 
−
      <valueA>1</valueA>
 
−
    </li>
 
−
  </comps>
 
−
</ThingDef>
 
−
 
 
−
<ThingDef ParentName="ThingOne">
 
−
  <comps Inherit= "False"> <!-- This here means "don't use the comps from the parent -->
 
−
    <li Class = "CompOne"> <!-- since we just removed all comps from the parent, we gotta re-add them -->
 
−
      <valueA>2</valueA>  <!-- but we can use our own values! -->
 
−
    </li>
 
−
  </comps>
 
−
</ThingDef>
 
−
</source>
 
  
 
=Next up=
 
=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.
+
* [[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]]
 
[[Category:Modding tutorials]]

Please note that all contributions to RimWorld Wiki are considered to be released under the CC BY-SA 3.0 (see RimWorld Wiki:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

Cancel Editing help (opens in new window)

Template used on this page:

Retrieved from "https://rimworldwiki.com/wiki/Modding_Tutorials/XML_file_structure"