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:

<?xml version="1.0" encoding="utf-8" ?>
<Patch>
  <Operation Class="PatchOperationReplace">
    <xpath>Defs/TerrainDef[defName="WaterDeep"]/texturePath</xpath>
    <value>
      <texturePath>Your/Texture/Path/Here</texturePath>
    </value>
  </Operation>
</Patch>

This xml file simply goes inside YourMod/Patches/ and you're done.

Overview of available PatchOperations

These are the 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
  • PatchOperationAttributeRemove removes an attribute for the selected node
• Three allow for more complex operations:
  • PatchOperationAddModExtension adds a ModExtension.
  • PatchOperationSetName changes the name of a node.
  • PatchOperationSequence contains a set of other PatchOperations, and aborts upon any operation failing
• Three allow for conditional operations
  • PatchOperationTest tests nodes, which is useful inside a PatchOperationSequence
  • PatchOperationConditional tests nodes, and can do different operations depending on the result.
  • PatchOperationFindMod tests for the presence of another mod, and can do different operations depending on the result.

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. Note that these "paths" have zero relation to the file path or folder structure: They follow the structure of the XML nodes.

XPaths start at the root node. Since the root node of all Defs is enforced to be <Defs>, so Defs/ is the start of our xpath. */ is also valid, as it uses the * wildcard: * matches any element, so it'll match the root (the top level) of the XML tree. // is technically also valid, but because that construct selects all the elements in the XML tree, it's an expensive operation that makes game loading exponentially slower.

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:

Defs/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
<Defs> <ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList /> </ExampleDef> </Defs>	<Operation Class="PatchOperationAdd"> <xpath>*/ExampleDef[defName="Example"]/exampleList</xpath> <value> <li>Foo</li> <li>Bar</li> </value> </Operation>	<Defs> <ExampleDef> <defName>Example</defName> <exampleNode>Some text</exampleNode> <exampleList> <li>Foo</li> <li>Bar</li> </exampleList> </ExampleDef> </Defs>

PatchOperationInsert

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

PatchOperationRemove

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

PatchOperationReplace

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

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.