Editing Modding Tutorials/PatchOperations

{{BackToTutorials}}

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:

<source lang="xml">
<?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>
</source>
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|PatchOperationAdd]]''' adds a provided child node to the selected node
** '''[[#PatchOperationInsert|PatchOperationInsert]]''' adds a provided sibling node to the selected node
** '''[[#PatchOperationRemove|PatchOperationRemove]]''' deletes the selected node
** '''[[#PatchOperationReplace|PatchOperationReplace]]''' replaces the selected node with the provided node
* Three do basic operations on XML attributes:
** '''[[#PatchOperationAttributeAdd|PatchOperationAttributeAdd]]''' adds a provided attribute to the selected node if and only if the attribute name is not already present
** '''[[#PatchOperationAttributeSet|PatchOperationAttributeSet]]''' sets a provided attribute for the selected node, overwriting the attribute value if the attribute name is already present
** '''[[#PatchOperationAttributeRemove|PatchOperationAttributeRemove]]''' removes an attribute for the selected node
* Three allow for more complex operations:
** '''[[#PatchOperationAddModExtension|PatchOperationAddModExtension]]''' adds a ModExtension.
** '''[[#PatchOperationSetName|PatchOperationSetName]]''' changes the name of a node.
** '''[[#PatchOperationSequence|PatchOperationSequence]]''' contains a set of other PatchOperations, and aborts upon any operation failing
* Three allow for conditional operations
** '''[[#PatchOperationTest|PatchOperationTest]]''' tests nodes, which is useful inside a PatchOperationSequence
** '''[[#PatchOperationConditional|PatchOperationConditional]]''' tests nodes, and can do different operations depending on the result.
** '''[[#PatchOperationFindMod|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 <code>/Defs/</code> is the start of our xpath. <code>*/</code> is also valid, as it uses the <code>*</code> wildcard: <code>*</code> matches any element, so it'll match the root (the top level) of the XML tree. <code>//</code> 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:

<code>/Defs/TerrainDef[defName="WaterDeep"]/texturePath</code>

# The root node is selected
# All child nodes of the root node called "TerrainDef" are selected
# 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
# We select the child node "texturePath" from this node
## Note that we cannot put <code>.../texturePath/</code> to specify the content of the texturePath node.  If we want to replace texturePath, we have to replace it with <code><texturePath>/new/path/to/texture</texturePath></code>

For more info, see this {{LudeonThread|32785}}. XPath is a [https://www.w3schools.com/xml/xml_xpath.asp well-documented industry standard] (good resource, too); there are plenty of resources available on the subject ranging from exhaustive tutorials to simple [https://stackoverflow.com/questions/tagged/xpath StackOverflow] questions.

==Overview of individual PatchOperations==
===PatchOperationAdd===
''PatchOperationAdd'' adds a child node to the selected node.

{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationAdd">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleList</xpath>
    <value>
        <li>Foo</li>
        <li>Bar</li>
    </value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList>
            <li>Foo</li>
            <li>Bar</li>
        </exampleList>
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationInsert===
''PatchOperationInsert'' adds a sibling to the selected node.

{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationInsert">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <value>
        <anotherExample>A new sibling</anotherExample>
    </value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <anotherExample>A new sibling</anotherExample>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationRemove===
''PatchOperationRemove'' removes the selected node.

{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationRemove">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationReplace===
''PatchOperationReplace'' replaces the selected node.

{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationReplace">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <value>
        <anotherExample>An alternate node</anotherExample>
    </value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <anotherExample>An alternate node</anotherExample>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationAttributeAdd===
''PatchOperationAttributeAdd'' will add an attribute and set its value, but only if that attribute is not yet present.
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationAttributeAdd">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <attribute>ExampleAttribute</attribute>
    <value>ExampleValue</value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode ExampleAttribute"ExampleValue">Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationAttributeSet===
''PatchOperationAttributeSet'' will add an attribute and set its value. Unlike PatchAttributeAdd, PatchOperationAttributeSet will overwrite any existing value. 
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode ExampleAttribute"ExampleValue">Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationAttributeSet">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <attribute>ExampleAttribute</attribute>
    <value>DifferentExampleValue</value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode ExampleAttribute"DifferentExampleValue">Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationAttributeRemove===
''PatchOperationAttributeRemove'' removes the specified attribute.
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode ExampleAttribute"ExampleValue">Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationAttributeRemove">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <attribute>ExampleAttribute</attribute>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationAddModExtension===
{{Main|Modding Tutorials/DefModExtension}}
''PatchOperationAddModExtension'' adds a [[Modding Tutorials/DefModExtension|Mod Extension]].

{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">

<Operation Class="PatchOperationAddModExtension">
    <xpath>Defs/ExampleDef[defName="Example"]</xpath>
    <value>
        <li Class="ExampleNameSpace.ExampleModExtension">
            <exampleValue>true</exampleValue>
        </li>
    </value>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
        <modExtensions>
            <li Class="ExampleNameSpace.ExampleModExtension">
                <exampleValue>true</exampleValue>
            </li>
        </modExtensions>
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationSetName===
''PatchOperationSetName'' changes the name of a node.
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! Patch operation !! Def after patch
|-
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <exampleNode>Some text</exampleNode>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Operation Class="PatchOperationSetName">
    <xpath>Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
    <name>newExampleName</name>
</Operation>
</source>
| style="vertical-align: top;" |<source lang="xml">
<Defs>
    <ExampleDef>
        <defName>Example</defName>
        <newExampleName>Some text</newExampleName>
        <exampleList />
    </ExampleDef>
</Defs>
</source>
|-
|}

===PatchOperationSequence===
''PatchOperationSequence'' will complete all operations in the order of their listing, and stop when any of them fails.

===PatchOperationTest===
''PatchOperationTest'' tests for the existence/validity of an xpath. Useful to stop a PatchOperationSequence. Often used as a simpler, less powerful version of PatchOperationConditional.
The following example patch is from Apparello, by Shinzy. 
<source lang ="xml>
<Operation Class="PatchOperationSequence">
    <!-- check for worn graphics and if none found, add one -->
    <success>Always</success>
    <operations>
        <li Class="PatchOperationTest">
            <xpath>/Defs/ThingDef[defName = "Apparel_Pants"]/apparel/wornGraphicPath</xpath>
            <success>Invert</success>
        </li>
        <li Class="PatchOperationAdd">
            <xpath>/Defs/ThingDef[defName = "Apparel_Pants"]/apparel</xpath>
            <value>
                <wornGraphicPath>Accessorello/Pants/Pants</wornGraphicPath>
            </value>
        </li>
    </operations>
</Operation>
</source>

===PatchOperationConditional===
''PatchOperationConditional'' can branch logic based on a match/nomatch. The following example patch adds a <comps> node if it does not yet exist, and adds itself 

This patch is courtesy Mehni. [https://github.com/Mehni/MoreFactionInteraction/blob/ab3ab2a22ee529ee4e38a471fe150fd48fd07ce9/Patches/MoreFactionInteraction.xml#L40-L62 See original.]
<source lang ="xml">
<!-- Add /comps/li/compClass if there are no comps yet. -->
<!-- Add /li/compClass to /comps if exists (i.e. other mod already added the comps field first) -->
<Operation Class="PatchOperationConditional">
    <xpath>/Defs/WorldObjectDef[defName="Caravan"]/comps</xpath>
    <nomatch Class="PatchOperationAdd">
        <xpath>/Defs/WorldObjectDef[defName="Caravan"]</xpath>
        <value>
            <comps>
                <li>
                    <compClass>MoreFactionInteraction.WorldObjectComp_CaravanComp</compClass>
                </li>
            </comps>
        </value>
    </nomatch>
    <match Class="PatchOperationAdd">
        <xpath>/Defs/WorldObjectDef[defName="Caravan"]/comps</xpath>
        <value>
            <li>
                <compClass>MoreFactionInteraction.WorldObjectComp_CaravanComp</compClass>
            </li>
        </value>
    </match>
</Operation>
</source>

===PatchOperationFindMod===
''PatchOperationFindMod'' searches the list of active mods for the mods listed in <nowiki><li></li></nowiki> tags.

For a successful match, <nowiki><li>ModName</li></nowiki> has to match the <name>ModName</name> in the About.xml of the mod you base your patch behaviour on.
This (shortened) patch is courtesy Mehni. [https://github.com/Mehni/MoreFactionInteraction/blob/ab3ab2a22ee529ee4e38a471fe150fd48fd07ce9/Patches/MoreFactionInteraction.xml#L64 See original.]

The following Patch adds the RimQuest mod extension to the listed Defs when RimQuest is found.
<source lang ="xml">
<Operation Class="PatchOperationFindMod">
    <mods>
        <li>RimQuest</li>
    </mods>
    <match Class="PatchOperationAddModExtension">
        <xpath>Defs/IncidentDef[defName="MFI_DiplomaticMarriage" or defName="MFI_HuntersLodge" or defName="MFI_Quest_PeaceTalks"]</xpath>
        <value>
            <li Class = "RimQuest.RimQuest_ModExtension">
                <canBeARimQuest>false</canBeARimQuest>
            </li>
        </value>
    </match>
</Operation>
</source>

The following Patch replace the tabWindowClass of the xpath when Relations Tab is '''not''' found. 
<source lang ="xml">
<Operation Class="PatchOperationFindMod">
    <mods>
        <li>Relations Tab</li>
    </mods>
    <nomatch Class="PatchOperationReplace">
        <xpath>/Defs/MainButtonDef[defName="Factions"]/tabWindowClass</xpath>
        <value>
            <tabWindowClass>MyNameSpace.MyTabWindowClass</tabWindowClass>
        </value>
    </nomatch>
</Operation>
</source>

==Some advanced examples==
This (shortened) patch is courtesy XeoNovaDan. [https://github.com/XeoNovaDan/SurvivalTools/blob/62a4316c81733dde417257bf4bc5c34e3e781c7d/Patches/ExpandedWoodworkingVGP/Patch.xml See original]. Viewer discretion is advised. Parents please take precautions if young children are present.
<source lang = "XML">
<Operation Class="PatchOperationFindMod">
    <mods>
        <li>Expanded Woodworking for Vegetable Garden Project</li>
    </mods>
    <match Class="PatchOperationSequence">
        <success>Always</success>
        <operations>
            <!-- Nested PatchOpFindMod. Used because Expanded Woodworking adds more Wood when VGP Xtra is installed. -->
            <li Class="PatchOperationFindMod">
                <mods>
                    <li>VGP Xtra Trees and Flowers</li>
                </mods>
                <match Class="PatchOperationSequence">
                    <success>Always</success>
                    <operations>
                        <!-- Processed camellia lumber. Mostly useful for building long-lasting, simple structures and furniture.-->
                        <li Class="PatchOperationAddModExtension">
                            <xpath>Defs/ThingDef[defName="LumberCamellia"]</xpath>
                            <value>
                                <li Class="SurvivalTools.StuffPropsTool">
                                    <toolStatFactors>
                                        <ConstructionSpeed>0.55</ConstructionSpeed>
                                    </toolStatFactors>
                                </li>
                            </value>
                        </li>
                    </operations>
                </match>
            </li>
        </operations>
    </match>
</Operation>
</source>

===Random stuff===
* @ select by attribute. Useful for patching (Abstract) bases. <source lang = "xml">/Defs/ThingDef[@Name="BuildingBase"]</source>
* ''or'' is inclusive. <source lang = "xml">/Defs/ThingDef[defName="Cassowary" or defName = "Emu" or defName = "Ostrich" or defName = "Turkey"]</source> selects all of those in a single (faster) operation.
* PatchOperationAdd and PatchOperation insert have an ''order'' tag which allows you to either Prepend or Append your add. Default behaviour of Add is to Append, insert Prepends.
* There is a ''success'' tag whose values can be Normal, Invert, Always and Never. This is used for the sake of error reporting: by default an error is logged when a patch fails to apply. For PatchOperationSequences and PatchOperationTests, you can set success to Always to avoid error logging.

== Write your own ==
Outside the scope of this wiki, but it's possible to write your own PatchOperation.</br>
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]</br>
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]</br>

== Resources ==

The best tutorial on PatchOperations created by Zhentar: [https://gist.github.com/Zhentar/4a1b71cea45b9337f70b30a21d868782 Introduction to PatchOperation]

You can also learn about XPaths here: [https://www.w3schools.com/xml/xpath_intro.asp XPath tutorial]

There is also an [https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL:-DefPatches Overview of PatchOperations]  on the [https://github.com/roxxploxx/RimWorldModGuide/wiki RimWorldModGuide].


[[Category:Modding]]