Difference between revisions of "Modding Tutorials/XML Defs"

From RimWorld Wiki
Jump to navigation Jump to search
m (→‎Structure: added / in the first sentence : of <Defs> and </Defs> as a ''type'' of ''def''.)
 
(One intermediate revision by one other user not shown)
Line 13: Line 13:
  
 
=Structure=
 
=Structure=
As previously established, the root node of all ''defs'' in the game is <Defs>. RimWorld will try to interpret everything between the opening tag of <Defs> and <Defs> as a ''type'' of ''def''. These ''types'' correspond to a C# class which inherits from the ''Def'' class. For example <source lang="xml"><Defs>
+
As previously established, the root node of all ''defs'' in the game is <Defs>. RimWorld will try to interpret everything between the opening tag of <Defs> and </Defs> as a ''type'' of ''def''. These ''types'' correspond to a C# class which inherits from the ''Def'' class. For example <source lang="xml"><Defs>
 
<ThingDef>
 
<ThingDef>
 
</ThingDef>
 
</ThingDef>
Line 28: Line 28:
  
 
=Common errors=
 
=Common errors=
 +
{{Main|Modding Tutorials/Troubleshooting}}
 
For beginning coders, the most common errors are '''formatting or syntax''' errors. A missing bracket, unclosed tag, empty file - these can all be avoided by using the proper tools. Get a text editor (or plug-in) that highlights or warns for these basic issues. RimWorld will not warn you: at best it will overload you with errors, at worst it will refuse to start.
 
For beginning coders, the most common errors are '''formatting or syntax''' errors. A missing bracket, unclosed tag, empty file - these can all be avoided by using the proper tools. Get a text editor (or plug-in) that highlights or warns for these basic issues. RimWorld will not warn you: at best it will overload you with errors, at worst it will refuse to start.
 
Other common errors are related to resolving cross-references. For instance: def A wants to use def B, but def B can't be found. These cross-references are by ''defName''. Both Type and defName have to match. In our earlier example, if there isn't a ''SoundDef'' with the ''Slurp'' defName, the game will log the following error:
 
 
        Could not resolve cross-reference: No SoundDef named Slurp found to give to ThingDef SomeName.
 
 
If the game can't find a cross-reference in a list, the error is slightly different:
 
 
        Could not resolve cross-reference to Verse.ThingCategoryDef named BuldingsPower (wanter=thingCategories)
 
 
where ''wanter=thingCategories'' is an optional addition, but it's the xml tag containing the misspelled "Bu'''i'''ldingsPower".<br/><br/>
 
 
Other errors are:
 
* Defining the same field/tag twice
 
        XML RimWorld.ThoughtDef defines the same field twice: stackLimit.
 
        Field contents: 1.
 
        Whole XML: <A lot of XML>
 
 
In this example, there is a ThoughtDef with two ''stackLimit'' entries. Likely the result of two mods patching the same Def. The first mod wins.
 
 
* Missing a Type
 
        Could not find type named TurretExtensions.CompProperties_Upgradable from node <A lot of XML>
 
This happens when an XML mod refers to a type which isn't loaded. In practice, a missing (DLL) dependency, a (DLL) dependency which couldn't be loaded due to earlier errors, or an outdated mod.<br/>
 
 
* Referencing a non-existing field
 
<source lang ="xml">        XML error: <costStaffCount>50</costStaffCount> doesn't correspond to any field in type ThingDef. Context: <ThingDef ParentName="SculptureBase"><defName>SculptureSmall</defName><label>small sculpture</label><description>An artistic sculpture.</description><stuffCategories><li>Metallic</li><li>Woody</li><li>Stony</li></stuffCategories><costStaffCount>50</costStaffCount></ThingDef></source>
 
 
This happens when the parentnode (in this case ''ThingDef'') does not contain an entry for the ''costSt'''a'''ffCount'' tag. This could be caused by a simple typo, by putting the tag in the wrong node, by a missing dependency, as a result of earlier errors, or an outdated mod. XML can only correspond to fields that are defined in C#.<br/>
 
  
 
=Note about (solving) XML errors=
 
=Note about (solving) XML errors=
 
XML errors '''cascade'''. Behind the scenes, RimWorld combines all Defs inside one massive XML document. If one <tag> is missing its closing </tag>, none of the XML will be readable by the parser and you will be greeted by a wall of red errors. Find the first XML error, and fix that one. Do not go chasing the other errors just yet. Reload the game, then fix the next error (if any).
 
XML errors '''cascade'''. Behind the scenes, RimWorld combines all Defs inside one massive XML document. If one <tag> is missing its closing </tag>, none of the XML will be readable by the parser and you will be greeted by a wall of red errors. Find the first XML error, and fix that one. Do not go chasing the other errors just yet. Reload the game, then fix the next error (if any).
 +
 +
[[Category: Modding tutorials]]
 +
[[Category: Modding]]

Latest revision as of 13:24, 16 February 2023

Modding Tutorials

Defs are packages containing most of the content for the game. They are stored in human-readable XML files, and you can take a look at them right now by browsing the Mods/Core/Defs folder located in the RimWorld install directory. There are many different types of Defs, the most common being ThingDef. Other examples of Defs are RecipeDef, ResearchProjectDef and TerrainDef.

Think of Defs as the system that turns a generic plant into a Potato-, Rice- or Corn plant. The C# contains the plant and its behaviour like growing and getting harvested the Defs determine how fast it grows and what its harvest products are.

Requirements[edit]

  1. You've read XML file structure.
  2. A basic understanding of XML is recommended.
  3. Some C# knowledge is helpful for a deeper understanding of the behind-the-scenes workings, but not required.

What you'll learn[edit]

This tutorial will tell you about the structure of Defs. It will explain the link between C# and Defs, as well as go over some common errors. If you want to learn what every tag for a Def is, read the ThingDef article.

Structure[edit]

As previously established, the root node of all defs in the game is <Defs>. RimWorld will try to interpret everything between the opening tag of <Defs> and </Defs> as a type of def. These types correspond to a C# class which inherits from the Def class. For example

<Defs>
	<ThingDef>
	</ThingDef>
</Defs>


points to the ThingDef class, which in C# inherits from the Def class. All XML nodes inside the <ThingDef> tag are a field in the ThingDef class. These fields can hold references to simple values like integers or strings. defName is one such string in the base Def class, so we'll give our ThingDef a defName of SomeName. A field can also contain more complex values like IngestibleProperties. The XML tag (and field name) that corresponds to IngestibleProperties is called ingestible. IngestibleProperties also has fields of its own, and these would go inside the ingestible tag, as a childnode. IngestibleProperties has a field of type SoundDef with the name of ingestSound. RimWorld resolves these by both Type and defName. Fleshing out our example with an ingestSound, our example now looks like this:

<Defs>
	<ThingDef>
		<defName>SomeName</defName>
		<ingestible>
			<ingestSound>Slurp</ingestSound>
		</ingestible>
	</ThingDef>
</Defs>


The rootnode of our example is <Defs>. The first childnode of <Defs> is <ThingDef>. <defName> and <ingestible> are both childnodes of <ThingDef> and they are siblingnodes of each other. Proper XML formatting will help you a lot in distinguishing the hierarchy of your XML. You can save yourself a lot of hassle if you get a text editor (or plugin) which can auto-format XML for you.

Common errors[edit]

For beginning coders, the most common errors are formatting or syntax errors. A missing bracket, unclosed tag, empty file - these can all be avoided by using the proper tools. Get a text editor (or plug-in) that highlights or warns for these basic issues. RimWorld will not warn you: at best it will overload you with errors, at worst it will refuse to start.

Note about (solving) XML errors[edit]

XML errors cascade. Behind the scenes, RimWorld combines all Defs inside one massive XML document. If one <tag> is missing its closing </tag>, none of the XML will be readable by the parser and you will be greeted by a wall of red errors. Find the first XML error, and fix that one. Do not go chasing the other errors just yet. Reload the game, then fix the next error (if any).