Modding Tutorials/PatchOperations

< Modding Tutorials

RimWorld Alpha 17 added a new modding feature: XML PatchOperations. Using these allows mods to edit specific elements of XML defs, rather than simply overwriting the old def with a new one, which was the required approach until A17. This greatly reduces mod conflicts, because mods that make separate changes to the same def won't necessarily overwrite one another's changes. Mods using PatchOperations can avoid requiring special compatibility mods, and can even add special features conditional on other mods being loaded.

Here's a simple example of replacing the texture path for deep water:

  <Operation Class="PatchOperationReplace">
	<xpath>*/TerrainDef[defName="WaterDeep"]/texturePath</xpath>
	<value><texturePath>Your/Texture/Path/Here</texturePath></value>
  </Operation>

Overview of available PatchOperations

There are 11 available PatchOperation types:

• Four do basic operations on XML nodes:
  • PatchOperationAdd adds a provided child node to the selected node
  • PatchOperationInsert adds a provided sibling node to the selected node
  • PatchOperationRemove deletes the selected node
  • PatchOperationReplace replaces the selected node with the provided node
• Three do basic operations on XML attributes:
  • PatchOperationAttributeAdd adds a provided attribute to the selected node if and only if the attribute name is not already present
  • PatchOperationAttributeSet sets a provided attribute for the selected node, overwriting the attribute value if the attribute name is already present
  • PatchOperationAttributeSet removes an attribute for the selected node
• Four allow for more complex operations:
  • PatchOperationAddModExtension adds a ModExtension.
  • PatchOperationSetName changes the name of a node. It is generally useless.
  • PatchOperationSequence contains a set of other PatchOperations, and aborts upon any operation failing
  • PatchOperationTest tests nodes, which is useful inside a PatchOperationSequence

XPath syntax

Each PatchOperation must specify an XML node to modify. It uses XPaths to specify them. An XPath is a "path" for the patch to follow when trying to find XML nodes matching the description. It will follow each part of the path from left to right.

Most XPaths should start with */. The * matches any element, so it'll match the root (the top level) of the XML tree. The following slash selects Using // is technically also valid, but because that construct selects all the elements in the XML tree, it's an expensive operation that makes a mod needlessly slow to load.

Once the root is selected, the XPath lets the system walk down specific branches of the tree. If we use the example from the lead, we get a specific path:

*/TerrainDef[defName="WaterDeep"]/texturePath

1. The root node is selected
2. All child nodes of the root node called "TerrainDef" are selected
3. We narrow down from "all TerrainDefs" to only those with the child "defName" node whose value is "WaterDeep", which should give us exactly one node because defNames must be unique
4. We select the child node "texturePath" from this node

Overview of individual PatchOperations

(to do)

PatchOperationAdd

Def before patch	Patch operation	Def after patch
<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList /> </ExampleDef>	<Operation Class="PatchOperationAdd"> <xpath>*/ExampleDef[defName="Example"]/exampleList</xpath> <value> <li>Foo</li> <li>Bar</li> </value> </Operation>	<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList> <li>Foo</li> <li>Bar</li> </exampleList> </ExampleDef>

PatchOperationInsert

Def before patch	Patch operation	Def after patch
<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList /> </ExampleDef>	<Operation Class="PatchOperationInsert"> <xpath>*/ExampleDef[defName="Example"]/exampleNode</xpath> <value> <anotherExample>A new sibling</anotherExample> </value> </Operation>	<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <anotherExample>A new sibling</anotherExample> <exampleList /> </ExampleDef>

PatchOperationRemove

Def before patch	Patch operation	Def after patch
<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList /> </ExampleDef>	<Operation Class="PatchOperationRemove"> <xpath>*/ExampleDef[defName="Example"]/exampleNode</xpath> </Operation>	<ExampleDef> <defName>Example</defName> <exampleList /> </ExampleDef>

PatchOperationReplace

Def before patch	Patch operation	Def after patch
<ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList /> </ExampleDef>	<Operation Class="PatchOperationReplace"> <xpath>*/ExampleDef[defName="Example"]/exampleNode</xpath> <value> <anotherExample>An alternate node</anotherExample> </value> </Operation>	<ExampleDef> <defName>Example</defName> <anotherExample>An alternate node</anotherExample> <exampleList /> </ExampleDef>

Resources

The best tutorial on PatchOperations created by Zhentar: Introduction to PatchOperation

You can also learn about XPaths here: XPath tutorial

There is also an Overview of PatchOperations on the RimWorldModGuide.