Modding Tutorials/PatchOperations

From RimWorld Wiki
Jump to: navigation, search

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>*/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

There are 11 available PatchOperation types:

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>

PatchOperationAttributeAdd

PatchOperationAttributeSet

PatchOperationAttributeRemove

PatchOperationAddModExtension

PatchOperationSetName

PatchOperationSequence

PatchOperationTest

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.