Difference between revisions of "Modding Tutorials/ThingDef"

From RimWorld Wiki
Jump to navigation Jump to search
(Added global attributes)
 
(25 intermediate revisions by 14 users not shown)
Line 1: Line 1:
'''ThingDef''' is a def type for making entities, such as buildings and pawns (NPCs).
+
{{BackToTutorials}}
  
 +
'''ThingDef''' is one of the many [[Modding_Tutorials/XML_Defs|Defs]] used in RimWorld. Almost every "tangible" (and some intangible) things you see in RimWorld are backed by a ThingDef.
  
==Buildings==
+
=What you'll learn=
Buildings are static entities. They usually require construction and perform a special function.
+
You will learn the '''structure''' of ThingDef, how to use a decompiler to learn what a tag does, and along the way you'll learn the meaning of a few select tags.
  
===Attributes===
+
=What you will '''not''' learn=
 +
The goal of this tutorial is not to tell you what each XML tag does. ThingDef alone has 200+ valid XML tags, not counting hundreds of subtags. There are simply too many to document, and a lot of them are self-explanatory.
  
 +
* If you want a list of all XML tags (not just ThingDef) you'll want [https://ludeon.com/forums/index.php?topic=21440.0 milon's autodocumentation project]. Note that it only includes tags ''in use by'' RimWorld, not necessarily ''all tags available''.
 +
* If you want to see what an earnest attempt at documenting the XML looks like, you'll want the [https://github.com/RimWorldMod/RimworldModdingFiles XML Documentation Database]. Last updated for A15.
 +
* If you want to see what a documentation attempt on this wiki looks like, [https://rimworldwiki.com/index.php?title=Modding_Tutorials/ThingDef&oldid=62403 view the history of this article] and see that was last up to date in Alpha 9.
  
==Pawns==
+
Fact of the matter is this: there is no documentation that will tell you the meaning and usage of every tag. There probably never will. If there is, it will be out-of-date soon enough.
Pawns are NPCs.
 
  
==Items==
+
=Requirements=
Items are anything that can be hauled, such as weapons, debris, or resources.
+
* A [[Modding Tutorials/Decompiling_source_code|decompiler]] is advised.
  
==Plants==
+
[[File:ThingDef.PNG|300px|thumb|right|ILSpy v4.0 showing the decompiled ThingDef class, with the analyzer expanded on the smallVolume field. To the left a few of available fields are visible.]]
Plants grow in growing areas, in the landscape, in a hydroponics table, or in a plant pot.
 
  
===Attributes===
+
=Introduction=
 +
There are hundreds of XML tags. Some of them are rudimentary tags required for basic operation. Most of them are self-explanatory, and you can always use the Find In Files functionality of [[Modding Tutorials/Recommended software|your favourite text editor]] to see what it is used by, and what values already exist. Sometimes, this does not suffice. This tutorial is for those times.
  
==Filth==
+
=An example=
Filth is just an image that is overlaid above the floor. It contributes to the "ugly environment" thought in pawns.
+
Let's take a look at the ''intricate'' tag. This tag serves as an example because unlike "DeteriorationRate" or "stackLimit" it's not immediately obvious what it does. This tutorial assumed you just used the Find In Files functionality of [[Modding Tutorials/Recommended software|your favourite text editor]] and learned just one thing: Only the [[Component]] and [[Advanced component]] have this tag, and it's set to true.
  
==Global attributes==
+
<source lang = "xml">
These attributes can be used in all ThingDef types.
+
<Defs>
 +
    <ThingDef>
 +
        <defName>ComponentIndustrial</defName>
 +
        <intricate>true</intricate>
 +
    </ThingDef>
 +
</Defs>
 +
</source>
  
{| class="wikitable sortable"
+
[[File:Intricate.PNG|300px|thumb|right|The search result for intricate.]]
! scope="col"| Attribute
+
 
! scope="col"|Function
+
Take your favourite [[Modding Tutorials/Decompiling source code|decompiler]] and search for ''intricate''. Now right-click the result and hit ''analyze''. The analyzer in my decompiler shows it's read in three places, and assigned nowhere. The decompiler doesn't show any assigning of this value because it's set in the XML. We can see it's read by ''PlayerItemAccessibilityUtility.CacheAccessibleThings'' and twice by ''Thing.SmeltProducts''. Taking a closer look at the ''Thing+<SmeltProducts>c__Iterator4.MoveNext'', this is an inner method for the enumerator<ref>The what? An enumerable is a fancy type of list and the MoveNext means "go to the next item on the list". Apologies to those who have a background in computer science.</ref>. That in itself doesn't do much, so let's take a look at ''SmeltProducts'' itself.
! scope="col"| Available options
+
 
|----
+
[[File:SmeltProducts.PNG|300px|thumb|right|The view for SmeltProducts.]]
! scope="row"| category
+
 
|Designates a category to be used internally.
+
We can see here that ''SmeltProducts'' in turn is used for some economy related DebugOutput, and by MakeRecipeProducts. We can dive further down the rabbithole, but by now it is a reasonable assumption that ''SmeltProducts'' is used to determine what products you get from smelting. But what's the ''intricate'' tag? Well, ''SmeltProducts'' loops over the ingredients in the costList (i.e. the required ingredients to make an item) and checks if it's ''intricate''. If it's not intricate, it will return the ingredient.
|Building, Pawn, Plant, Item, Filth
+
 
|----
+
In other words, the ''intricate'' tag means that ThingDef won't survive a trip to the smelter. You don't get your components back if you smelt down an [[Assault rifle]].
! scope="row"| eType
+
 
|Provides a more specific description of an object. This may be equal to the category's name.
+
'''You can find the meaning of every XML tag this way.''' Some might be easier than others, but you can find (or make an educated guess) to the meaning of every XML tag.
|Varies per category
+
 
|----
+
=Adding more tags=
! scope="row"| thingClass
+
This requires C#. The current recommended way for maximum compatibility is by using a [[Modding_Tutorials/DefModExtension|DefModExtension]].
|Provides an attachment to an internal class in the code.
+
 
|Varies per category
+
=See also=
|----
+
* [https://ludeon.com/forums/index.php?topic=21440.0 milon's autodocumentation project]. Note that it only includes tags ''in use by'' RimWorld, not necessarily ''all tags available''
! scope="row"| selectable
+
* [https://github.com/RimWorldMod/RimworldModdingFiles XML Documentation Database]. Last updated for A15.
|Specifies whether or not the item can be selected in the atlas.
 
|true, false
 
|----
 
! scope="row"| useStandardHealth
 
|Determines whether or not health will be calculated normally. (?)
 
|true, false
 
|----
 
! scope="row"| label
 
|User-friendly name of a Thing
 
|String
 
|----
 
! scope="row"| textureFolderPath
 
|Specifies location of the textures (root folder is assumed to be Textures)
 
|String
 
|----
 
! scope="row"| altitudeLayer
 
|Influences whether pawns can walk through the Thing or must travel around it.
 
|Filth, DoorMoveable, BuildingTall, FloorEmplacement, Waist, Item, LowPlant, Projectile, Floor, PawnState
 
|----
 
! scope="row"| flammability
 
|Influences how likely it is for the Thing to catch fire and take damage.
 
|0 to 1.0
 
|----
 
! scope="row"| maxHealth
 
|Sets the maximum health of the Thing (if applicable).
 
|Any value above 0
 
|----
 
|}
 
  
 
[[Category:Defs]]
 
[[Category:Defs]]
 +
[[Category:Modding tutorials]]

Latest revision as of 10:30, 11 February 2019

Modding Tutorials

ThingDef is one of the many Defs used in RimWorld. Almost every "tangible" (and some intangible) things you see in RimWorld are backed by a ThingDef.

What you'll learn[edit]

You will learn the structure of ThingDef, how to use a decompiler to learn what a tag does, and along the way you'll learn the meaning of a few select tags.

What you will not learn[edit]

The goal of this tutorial is not to tell you what each XML tag does. ThingDef alone has 200+ valid XML tags, not counting hundreds of subtags. There are simply too many to document, and a lot of them are self-explanatory.

  • If you want a list of all XML tags (not just ThingDef) you'll want milon's autodocumentation project. Note that it only includes tags in use by RimWorld, not necessarily all tags available.
  • If you want to see what an earnest attempt at documenting the XML looks like, you'll want the XML Documentation Database. Last updated for A15.
  • If you want to see what a documentation attempt on this wiki looks like, view the history of this article and see that was last up to date in Alpha 9.

Fact of the matter is this: there is no documentation that will tell you the meaning and usage of every tag. There probably never will. If there is, it will be out-of-date soon enough.

Requirements[edit]

ILSpy v4.0 showing the decompiled ThingDef class, with the analyzer expanded on the smallVolume field. To the left a few of available fields are visible.

Introduction[edit]

There are hundreds of XML tags. Some of them are rudimentary tags required for basic operation. Most of them are self-explanatory, and you can always use the Find In Files functionality of your favourite text editor to see what it is used by, and what values already exist. Sometimes, this does not suffice. This tutorial is for those times.

An example[edit]

Let's take a look at the intricate tag. This tag serves as an example because unlike "DeteriorationRate" or "stackLimit" it's not immediately obvious what it does. This tutorial assumed you just used the Find In Files functionality of your favourite text editor and learned just one thing: Only the Component and Advanced component have this tag, and it's set to true.

<Defs>
    <ThingDef>
        <defName>ComponentIndustrial</defName>
        <intricate>true</intricate>
    </ThingDef>
</Defs>
The search result for intricate.

Take your favourite decompiler and search for intricate. Now right-click the result and hit analyze. The analyzer in my decompiler shows it's read in three places, and assigned nowhere. The decompiler doesn't show any assigning of this value because it's set in the XML. We can see it's read by PlayerItemAccessibilityUtility.CacheAccessibleThings and twice by Thing.SmeltProducts. Taking a closer look at the Thing+<SmeltProducts>c__Iterator4.MoveNext, this is an inner method for the enumerator[1]. That in itself doesn't do much, so let's take a look at SmeltProducts itself.

The view for SmeltProducts.

We can see here that SmeltProducts in turn is used for some economy related DebugOutput, and by MakeRecipeProducts. We can dive further down the rabbithole, but by now it is a reasonable assumption that SmeltProducts is used to determine what products you get from smelting. But what's the intricate tag? Well, SmeltProducts loops over the ingredients in the costList (i.e. the required ingredients to make an item) and checks if it's intricate. If it's not intricate, it will return the ingredient.

In other words, the intricate tag means that ThingDef won't survive a trip to the smelter. You don't get your components back if you smelt down an Assault rifle.

You can find the meaning of every XML tag this way. Some might be easier than others, but you can find (or make an educated guess) to the meaning of every XML tag.

Adding more tags[edit]

This requires C#. The current recommended way for maximum compatibility is by using a DefModExtension.

See also[edit]

  1. The what? An enumerable is a fancy type of list and the MoveNext means "go to the next item on the list". Apologies to those who have a background in computer science.