RimWorld Wiki - User contributions [en]

Modding Tutorials/Translation

2024-01-20T18:36:52Z

Lilwhitemouse: Because I searched for Translation first

#REDIRECT [[Modding Tutorials/Localization]]

File:NPD-Royalty.png

2023-09-10T18:57:47Z

Lilwhitemouse:

A nutrient paste dispenser VERY CLOSE to a royal throne room, but not in the throne room where NPDs are not allowed

Time

2020-06-11T23:08:20Z

Lilwhitemouse: rare and long tick conversion

<noinclude>
{| align=center
| {{Gameplay_Nav}}
|}
----

</noinclude>
'''Time''' in RimWorld passes as a series of ticks. On normal game speed, there are 60 such ticks to a real second; there are always 2,500 ticks to one in-game hour.

The game starts in the year 5500. The in-game clock is in 24-hour format with the hours displayed in military time from 0h to 23h.

Time proceeds as one would expect except that the four months are named "quadrums." They are named as portmanteaus of terrestrial months, suggesting seasonal associations: "Decembary," "Aprimay," "Jugust," and "Septober." Each individual quadrum is always 15 days, after which you proceed into the next quadrum.

Time of day is modeled on the planet view; local time of day corresponds to how the sunlight hits the planet.

{{asof|A17}} season names could no longer be consistently applied to the entire globe, necessitating that they be named as month-like "quadrums."

<noinclude>
{| {{STDT|c_01 text-right}}
! colspan='2' | In-Game Time
! colspan='1' | Ticks
! colspan='1' | Real Time
|-
! 1.44 Min
| || 60 || 1s
|-
! 1 Hour
| 60 Min || 2,500 || ~{{Time| 60000/60/24 }}
|-
! 1 Day
| 24 Hours || 60,000 || {{Time| 60000/60 }}
|-
! 1 Quadrum
| 15 Days || 900,000 || {{Time| 60000/60*15 }}
|-
! 1 Year
| 4 Quadrums || 3,600,000 || {{Time| 60000/60*15*4 }}
|}
{| {{STDT|c_01 text-right}}
|-
! colspan='3' | Technical details for modders
|-
!
! Ticks
! Game Time
|-
| 1 tick || 1 tick || 1/60th second
|-
| 1 rare tick || 250 ticks || 4.16 seconds
|-
| 1 long tick || 2000 ticks || 33.33 seconds
|}
[[Category:Game mechanics]]
</noinclude>

Trade

2020-06-08T11:33:37Z

Lilwhitemouse: /* Retreat */ goodwill loss on strip

{| align=center
| {{Gameplay_Nav}}
|}
----

{{TOCright}}
<onlyinclude>
Colonies can trade with other factions by using [[caravan]]s and orbital trade ships via a comms console. Tradeable commodities include [[colonists|slaves]]/[[prisoners]], [[furniture]], [[gear]], [[resources]], [[food]], [[drugs]], and [[sculptures|works of art]].

The trade interface shows what commodities are available to trade, the colony's stock, the trader's stock, and the prices to buy and sell.

{|class="wikitable" style="text-align: center;"
!colspan="2"|BUY
!QUANTITY
!colspan="2"|SELL
|-
|ALL||ONE||<tt>positive = buy negative = sell</tt>||ONE||ALL
|-
|'''{{key|<<}}'''||'''{{key|<}}'''||<tt>may type # here</tt>||'''{{key|>}}'''||'''{{key|>>}}'''
|}

* Trade is influenced by your trader's ability to speak and hear. Damage to any such parts will ruin trade prices.
* Prices listed in green are cheap (does not appear with base-game traders), while prices listed in red are expensive.
* Items that the foreign trader has no interest in are shown grayed out at the bottom of the list; other traders may want them instead.
* Animals that have been downed are not listed for trade.
* All traders carry a limited amount of silver, so they may not be able to buy everything you wish to sell. You can still give them things but everything they receive will be for free, as they cannot afford to pay.
* Selling a prisoner is profitable, but has a [[Thoughts#A prisoner was sold|negative impact on the happiness]] of all colonists (excludes psychopaths).

== Game progression ==

=== Early game ===

Caravans consist of one or more faction members often with pack animals and/or tamed animals in tow. Players can either form their own caravan or wait for others to visit their own colony. To trade with a foreign passing caravan, direct a colonist (preferably with high social skill as he/she can get better prices) to speak with the caravan member who has a yellow question mark above the head. Stored items will be eligible to sell and appear in the trade window. Purchased items will be dropped in the location where the trader was standing and will need to be hauled.

Sometimes, foreign caravan members may fight each other and accidentally drop items from their gear inventory.

=== Later game ===

After finishing the required research, a [[comms console]] and an [[orbital trade beacon]] can be built, which allow:

* Satellite calls to request caravans to allied factions at a cost of 15 goodwill (or 700/1100 silver prior to 1.0). You can only call for a caravan from a given friendly faction once every four days.

* Interaction with orbital trade ships which will stay around for a limited time. A blue notification will appear at the right of your screen to announce the trade ship and its type. After it's gone, a simple notice at the top of the screen will note when the same vessel leaves comms range and can no longer be traded with. Each trade ship varies in type, which determines its inventory.

To trade, order a colonist to interact with the comms console. Only items located within range of an orbital trade beacon can be traded. Purchases will be sent via drop pods to a beacon's open-air tiles, drop pods will phase through constructed roofs otherwise. If all beacon tiles are covered, drop pods will land at the nearest eligible tile. Colonists with a higher social skill using the comms console will negotiate lower buying prices and higher selling prices for everything (1.5% per social skill point). [[Prisoner]]s can be sold directly from their cell even if not in range of a beacon and tamed [[animals]] can be sold from anywhere on the map. The trade value of a prisoner or animal is based on their capabilities, injuries and skills.

== Trade prices ==

Hovering over an item's price opens a tooltip that displays price modifiers. Usually, goods from the colony are sold at 60% market value, and bought at 140% market value. These are further affected by the difficulty setting; see [[AI Storytellers#Challenge Scale|Challenge Scale]].

Actual trade prices are also dependent on the [[Trade Price Improvement]] stat of chosen colonist, listed on the tooltip as <tt>"Your negotiator bonus: -''x''%"</tt>.

Some traders will charge 2x the price of a good, in addition to the multiplier on buying. Selling remains at normal price.
Faction bases don't have any goods-specific price penalties and will even offer a 2% discount when trading at a base.

== Types of Traders ==

=== Land Convoy ===

*'''Visitors''' are small groups that carry all of their goods on their person. They may or may not have items for trade; even if they do, they often have few items and little silver to trade with.
*'''Trade caravans''' are large groups that carry their goods on pack [[muffalo]] or [[dromedary|dromedaries]], depending on climate. They have a moderate amount of items and silver to buy trade with.

Land convoys will leave the area if the temperature is deemed too dangerous for them to continue trading.

[[File:Visitors but not traders.png|400px|thumb|none|Visitors but not traders, no character with ('''?''') sign overhead]].

=== Technological Level ===

* '''Neolithic''' traders are tribal in nature and will be limited to selling neolithic level items.
* '''Outlander''' traders come from other faction settlements and are not restricted to a specific technology level of items.

=== Faction Bases ===

Large faction settlements that engage in trading. They buy/sell everything within their technology level, have the most extensive stocks and offer a 2% discount.

=== Physical presence ===

*'''Outlander traders''' have a physical presence on the map and offer a small to medium amount of items and silver.
*'''Orbital traders''' have no physical presence. They have large amounts of items and silver to trade with, and have the same trader types as outlanders.

''While the game does not specify where orbital traders hail from, the technologically advanced nature of items that they carry generally indicates that they are from midworlds, urbworlds or glitterworlds.''

=== By inventory ===

==== Bulk goods trader ====

'''Bulk goods traders''' deal in [[food]] and basic materials, such as [[steel]], [[wood]], [[component]]s, [[gold]], [[textiles]], as well as [[clothing]], [[furniture]] and domesticated animals.

==== Combat supplier ====

'''Combat suppliers''' deal in [[weapons]], [[armor]], [[mortar shell]]s, and [[medicine]].

The tribal variant of this is the '''War merchant'''.

==== Exotic Goods Trader ====

'''Exotic Goods Traders''' deal in rare and valuable items such as artifacts, [[Joy|televisions]], [[Joy|telescopes]], [[Gear|apparel]], [[Medical Items|bionic body parts]], [[neurotrainer]]s, some [[furniture]], [[plasteel]], [[gold]], [[uranium]], and [[glitterworld medicine]]. The may also carry animals of the wilder variety.

The tribal variant of this is the '''Shaman merchant'''.

==== Pirate Merchant ====

'''Pirate Merchants''' and its derivatives deal in slaves/prisoners, weapons, body parts, medicine, and drugs. The chance of traders carrying prisoners should go down as colony population goes up.

The tribal variant of this is the '''Slaver'''.

== Trader inventories ==

=== Faction base ===

Faction bases have an extensive inventory and deal with most things.

==== Outlander base ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 800 || 3000
|-
! [[Component]]
| x1 || 20 || 70
|-
! [[Steel]]
| x1 || 300 || 600
|-
! [[Wood]]
| x1 || 200 || 400
|-
! [[Plasteel]]
| x1 || -50 || 200
|-
! [[Cloth]]
| x1 || 100 || 300
|-
! [[Gold]]
| x1 || -50 || 200
|-
! [[Neutroamine]]
| x1 || 50 || 200
|-
! [[Chemfuel]]
| x1 || 300 || 500
|-
! [[Chocolate]]
| x1 || -30 || 70
|-
! [[Beer]]
| x1 || -40 || 100
|-
! [[Medicine]]
| x1 || 25 || 50
|-
![[Telescope]]
| x1 || 0 || 1
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
! Mortar shells
| x1 || 1 - 2 kinds || 20 each || 40 each || All [[mortar shell]]s except [[antigrain warhead]]
|-
! Textiles
| x1 || 1 - 2 kinds || 400 {{icon|silver}} || 800 {{icon|silver}} || All [[Textiles]]
|-
! Resources
| x1 || 2 - 4 kinds || 400 {{icon|silver}} || 800 {{icon|silver}} || All resources except [[silver]]
|-
! Raw food
| x1 || 2 - 4 kinds || 400 {{icon|silver}} || 800 {{icon|silver}} || All except fertilized eggs
|-
! Meals
| x1 || 1 - 2 kinds || 12 each || 50 each || All [[meal]]s
|-
! Furniture
| x1 || 3 - 4 kinds || 1 each || 2 each || All [[furniture]]
|-
! Animals
| x1 || 2 - 4 kinds || 3 each || 8 each || Most animals
|-
! Clothing
| x1 || 10 - 16 kinds || 1 each || 1 each|| All [[clothing]]
|-
! Drugs
| x1 || 3 - 4 kinds || 750 {{icon|silver}} || 1500 {{icon|silver}} || All [[drugs]]
|-
!Ranged weapons
| x1 || 3 - 6 kinds || 1 each || 1 each || All ranged weapons
|-
!Melee weapons
| x1 || 3 - 4 kinds || 1 each || 2 each || All melee weapons
|-
!Armor
| x1 || 2 - 4 kinds || 1 each || 1 each || All [[armor]]
|-
!Body parts/ Implants
| x1 || 2 - 4 kinds || 1 each || 1 each || All body parts or implants
|-
!Exotic items
| x1 || 1 - 4 kinds || 1 each || 2 each || Rare items
|-
!Artifacts
| x1 || 1 - 4 kinds || 1 each || 1 each || All artifacts
|-
!Apparel
| x1 || 3 - 6 kinds || 1 each || 10 each || All [[apparel]]
|-
!Art
| x1 || 5 - 10 kinds || 1 each || 1 each || [[Sculptures]]
|-
!Televisions
| x1 || 1 - 2 kinds || 1 each || 2 each || [[Tube television]], [[Flatscreen television]], [[Megascreen television]]
|-
! Slaves
| x1 || -1 - 2 || 1 each || 1 each || ---
|-
|}

----

==== Neolithic base ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 800 || 3000
|-
! [[Component]]
| x2 || 3 || 10
|-
! [[Steel]]
| x1 || 200 || 300
|-
! [[Wood]]
| x1 || 500 || 600
|-
! [[Cloth]]
| x1 || 200 || 300
|-
! [[Gold]]
| x1 || -40 || 120
|-
! [[Pemmican]]
| x1 || 500 || 1000
|-
! [[Herbal medicine]]
| x1 || 15 || 30
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
! Textiles
| x1 || 1 - 2 kinds || 300 {{icon|silver}} || 700 {{icon|silver}} || All [[Textiles]]
|-
! Resources
| x1 || 3 kinds || 200 {{icon|silver}} || 600 {{icon|silver}} || All resources except [[silver]]
|-
! Raw food
| x1 || 3 - 5 kinds || 300 {{icon|silver}} || 800 {{icon|silver}} || All except fertilized eggs
|-
! Clothing
| x1 || 4 - 12 kinds || 1 each || 1 each|| Neolithic [[clothing]]
|-
! Animals
| x1 || 2 - 4 kinds || 1 each || 5 each || Wildness below 70%
|-
! Animals
| x1 || 1 - 2 kinds || 1 each || 4 each || Powerful  animals
|-
! Drugs
| x1 || 1 - 2 kinds || 400 {{icon|silver}} || 1000 {{icon|silver}} || [[Beer]], [[smokeleaf joint]], [[psychoid pekoe]]
|-
!Ranged weapons
| x1 || 2 - 4 kinds || 1 each || 1 each || Neolithic ranged
|-
!Melee weapons
| x1 || 2 - 4 kinds || 1 each || 2 each || Neolithic melee
|-
! Slaves
| x1 || -1 - 2 || 1 each || 1 each || ---
|-
!Artifacts
| x1 || 0 - 3 kinds || 1 each || 1 each || All artifacts
|-
|}

----

=== Orbital ===

Orbital traders usually come with large stocks corresponding to their trader type.

==== Bulk goods trader ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 2000 || 4000
|-
! [[Component]]
| x1 || 15 || 30
|-
! [[Steel]]
| x1 || 500 || 800
|-
! [[Wood]]
| x1 || 500 || 800
|-
! [[Plasteel]]
| x1 || 100 || 400
|-
! [[Cloth]]
| x1 || 200 || 600
|-
! [[Medicine]]
| x2 || 20 || 30
|-
! [[Gold]]
| x1 || 50 || 200
|-
! [[Neutroamine]]
| x1 || 100 || 200
|-
! [[Chemfuel]]
| x1 || 200 || 600
|-
! [[Chocolate]]
| x1 || -70 || 100
|-
! [[Beer]]
| x1 || -70 || 100
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
! Textiles
| x1 || 1 - 2 kinds || 2200 {{icon|silver}} || 4000 {{icon|silver}} || All [[Textiles]]
|-
! Resources
| x1 || 2 - 4 kinds || 800 {{icon|silver}} || 1500 {{icon|silver}} || All resources except [[silver]]
|-
! Raw food
| x1 || 2 - 4 kinds || 800 {{icon|silver}} || 1500 {{icon|silver}} || All except fertilized eggs
|-
! Meals
| x1 || 1 - 2 kinds || 15 each || 30 each || All [[meal]]s
|-
! Furniture
| x1 || 0 - 3 kinds || 1 each || 2 each || All [[furniture]]
|-
! Clothing
| x1 || 10 - 20 kinds || 1 each || 1 each|| All [[clothing]]
|-
! Drugs
| x1 || 2 - 4 kinds || 1000 {{icon|silver}} || 2000 {{icon|silver}} || All [[drugs]]
|-
! Animals
| x1 || 2 - 4 kinds || 10 each || 20 each || Animals with wildness below 70%
|-
|}

Commonality: 2

----

==== Combat supplier ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 2000 || 4000
|-
! [[Component]]
| x2 || 5 || 10
|-
! [[Medicine]]
| x1 || 30 || 50
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
! Mortar shells
| x1 || 1 - 2 kinds || 20 each || 40 each || All [[mortar shell]]s except [[antigrain warhead]]
|-
!Ranged weapons
| x1 || 5 - 6 kinds || 1 each || 1 each || All ranged weapons
|-
!Melee weapons
| x1 || 5 - 6 kinds || 2 each || 3 each || All melee weapons
|-
!Armor
| x1 || 8 - 10 kinds || 1 each || 1 each || All [[armor]]
|-
|}

Commonality: 1

----

==== Exotic goods trader ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 2000 || 4000
|-
! [[Component]]
| x2 || 5 || 30
|-
! [[Gold]]
| x1 || 200 || 400
|-
! [[Plasteel]]
| x1 || 100 || 400
|-
! [[Glitterworld medicine]]
| x1 || 5 || 30
|-
! [[Neutroamine]]
| x1 || 100 || 500
|-
![[Telescope]]
| x1 || 1 || 1
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
!Drugs
| x1 || 3 - 4 kinds || 2000 {{icon|silver}} || 3000 {{icon|silver}} || All drugs
|-
!Exotic items
| x1 || 3 - 5 kinds || 1 each || 2 each || Rare items
|-
!Body parts/ Implants
| x1 || 3 - 5 kinds || 1 each || 1 each || All body parts or implants
|-
!Artifacts
| x1 || 2 - 4 kinds || 1 each || 1 each || All artifacts
|-
!Art
| x1 || 4 - 8 kinds || 1 each || 1 each || [[Sculptures]]
|-
!Televisions
| x1 || 1 - 3 kinds || 1 each || 1 each || [[Tube television]], [[Flatscreen television]], [[Megascreen television]]
|-
! Furniture
| x1 || 1 - 4 kinds || 1 each || 2 each || All [[furniture]]
|-
! Animals
| x1 || 1 - 2 kinds || 2 each || 3 each || Animals with wildness above 60%
|-
|}

Commonality: 1

----

==== Pirate merchant ====

{| {{STDT|sortable c_03}}
! Name !! Price !! Min Stock !! Max Stock
|-
! [[Silver]]
| N/A || 2000 || 4000
|-
! [[Component]]
| x2 || 5 || 10
|-
! [[Beer]]
| x1 || -300 || 300
|-
! [[Medicine]]
| x2 || 5 || 15
|-
! [[Neutroamine]]
| x2 || 100 || 400
|-
! [[Chemfuel]]
| x2 || 50 || 200
|-
|}

'''Groups of items:'''
{| {{STDT|sortable c_03}}
! Group !! Price !! Variety !! Min Stock !! Max Stock !! Items
|-
! Slaves
| x1 || 2 - 3 || 1 each || 1 each || ---
|-
!Ranged weapons
| x1 || -1 - 2 kinds || 1 each || 1 each || All ranged weapons
|-
!Armor
| x1 || -2 - 2 kinds || 1 each || 1 each || All armor
|-
!Body parts/ Implants
| x1 || -4 - 5 kinds || 1 each || 1 each || All body parts or implants
|-
!Artifacts
| x1 || -5 - 1 kinds || 1 each || 1 each || All artifacts
|-
!Drugs
| x1 || 3 - 6 kinds || 2000 {{icon|silver}} || 3000 {{icon|silver}} || All drugs
|-
|}

Commonality: 1

== Trader behavior ==

Trade caravans that come to your colony usually pick a random spot where they will simply wander around and wait for your colonists to send a negotiator for trade. When hungry they may use the colony's tables and chairs for dining, and will sleep on the floor when exhausted.

=== Retreat ===

Sometimes, certain occurrences can cause foreign characters to leave your map before you have the chance to interact with them. They can just fight each other just like your own people do. In other occasions, they may get attacked by wild animals. They may leave the map on their own if the temperature becomes too high or too low for them or their animals. Some of them might get killed and others may only get downed, leaving a chance for rescue either by their own or by yourself. Items they drop can be unforbidden for you to take. As of the May 27, 2020 version of the game, stripping clothes from anyone unconscious causes a loss of goodwill.

<gallery widths="400px" heights="400px" class="center" mode="nolines">
File:Foreign traders taking a downed guest.png|'''Foreign traders taking a wounded guest (wild animal attack) back to their base.'''
File:Foreign trader downed due to overdose.png|'''Foreign trader downed due to overdose.'''
</gallery>

== Notes ==

* You cannot buy back prisoners you just sold as a way to insta-recruit anyone (exploit prevention).
* You can trade your expensive items (weapons, sculptures) for other desirable items if the trade ship doesn't have enough silver to complete the transaction. Of course, the amount of silver you can gain is lower, but it is usually better to have a lot of cheap items than an expensive one in your store. Sometimes you have items so expensive that no trader can buy them.

[[Category:Trade]]

Modding Tutorials/PatchOperations

2020-01-23T18:53:26Z

Lilwhitemouse: /* PatchOperationConditional */

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests, where you'd not want to throw an error on a simple test.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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.

Modders will often specify <code><success>Always</success></code>, which will mean that even if one part of the sequence fails (e.g., a test), the whole is still considered a success and no unneeded errors show up.

'''Patch Operation'''
<source lang="xml">
<Operation Class="PatchOperationSequence">

<operations>
<li Class="PatchOperationInsert">
<xpath>/Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
<value>
<anotherExample>A new sibling</anotherExample>
</value>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs/ExampleDef[defName="Example"]</xpath>
<value><label>I'm a node</label></value>
<li>

<operations>
</Operation>
</source>

'''Effect'''
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! 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">
<Defs>
<ExampleDef>
<label>I'm a node</label>
<defName>Example</defName>
<exampleNode>Some text</exampleNode>
<anotherExample>A new sibling</anotherExample>
<exampleList />
</ExampleDef>
</Defs>
</source>
|-
|}

'''Another Example''': Maybe you don't like the "Example" ExampleDef...
<source lang="xml">
<Operation Class="PatchOperationSequence">
<success>Always</success>
<operations>
<li Class="PatchOperationRemove">
<xpath>/Defs/ExampleDef[defName="Example"]<xpath>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs</xpath>
<value>
<ExampleDef><defName>MyBetterExample</defName></ExampleDef>
</value>
</operations>
</Operation>
</source>

If ExampleDef were already gone, MyBetterExample would not get added.

===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">

<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

''Important Note:'' If the xpath does not match and <nomatch> has not been specified, this will return 'false' - which may throw an error to the user. Likewise, if the xpath does match and there is no <match>, a failure. You may specify <success>Always</success> to avoid any errors.

This patch is courtesy Mehni. [https://github.com/Mehni/MoreFactionInteraction/blob/ab3ab2a22ee529ee4e38a471fe150fd48fd07ce9/Patches/MoreFactionInteraction.xml#L40-L62 See original.]
<source lang ="xml">


<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. It only needs to find ''one'' of the mods in the list for a successful match.
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>

==Common issues==
Spelling matters, and XPath is case sensitive. It's ''very'' case sensitive. If you've written something that doesn't work but you're convinced it should, put it through some XPath validator. Case sensitivity includes but is not limited to the <Operation Class="PatchOperationWhatever">, the XPath, the value, every tag -- spell it right.

Another common issue is swapping Insert and Add, which leads to a different position in the node. A common misconception is trying to account for file paths. The file path is completely irrelevant to the expression you're writing. XPath is used to search XML content, not files themselves.

Still beating your head against a wall? The main RimWorld [https://discord.gg/RimWorld discord] has helpful people and a bot where you can test XPath, and the forums have a [https://ludeon.com/forums/index.php?board=14.0 help] section as well.

==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>

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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 PatchOperationInsert 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.
* More useful things:
** Select nodes by text <source lang = "xml">ExampleTag/li[text()="Submit"]</source>
** Select nodes by text with a type of wildcard <source lang = "xml">ExampleTag[contains(text(), "MFI_")]</source>
** Exclude nodes with not() <source lang = "xml">[not(xxxxx)]</source>
** Can't think of an example but I'm sure someone will find a use for <source lang = "xml">[count(li)]</source>
** Go back to parentnode with <source lang = "xml">..</source>

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

== 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]]
[[Category:Modding tutorials]]

Modding Tutorials/PatchOperations

2020-01-12T14:43:42Z

Lilwhitemouse: /* PatchOperationAttributeSet */ put in = for attriubute examples

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests, where you'd not want to throw an error on a simple test.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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.

Modders will often specify <code><success>Always</success></code>, which will mean that even if one part of the sequence fails (e.g., a test), the whole is still considered a success and no unneeded errors show up.

'''Patch Operation'''
<source lang="xml">
<Operation Class="PatchOperationSequence">

<operations>
<li Class="PatchOperationInsert">
<xpath>/Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
<value>
<anotherExample>A new sibling</anotherExample>
</value>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs/ExampleDef[defName="Example"]</xpath>
<value><label>I'm a node</label></value>
<li>

<operations>
</Operation>
</source>

'''Effect'''
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! 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">
<Defs>
<ExampleDef>
<label>I'm a node</label>
<defName>Example</defName>
<exampleNode>Some text</exampleNode>
<anotherExample>A new sibling</anotherExample>
<exampleList />
</ExampleDef>
</Defs>
</source>
|-
|}

'''Another Example''': Maybe you don't like the "Example" ExampleDef...
<source lang="xml">
<Operation Class="PatchOperationSequence">
<success>Always</success>
<operations>
<li Class="PatchOperationRemove">
<xpath>/Defs/ExampleDef[defName="Example"]<xpath>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs</xpath>
<value>
<ExampleDef><defName>MyBetterExample</defName></ExampleDef>
</value>
</operations>
</Operation>
</source>

If ExampleDef were already gone, MyBetterExample would not get added.

===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">

<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">


<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. It only needs to find ''one'' of the mods in the list for a successful match.
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>

==Common issues==
Spelling matters, and XPath is case sensitive. It's ''very'' case sensitive. If you've written something that doesn't work but you're convinced it should, put it through some XPath validator. Case sensitivity includes but is not limited to the <Operation Class="PatchOperationWhatever">, the XPath, the value, every tag -- spell it right.

Another common issue is swapping Insert and Add, which leads to a different position in the node. A common misconception is trying to account for file paths. The file path is completely irrelevant to the expression you're writing. XPath is used to search XML content, not files themselves.

Still beating your head against a wall? The main RimWorld [https://discord.gg/RimWorld discord] has helpful people and a bot where you can test XPath, and the forums have a [https://ludeon.com/forums/index.php?board=14.0 help] section as well.

==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>

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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 PatchOperationInsert 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.
* More useful things:
** Select nodes by text <source lang = "xml">ExampleTag/li[text()="Submit"]</source>
** Select nodes by text with a type of wildcard <source lang = "xml">ExampleTag[contains(text(), "MFI_")]</source>
** Exclude nodes with not() <source lang = "xml">[not(xxxxx)]</source>
** Can't think of an example but I'm sure someone will find a use for <source lang = "xml">[count(li)]</source>
** Go back to parentnode with <source lang = "xml">..</source>

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

== 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]]
[[Category:Modding tutorials]]

Modding Tutorials/PatchOperations

2019-12-24T00:26:07Z

Lilwhitemouse: /Defs slightly faster than Defs: see https://ludeon.com/forums/index.php?topic=32785.msg458062#msg458062

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests, where you'd not want to throw an error on a simple test.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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.

Modders will often specify <code><success>Always</success></code>, which will mean that even if one part of the sequence fails (e.g., a test), the whole is still considered a success and no unneeded errors show up.

'''Patch Operation'''
<source lang="xml">
<Operation Class="PatchOperationSequence">

<operations>
<li Class="PatchOperationInsert">
<xpath>/Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
<value>
<anotherExample>A new sibling</anotherExample>
</value>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs/ExampleDef[defName="Example"]</xpath>
<value><label>I'm a node</label></value>
<li>

<operations>
</Operation>
</source>

'''Effect'''
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! 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">
<Defs>
<ExampleDef>
<label>I'm a node</label>
<defName>Example</defName>
<exampleNode>Some text</exampleNode>
<anotherExample>A new sibling</anotherExample>
<exampleList />
</ExampleDef>
</Defs>
</source>
|-
|}

'''Another Example''': Maybe you don't like the "Example" ExampleDef...
<source lang="xml">
<Operation Class="PatchOperationSequence">
<success>Always</success>
<operations>
<li Class="PatchOperationRemove">
<xpath>/Defs/ExampleDef[defName="Example"]<xpath>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs</xpath>
<value>
<ExampleDef><defName>MyBetterExample</defName></ExampleDef>
</value>
</operations>
</Operation>
</source>

If ExampleDef were already gone, MyBetterExample would not get added.

===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">

<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">


<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. It only needs to find ''one'' of the mods in the list for a successful match.
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>

==Common issues==
Spelling matters, and XPath is case sensitive. It's ''very'' case sensitive. If you've written something that doesn't work but you're convinced it should, put it through some XPath validator. Case sensitivity includes but is not limited to the <Operation Class="PatchOperationWhatever">, the XPath, the value, every tag -- spell it right.

Another common issue is swapping Insert and Add, which leads to a different position in the node. A common misconception is trying to account for file paths. The file path is completely irrelevant to the expression you're writing. XPath is used to search XML content, not files themselves.

Still beating your head against a wall? The main RimWorld [https://discord.gg/RimWorld discord] has helpful people and a bot where you can test XPath, and the forums have a [https://ludeon.com/forums/index.php?board=14.0 help] section as well.

==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>

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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 PatchOperationInsert 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.
* More useful things:
** Select nodes by text <source lang = "xml">ExampleTag/li[text()="Submit"]</source>
** Select nodes by text with a type of wildcard <source lang = "xml">ExampleTag[contains(text(), "MFI_")]</source>
** Exclude nodes with not() <source lang = "xml">[not(xxxxx)]</source>
** Can't think of an example but I'm sure someone will find a use for <source lang = "xml">[count(li)]</source>
** Go back to parentnode with <source lang = "xml">..</source>

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

== 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]]
[[Category:Modding tutorials]]

Modding Tutorials/Hello World

2019-08-11T05:33:01Z

Lilwhitemouse: /* But why can't I make my StaticConstructorOnStartup inherit from mod? */ Resent research: two condoms not working is a bit of a myth?

{{BackToTutorials}}

In this tutorial you will learn how to make a mod that runs on startup and writes "Hello World" to the dev console.

=Requirements=
* This tutorial requires you to have [[Modding Tutorials/Setting up a solution|set up a solution]].
* This tutorial requires a Mod folder (here called: MyMod) and the mod folder will need an About folder containing a valid About.xml and an Assemblies folder where we will put our HelloWorld.dll file. For more info, see [[Modding_Tutorials/Mod_folder_structure | Mod folder structure]]

=Bootstrapping=
There are two acceptable ways of making RimWorld load your mod. One is by using the StaticConstructorOnStartup annotation, the other is by inheriting from the Mod class. We will be using the StaticConstructorOnStartup annotation, for reasons explained below.

=Hello World=
<source lang="csharp">
using RimWorld;
using Verse;

namespace TestMod
{
[StaticConstructorOnStartup]
public static class MyMod
{
static MyMod() //our constructor
{
Log.Message("Hello World!"); //Outputs "Hello World!" to the dev console.
}
}
}
</source>
* The [StaticConstructorOnStartup] annotation does what it says on the tin. At startup, it runs the Static Constructor of any class with that annotation. For a thorough explanation of what a static constructor is, refer to [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/static-constructors official C# documentation.] What you need to know: It's a method without a return type, has the same name as the class and doesn't take any arguments.

=Common pitfalls=
* Your constructor isn't static.
* Your constructor isn't a constructor. Refer once more to the [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/static-constructors official C# documentation.]
* There are red squiggles under [StaticConstructorOnStartup] (or anywhere else): you either typo'd, are missing ''using'' statements or don't have a reference to ''Assembly-Csharp.dll''. Read how to [[Modding Tutorials/Setting up a solution|set up a solution]] again.
* You did not compile, and if you did compile, your IDE placed the resulting assembly in some far away folder. Set the output path of your build to something more sane. Read how to [[Modding Tutorials/Setting up a solution|set up a solution]] again.
* There are lot of yellow errors along the line of "x already has short hash": You did not set "Copy local" to false. Read how to [[Modding Tutorials/Setting up a solution|set up a solution]] again.

=StaticConstructorOnStartup vs inheriting from Mod=
Subclasses of the Mod class are loaded extremely early during launch. As such, it is less suitable for most purposes (most notably: using Defs or anything that uses Defs). Classes with the StaticConstructorOnStartup are initialised just before the Main Menu is shown. Classes with this annotation are loaded in the main thread: a requirement for loading any Texture, Material, Shader, Graphic, GameObject or MaterialPropertyBlock.

Inheriting from Mod is necessary if you want [[Modding Tutorials/ModSettings|Mod Settings]], or if you need to run really early in the loading process.

For the exact order of initialisation, look up Verse.PlayDataLoader.DoPlayLoad.

==But why can't I make my StaticConstructorOnStartup inherit from mod?==
That's like wearing two condoms. You might think you're extra safe, in reality it puts you in a worse position. Okay, two condoms might actually be safe enough, but you can't both inherit from the mod and expect the StaticConstructorOnStartup to work.

When C# tries to instantiate a type (like your Mod class) for the very first time, it first runs the static constructor and then an instance constructor. The static constructor in this case is the StaticConstructorOnStartup: meaning it'll try to load your textures outside the main thread and run your Harmony patches using Defs the game doesn't know exist yet. Subsequent new instances of your Mod class will not have their static constructor called again: they run once and only once. Likewise, if the StaticConstructorOnStartup then tries to call the static constructor again, nothing will happen as the static constructor already ran once.

Sometimes you need both a StaticConstructorOnStartup and a class that inherits from Mod. The correct way of doing that is by making two separate classes; one that inherits from Mod and the other with a StaticConstructorOnStartup attribute.

[[Category: Modding]]
[[Category: Modding tutorials]]

Modding Tutorials/Harmony

2019-08-11T05:17:21Z

Lilwhitemouse: /* Bootstrapping */ It's "Startup" not "StartUp" - big difference, very important. Easy to miss.

{{BackToTutorials}}

'''[http://rimworldwiki.com/index.php?title=Modding_Tutorials/Injection&action=edit&redlink=1 Harmony] - A library for patching, replacing and decorating .NET and Mono methods during runtime'''

Harmony is the current best practice for changing the runtime execution of code in RimWorld.

To integrate Harmony into your mod for use, download the latest stable release and add it as a reference to your C# project. Make sure that you also include the dll, (0Harmony.dll) in your mod's assemblies folder. Please DO NOT use HugsLib for an "easy" Harmony implementation due to the fact that HugsLib becomes an unnecessary and unutilized dependency for mods and beginners grow accustomed to using HugsLib in all their mods even if they never touch HugsLib's API in their code. This is a bad practice, especially for beginners new to RimWorld Modding. Please only use HugsLib when you want to utilize some of its features!

Harmony is great for running code patches before (Prefix) or after (Postfix) an existing method. Usually this is all you need for your Mod. Because this does not change existing functionality of RimWorld, it MOST LIKELY does not impact other mods and runs in parallel with other Harmony patches.

''The snippets on this page are not meant as an exhaustive document on all things Harmony. Refer to the original documentation.'' This article is mostly a "this is what you can do" summary in 5 minutes.

==Requirements==
* If you still haven't [[Modding_Tutorials/Setting up a solution|set up a solution]], you're not ready for Harmony.
* You need to be able to write a [[Modding_Tutorials/Hello World|Hello World]] program.
* You don't need to know the inner workings of JIT-compilation, reflection and inlining, but a basic understanding of C# and/or programming in general is assumed in this article.

==Summary==
Harmony can alter the workings of any method. It offers three ways of doing this: prefixes, postfixes, and transpilers.

===Prefix===
A prefix is a method that runs before the original method. It can have a return type of void or bool. If a bool returns false, the original method is skipped. This will cause compatibility issues if you're not very careful. This type of prefix may also prevent other prefixes from running.

===Postfix===
A postfix is a method that runs after the original method. They are guaranteed to run. Postfixes can also alter the result. Use these for greatest compatibility.

===Transpilers===
A transpiler is a set of CodeInstructions. These alter the inner working of the method. They use low-level IL-code, from System.Reflection and System.Reflection.Emit. Refer to MSDN and Harmony documentation for more info. Transpilers are difficult to debug and therefor hard to create/maintain/update.

If you must use a transpiler, you might find useful notes [[Modding_Tutorials/Transpiler Hints|here]].

==Altering the result==
If the original method has a return type, you can alter its ''__result'' by passing it by ''ref''.

==Pitfalls==
===Overuse===
Harmony is a fantastic tool, that you'll soon want to use for everything. Before you do that, consider the alternatives. Can you subclass? Can you use a ThingComp? A MapComponent? There may be viable alternatives without the added dependency.
===Not changing the result?===
Forgot to pass by ref.
===How do I return a value from a void or prefix?===
That's the magic. Harmony disconnects its own return type from the return type of the original method. Consider the following destructive prefix, which gives everyone perfect knowledge of trap locations:
<source lang="csharp">
[HarmonyPatch(typeof(Building_Trap))]
[HarmonyPatch(nameof(Building_Trap.KnowsOfTrap)] //annotation boiler plate to tell Harmony what to patch. Refer to docs.
static class Building_Trap_KnowsOfTrap_Patch
{
static bool Prefix(ref bool __result) //pass the __result by ref to alter it.
{
__result = true; //alter the result.
return false; //return false to skip execution of the original.
}
}
</source>
===Getting the right method to patch===
'''AccessTools''' is a nice wrapper for reflection. The most reliable way of specifying the method to patch is by providing the Patch() method with MethodInfo. Standard System.Reflection also works. You will need to specify arguments for overloaded methods.
===Doesn't seem to get patched?===
Does your Log.Message() not show up? Set HarmonyInstance.DEBUG = true and check the new .txt file Harmony placed on your desktop. If you are trying to patch something that runs during game loading, you [[Modding_Tutorials/Hello_World#StaticConstructorOnStartup_vs_inheriting_from_Mod| may need to bootstrap differently]]. Are you doing everything right? If the method you're patching is small, it may have been [https://en.wikipedia.org/wiki/Inline_expansion inlined.]

==Bootstrapping==
Remember the [[Modding Tutorials/Hello World|Hello World]] tutorial? The [StaticConstructorOnStartup] is a perfect starting point. Create your harmony instance in there, and use it to call PatchAll() or do your manual patching.

== Links ==

[https://github.com/pardeike/Harmony/releases Harmony's Releases] - Link to Harmony's latest release(s) for download.

[https://github.com/pardeike/Harmony/wiki Harmony's Wiki] - General outline of how to use Harmony

[https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL%3A-Harmony RimWorldModGuide on Harmony] - gives some concrete examples and helpful explanations

[https://gist.github.com/pardeike/c02e29f9e030e6a016422ca8a89eefc9 Harmony's Author's Transpiler tutorial] - Tutorial and example of using Harmony Transpiler, with helpful links (inject your code inside a RimWorld class's code - #DeepMagic)

[https://ludeon.com/forums/index.php?topic=29517 Harmony Thread] - Harmony thread on Ludeon Studio's Forum. Announcements of new versions, and the forum in general is a reasonable place to ask questions.

[https://github.com/RimWorld-CCL-Reborn/AlienRaces/blob/master/Source/AlienRace/AlienRace/HarmonyPatches.cs Alien races] - The unofficial Harmony encyclopedia. Dozens, if not hundreds of patches for all your cargo cult programming needs.

Modding Tutorials/Harmony

2019-07-16T03:08:03Z

Lilwhitemouse: /* Doesn't seem to get patched? */ added "to"

{{BackToTutorials}}

'''[http://rimworldwiki.com/index.php?title=Modding_Tutorials/Injection&action=edit&redlink=1 Harmony] - A library for patching, replacing and decorating .NET and Mono methods during runtime'''

Harmony is the current best practice for changing the runtime execution of code in RimWorld.

To integrate Harmony into your mod for use, download the latest stable release and add it as a reference to your C# project. Make sure that you also include the dll, (0Harmony.dll) in your mod's assemblies folder. Please DO NOT use HugsLib for an "easy" Harmony implementation due to the fact that HugsLib becomes an unnecessary and unutilized dependency for mods and beginners grow accustomed to using HugsLib in all their mods even if they never touch HugsLib's API in their code. This is a bad practice, especially for beginners new to RimWorld Modding. Please only use HugsLib when you want to utilize some of its features!

Harmony is great for running code patches before (Prefix) or after (Postfix) an existing method. Usually this is all you need for your Mod. Because this does not change existing functionality of RimWorld, it MOST LIKELY does not impact other mods and runs in parallel with other Harmony patches.

''The snippets on this page are not meant as an exhaustive document on all things Harmony. Refer to the original documentation.'' This article is mostly a "this is what you can do" summary in 5 minutes.

==Requirements==
* If you still haven't [[Modding_Tutorials/Setting up a solution|set up a solution]], you're not ready for Harmony.
* You need to be able to write a [[Modding_Tutorials/Hello World|Hello World]] program.
* You don't need to know the inner workings of JIT-compilation, reflection and inlining, but a basic understanding of C# and/or programming in general is assumed in this article.

==Summary==
Harmony can alter the workings of any method. It offers three ways of doing this: prefixes, postfixes, and transpilers.

===Prefix===
A prefix is a method that runs before the original method. It can have a return type of void or bool. If a bool returns false, the original method is skipped. This will cause compatibility issues if you're not very careful. This type of prefix may also prevent other prefixes from running.

===Postfix===
A postfix is a method that runs after the original method. They are guaranteed to run. Postfixes can also alter the result. Use these for greatest compatibility.

===Transpilers===
A transpiler is a set of CodeInstructions. These alter the inner working of the method. They use low-level IL-code, from System.Reflection and System.Reflection.Emit. Refer to MSDN and Harmony documentation for more info. Transpilers are difficult to debug and therefor hard to create/maintain/update.

If you must use a transpiler, you might find useful notes [[Modding_Tutorials/Transpiler Hints|here]].

==Altering the result==
If the original method has a return type, you can alter its ''__result'' by passing it by ''ref''.

==Pitfalls==
===Overuse===
Harmony is a fantastic tool, that you'll soon want to use for everything. Before you do that, consider the alternatives. Can you subclass? Can you use a ThingComp? A MapComponent? There may be viable alternatives without the added dependency.
===Not changing the result?===
Forgot to pass by ref.
===How do I return a value from a void or prefix?===
That's the magic. Harmony disconnects its own return type from the return type of the original method. Consider the following destructive prefix, which gives everyone perfect knowledge of trap locations:
<source lang="csharp">
[HarmonyPatch(typeof(Building_Trap))]
[HarmonyPatch(nameof(Building_Trap.KnowsOfTrap)] //annotation boiler plate to tell Harmony what to patch. Refer to docs.
static class Building_Trap_KnowsOfTrap_Patch
{
static bool Prefix(ref bool __result) //pass the __result by ref to alter it.
{
__result = true; //alter the result.
return false; //return false to skip execution of the original.
}
}
</source>
===Getting the right method to patch===
'''AccessTools''' is a nice wrapper for reflection. The most reliable way of specifying the method to patch is by providing the Patch() method with MethodInfo. Standard System.Reflection also works. You will need to specify arguments for overloaded methods.
===Doesn't seem to get patched?===
Does your Log.Message() not show up? Set HarmonyInstance.DEBUG = true and check the new .txt file Harmony placed on your desktop. If you are trying to patch something that runs during game loading, you [[Modding_Tutorials/Hello_World#StaticConstructorOnStartup_vs_inheriting_from_Mod| may need to bootstrap differently]]. Are you doing everything right? If the method you're patching is small, it may have been [https://en.wikipedia.org/wiki/Inline_expansion inlined.]

==Bootstrapping==
Remember the [[Modding Tutorials/Hello World|Hello World]] tutorial? The [StaticConstructorOnStartUp] is a perfect starting point. Create your harmony instance in there, and use it to call PatchAll() or do your manual patching.

== Links ==

[https://github.com/pardeike/Harmony/releases Harmony's Releases] - Link to Harmony's latest release(s) for download.

[https://github.com/pardeike/Harmony/wiki Harmony's Wiki] - General outline of how to use Harmony

[https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL%3A-Harmony RimWorldModGuide on Harmony] - gives some concrete examples and helpful explanations

[https://gist.github.com/pardeike/c02e29f9e030e6a016422ca8a89eefc9 Harmony's Author's Transpiler tutorial] - Tutorial and example of using Harmony Transpiler, with helpful links (inject your code inside a RimWorld class's code - #DeepMagic)

[https://ludeon.com/forums/index.php?topic=29517 Harmony Thread] - Harmony thread on Ludeon Studio's Forum. Announcements of new versions, and the forum in general is a reasonable place to ask questions.

[https://github.com/RimWorld-CCL-Reborn/AlienRaces/blob/master/Source/AlienRace/AlienRace/HarmonyPatches.cs Alien races] - The unofficial Harmony encyclopedia. Dozens, if not hundreds of patches for all your cargo cult programming needs.

Topic:V2wkppkulu3vltal

2019-07-08T15:27:31Z

Lilwhitemouse (talk | contribs) commented on "Logging hint" (As some ppl say here in the south, harmony.what now? I'm not familiar with what harmony.DEBUG does is the advantage - there's no document...)

Modding Tutorials/Linking XML and C

2019-07-03T05:30:04Z

Lilwhitemouse: /* DefDatabase */

{{BackToTutorials}}

[[Modding Tutorials/Writing custom code|Writing custom code]] is all well and good if you can't force RimWorld to use it! Here are three ways of linking your Code to the XML and vice versa.

=Using your C# from XML=
==A classy design pattern==
RimWorld leans heavily on Object Oriented Programming and will often expose the specific class of a Def to the XML. They're often called a workerClass, thingClass, but obviously can be named anything. Keep a look out for these, they're sometimes subtle.

===Examples===
<source lang ="xml">
<BiomeDef>
<defName>BorealForest</defName>
<workerClass>BiomeWorker_BorealForest</workerClass>
</BiomeDef>
</source>

<source lang ="xml">
<inspectorTabs>
<li>ITab_Art</li>
</inspectorTabs>
</source>

==A "Classy" pattern==
It is possible to overwrite the default class associated with a Def (or field in a def) by specifying the Class by attribute. The most common usage of this you've undoubtedly seen before is in Components: <source lang = "xml">
<comps>
<li Class="CompProperties_Forbiddable"/>
</comps>
</source>

This class override is more widely applicable than just [[Modding Tutorials/Custom Comp Classes|comps]]. It's possible to overwrite or specify almost any type you wish. Keep [[Modding Tutorials/Compatibility|Compatibility]] in mind when doing this: in the end each object can only be one [[Modding Tutorials/Def classes|Class]].

===Example===
<source lang ="xml">

<GenStepDef Class = "MyNameSpace.MyCustomGenStepDefClass"> 
<defName>Settlement</defName>
<order>400</order>
<genStep Class="GenStep_Settlement"> 
<count>1</count>
<nearMapCenter>true</nearMapCenter>
</genStep>
<modExtensions>
<li Class="MyNameSpace.MyCustomModExtension"> 
<isACustomGenStepDefClassAndAModExtensionOverkill>false</isACustomGenStepDefClassAndAModExtensionOverkill>
</li>
</modExtensions>
</GenStepDef>
</source>

==You define yourself==
Another possibility is to supply your own type in the XML. The most well-known example of this is [https://github.com/RimWorld-CCL-Reborn/AlienRaces/wiki/Let%27s-Start Alienraces]. The [https://github.com/RimWorld-CCL-Reborn/AlienRaces/blob/master/Source/AlienRace/AlienRace/ThingDef_AlienRace.cs ThingDef_AlienRace] inherits from regular [[Modding Tutorials/ThingDef|ThingDef]], and adds the alienRace tag to it. The alienRace tag then holds more information, a sample of which is shown below.

One benefit of this over the annotation method above (the "Classy" pattern) is that the added control and restriction of scope is increased compatibility with over mods. It's theoretically also easier to further subclass the AlienRace def by annotation.

===Example===
<source lang = "xml">
<AlienRace.ThingDef_AlienRace ParentName="BasePawn">
<defName>ExampleAlien</defName>
<label>Alien for example</label>
<description>This alien is really special.. because it is used as an example</description>

<alienRace>

<generalSettings>

</generalSettings>
<raceRestriction>

</raceRestriction>
</alienRace>
</AlienRace.ThingDef_AlienRace>
</source>

==Serialising custom classes==
It may sometimes be required to read/write your own datatype to XML. While we all love long strings with comma separated values, there are many cases where this is not a good idea. For that, RimWorld offers a ''LoadDataFromXmlCustom'' method. When RimWorld comes across your type during load, and the class defining that type contains the ''LoadDataFromXmlCustom'', RimWorld will use that method to parse the XML. This is done through the magic of reflection.

Note that this method fails on types that can't have a constructor. In practice, this means you can't serialise [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/structs structs].

<source lang = "csharp">
//example taken from https://github.com/LocoNeko/RoadsOfTheRim/blob/master/Source/DefModExtension_RotR_RoadDef.cs
public class RotR_cost
{
public string name;
public int count;

public void LoadDataFromXmlCustom(XmlNode xmlRoot)
{
if (xmlRoot.ChildNodes.Count != 1)
{
Log.Error("Misconfigured RotR_cost: " + xmlRoot.OuterXml, false);
return;
}
name = xmlRoot.Name;
count = (int)ParseHelper.FromString(xmlRoot.FirstChild.Value, typeof(int));
}
}
</source>

==Common issues==
You need to specify your exact Namespace.Class. There are no two ways around it. You also need to supply RimWorld with the assembly containing the type and namespace specified.

=Using your XML from C#=
There are times you'll need to use a Def or other value defined in XML.

==DefOf==
Any class with the [DefOf] annotation will automatically have its fields filled with their corresponding Def. You can then access it in other code like you'd access any DefOf, like ThingDefOf. The below example would be used as ''SomeDef def = MyDefOf.JustOneExampleDefName;''.

'''Advantages''':
* It's run-time fast.
* It's easy.
* It moves errors to startup, rather than at runtime. Early warnings save considerable testing and debugging!
** If there's an error in your code (like a typo in the defName, or a missing Def), it will detect that as soon as the game starts, rather than when it's trying to use it.

'''Disadvantages''':
* DefOfs don't get their fields filled until after the game is done loading Defs.
** This means using a DefOf before it is properly initialised gets you ''null'' - which the DefOf class is supposed to prevent.
* Has a negative influence on startup times. <ref>It uses reflection to find and fill the fields. This probably isn't the quickest, but the extent of it hasn't been measured.</ref>

<source lang = "csharp">
[DefOf]
public static class MyDefOf
{
public static SomeDef JustOneExampleDefName;
public static SomeDef AnotherExampleDefName;
public static SomeDef YetMoreExampleDefName;

static MyDefOf()
{
DefOfHelper.EnsureInitializedInCtor(typeof(MyDefOf));
}
}
</source>
The fields have to be static and public.

===That weird constructor===
It's there for your own good. If you're trying to use a Def before RimWorld had a chance to fill the field with a proper reference, it will return null. You don't want that. This constructor warns against that.

==DefDatabase==
If you only need to use a certain Def occasionally, you can look it up in the DefDatabase directly.
<source lang = "csharp">SomeDef def = DefDatabase<SomeDef>.GetNamed("JustOneExampleDefName");</source>

'''Advantages''':
* Is allowed to return null (silent failure is an option).
* Does not require an entire class.
* Is open to string based shenanigans.

'''Disadvantages''':
* Is allowed to return null. If you're not prepared for it to return null, Bad Things Happen.
* Slower than a DefOf. (Altho if you put the def in a static variable, this is somewhat negated)
* Prone to typos.

=See also=
[[Modding Tutorials/Hello World|Hello World]] - For when your code shouldn't be linked to XML, but does need to be bootstrapped.

[[Category: Modding tutorials]]

Modding Tutorials/Transpiler Hints

2019-06-30T18:02:46Z

Lilwhitemouse: link

Debugging Transpilers can seem impossible. It's very difficult to count exactly correctly, and any mistakes will likely throw a system exception.

==Helpful examples==
One way to get an idea of how to use the Transpiler is to [https://github.com/search?o=desc&q=Rimworld+Harmony+Transpiler&s=indexed&type=Code search github for Harmony Transpilers].

==Useful debugging tools.==

===See what your IL code is===
One thing that can potentially help is to print out your entire modified IL code, to make sure you've got it correct:

<code>
public static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions, ILGenerator generator) {
var l=XTranspiler(instructions, generator).ToList(); // name your actual transpiler XTranspiler
string s="Code:";
int i=0;
foreach (var c in l) {
if (c.opcode==OpCodes.Call ||
c.opcode==OpCodes.Callvirt) { // you can make certain operations more visible
Log.Warning(""+i+": "+c);
} else {
Log.Message(""+i+": "+c);
}
s+="\n"+i+": "+c;
i++;
yield return c;
}
Log.Error(s); // or just print the entire thing out to copy to a text editor.
}
</code>

Modding Tutorials/Transpiler Hints

2019-06-30T17:58:42Z

Lilwhitemouse: Useful tool in some certain circumstances ><

Debugging Transpilers can seem impossible. It's very difficult to count exactly correctly, and any mistakes will likely throw a system exception.

==Helpful examples==
One way to get an idea of how to use the Transpiler is to search github for Harmony Transpilers.

==Useful debugging tools.==

===See what your IL code is===
One thing that can potentially help is to print out your entire modified IL code, to make sure you've got it correct:

<code>
public static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions, ILGenerator generator) {
var l=XTranspiler(instructions, generator).ToList(); // name your actual transpiler XTranspiler
string s="Code:";
int i=0;
foreach (var c in l) {
if (c.opcode==OpCodes.Call ||
c.opcode==OpCodes.Callvirt) { // you can make certain operations more visible
Log.Warning(""+i+": "+c);
} else {
Log.Message(""+i+": "+c);
}
s+="\n"+i+": "+c;
i++;
yield return c;
}
Log.Error(s); // or just print the entire thing out to copy to a text editor.
}
</code>

Modding Tutorials/Harmony

2019-06-30T17:57:08Z

Lilwhitemouse: /* Transpilers */

{{BackToTutorials}}

'''[http://rimworldwiki.com/index.php?title=Modding_Tutorials/Injection&action=edit&redlink=1 Harmony] - A library for patching, replacing and decorating .NET and Mono methods during runtime'''

Harmony is the current best practice for changing the runtime execution of code in RimWorld.

To integrate Harmony into your mod for use, download the latest stable release and add it as a reference to your C# project. Make sure that you also include the dll, (0Harmony.dll) in your mod's assemblies folder. Please DO NOT use HugsLib for an "easy" Harmony implementation due to the fact that HugsLib becomes an unnecessary and unutilized dependency for mods and beginners grow accustomed to using HugsLib in all their mods even if they never touch HugsLib's API in their code. This is a bad practice, especially for beginners new to RimWorld Modding. Please only use HugsLib when you want to utilize some of its features!

Harmony is great for running code patches before (Prefix) or after (Postfix) an existing method. Usually this is all you need for your Mod. Because this does not change existing functionality of RimWorld, it MOST LIKELY does not impact other mods and runs in parallel with other Harmony patches.

''The snippets on this page are not meant as an exhaustive document on all things Harmony. Refer to the original documentation.'' This article is mostly a "this is what you can do" summary in 5 minutes.

==Requirements==
* If you still haven't [[Modding_Tutorials/Setting up a solution|set up a solution]], you're not ready for Harmony.
* You need to be able to write a [[Modding_Tutorials/Hello World|Hello World]] program.
* You don't need to know the inner workings of JIT-compilation, reflection and inlining, but a basic understanding of C# and/or programming in general is assumed in this article.

==Summary==
Harmony can alter the workings of any method. It offers three ways of doing this: prefixes, postfixes, and transpilers.

===Prefix===
A prefix is a method that runs before the original method. It can have a return type of void or bool. If a bool returns false, the original method is skipped. This will cause compatibility issues if you're not very careful. This type of prefix may also prevent other prefixes from running.

===Postfix===
A postfix is a method that runs after the original method. They are guaranteed to run. Postfixes can also alter the result. Use these for greatest compatibility.

===Transpilers===
A transpiler is a set of CodeInstructions. These alter the inner working of the method. They use low-level IL-code, from System.Reflection and System.Reflection.Emit. Refer to MSDN and Harmony documentation for more info. Transpilers are difficult to debug and therefor hard to create/maintain/update.

If you must use a transpiler, you might find useful notes [[Modding_Tutorials/Transpiler Hints|here]].

==Altering the result==
If the original method has a return type, you can alter its ''__result'' by passing it by ''ref''.

==Pitfalls==
===Overuse===
Harmony is a fantastic tool, that you'll soon want to use for everything. Before you do that, consider the alternatives. Can you subclass? Can you use a ThingComp? A MapComponent? There may be viable alternatives without the added dependency.
===Not changing the result?===
Forgot to pass by ref.
===How do I return a value from a void or prefix?===
That's the magic. Harmony disconnects its own return type from the return type of the original method. Consider the following destructive prefix, which gives everyone perfect knowledge of trap locations:
<source lang="csharp">
[HarmonyPatch(typeof(Building_Trap))]
[HarmonyPatch(nameof(Building_Trap.KnowsOfTrap)] //annotation boiler plate to tell Harmony what to patch. Refer to docs.
static class Building_Trap_KnowsOfTrap_Patch
{
static bool Prefix(ref bool __result) //pass the __result by ref to alter it.
{
__result = true; //alter the result.
return false; //return false to skip execution of the original.
}
}
</source>
===Getting the right method to patch===
'''AccessTools''' is a nice wrapper for reflection. The most reliable way of specifying the method to patch is by providing the Patch() method with MethodInfo. Standard System.Reflection also works. You will need to specify arguments for overloaded methods.
===Doesn't seem to get patched?===
Does your Log.Message() not show up? Set HarmonyInstance.DEBUG = true and check the new .txt file Harmony placed on your desktop. If you are trying to patch something that runs during game loading, you [[Modding_Tutorials/Hello_World#StaticConstructorOnStartup_vs_inheriting_from_Mod| may need bootstrap differently]]. Are you doing everything right? If the method you're patching is small, it may have been [https://en.wikipedia.org/wiki/Inline_expansion inlined.]

==Bootstrapping==
Remember the [[Modding Tutorials/Hello World|Hello World]] tutorial? The [StaticConstructorOnStartUp] is a perfect starting point. Create your harmony instance in there, and use it to call PatchAll() or do your manual patching.

== Links ==

[https://github.com/pardeike/Harmony/releases Harmony's Releases] - Link to Harmony's latest release(s) for download.

[https://github.com/pardeike/Harmony/wiki Harmony's Wiki] - General outline of how to use Harmony

[https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL%3A-Harmony RimWorldModGuide on Harmony] - gives some concrete examples and helpful explanations

[https://gist.github.com/pardeike/c02e29f9e030e6a016422ca8a89eefc9 Harmony's Author's Transpiler tutorial] - Tutorial and example of using Harmony Transpiler, with helpful links (inject your code inside a RimWorld class's code - #DeepMagic)

[https://ludeon.com/forums/index.php?topic=29517 Harmony Thread] - Harmony thread on Ludeon Studio's Forum. Announcements of new versions, and the forum in general is a reasonable place to ask questions.

[https://github.com/RimWorld-CCL-Reborn/AlienRaces/blob/master/Source/AlienRace/AlienRace/HarmonyPatches.cs Alien races] - The unofficial Harmony encyclopedia. Dozens, if not hundreds of patches for all your cargo cult programming needs.

Modding

2019-02-17T15:06:30Z

Lilwhitemouse: /* I want my mod to...: */ save data, as per https://ludeon.com/forums/index.php?topic=48046.0

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods. RimWorld mods may make use of XML and C#.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [https://ludeon.com/forums/index.php?board=14.0 the forums help section on modding] to check if the information you're looking for has been asked previously, before starting your own thread.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
RimWorld does not limit what you can or can't do. The only limit is skills and motivation, or patience and willpower. You can mod everything, from defs, to code, images, and sounds. Some examples:

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. There is no API for RimWorld modding, you can make full use of RimWorld's functions. You also have the full power of the .NET Framework 3.5 available. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Patches''': Using xpath, you can edit Defs with pinpoint precision to change only the values you need to change while staying as compatible as possible with other mods.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils
** Higher level, explanation on how pawns think: https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL%3A-How-Pawns-Think

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''Defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''Sound'''
* '''Research'''
* '''Biomes'''
* '''Much much more'''

When the game runs, it collects all the definitions into a database. It then draws from these pools in when appropriate. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game with Defs means adding your definitions to these pools and watching the game use them.

A mod could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several Defs of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. Most players often have several mods active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</Defs>
</source>
All rootnodes for Defs start with '''<Defs>'''. Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure. Root folders have to follow the naming pattern (About, Assemblies, Defs, Sounds, Patches, Textures, Languages) for them to be read by RimWorld. Apart from the Languages Folder, subfolders can have any structure. For the sake of organisation, it is recommended to keep things categorised:
<pre>
┌About (Your mod MUST have an About folder containing an About.xml file. Case sensitive)
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│
├┬Sounds (Put any sound files here. Universally supported formats are .ogg and .wav. .mp3 files are not guaranteed to work)
├─MySound.wav
|
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─MyPatch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected (NOTE: the folder (and subfolder) names must be specific here, and follow the XML structure of the mod)
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image size to 1 MB.

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_Multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_east (for both east- and west-facing), Texturename_south (front-facing), and Texturename_north (back-facing).
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_Multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_east
├╴RoyalCouch_south
└╴RoyalCouch_north
</pre>

For plant textures that have multiple growth stages and/or utilize the Graphic_Random class, the different images for each stage must be in separate folders. These images within must also share the same filenames. For example, the [[corn plant]] has one immature form, and two different mature forms that appear at random once the plant is fully grown. Similarly to Graphic_Multi, when using the Graphic_Random class, you will always want to reference the folder containing the images rather than the images themselves. It should be noted that only harvestable plants are able to display an immature image.

An example of how retexturing a plant could work:

<source lang="xml" >
<graphicPath>Things/Plants/CornPlant</graphicPath>
<graphicClass>Graphic_Random</graphicClass>
</source>

Your folder structure:
<pre>
┌Textures
└┬Things
└┬Plants
└┬CornPlant
├╴CornPlant_A
└╴CornPlant_B
└┬CornPlant_Immature
├╴CornPlant_A
└╴CornPlant_B
</pre>

Even though there is only one image used for the immature corn plant, we must have two copies of it with the same filenames as the mature plant images in order to prevent broken textures in-game.
If you wanted to add a leafless variant to a plant (such as the leafless trees in winter), another folder would be added.

<pre>
┌Textures
└┬Things
└┬Plants
└┬CornPlant
├╴CornPlant_A
└╴CornPlant_B
└┬CornPlant_Immature
├╴CornPlant_A
└╴CornPlant_B
└┬CornPlant_Leafless
├╴CornPlant_A
└╴CornPlant_B
</pre>

===Interactive "Things"===
A Thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed. Note that new workbenches also need a WorkGiver tied to them, otherwise pawns will ignore your new bench.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_MiniTurret</turretGunDef>
<turretBurstCooldownTime>4.8</turretBurstCooldownTime>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==I want to make a mod that can...:==
'''Or, how do I make my mod do ''this''?'''

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

* Save/Load information. See a very useful guide at [https://spdskatr.github.io/RWModdingResources/saving-guide this page]
** For saving settings for your mod, either use a class that extends ModSettings or use HugsLib.
** For saving per-world data, make a [[Modding_Tutorials/GameComponent|Game Component]] and override ExposeData
* Add a new value to a def
** See [[Modding_Tutorials/ThingComp|ThingComp]]
** Also helpful: [[Modding Tutorials/DefModExtension|DefModExtension]]s

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://spdskatr.github.io/RWModdingResources/ A good collection of guides for RimWorld modders]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding Tutorials/Linking XML and C

2019-02-11T16:46:41Z

Lilwhitemouse: /* Examples */

Modding Tutorials/PatchOperations

2019-02-04T18:01:56Z

Lilwhitemouse: /* PatchOperationSequence */

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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.

Modders will often specify <code><success>Always</success></code>, which will mean that even if one part of the sequence fails (e.g., a test), the whole is still considered a success and no unneeded errors show up.

'''Patch Operation'''
<source lang="xml">
<Operation Class="PatchOperationSequence">

<operations>
<li Class="PatchOperationInsert">
<xpath>/Defs/ExampleDef[defName="Example"]/exampleNode</xpath>
<value>
<anotherExample>A new sibling</anotherExample>
</value>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs/ExampleDef[defName="Example"]</xpath>
<value><label>I'm a node</label></value>
<li>

<operations>
</Operation>
</source>

'''Effect'''
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
! Def before patch !! 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">
<Defs>
<ExampleDef>
<label>I'm a node</label>
<defName>Example</defName>
<exampleNode>Some text</exampleNode>
<anotherExample>A new sibling</anotherExample>
<exampleList />
</ExampleDef>
</Defs>
</source>
|-
|}

'''Another Example''': Maybe you don't like the "Example" ExampleDef...
<source lang="xml">
<Operation Class="PatchOperationSequence">
<success>Always</success>
<operations>
<li Class="PatchOperationRemove">
<xpath>/Defs/ExampleDef[defName="Example"]<xpath>
</li>
<li Class="PatchOperationAdd">
<xpath>/Defs</xpath>
<value>
<ExampleDef><defName>MyBetterExample</defName></ExampleDef>
</value>
</operations>
</Operation>
</source>

If ExampleDef were already gone, MyBetterExample would not get added.

===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">

<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">


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

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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.
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]

== 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]]

Modding Tutorials/PatchOperations

2019-02-04T17:38:57Z

Lilwhitemouse: /* PatchOperationInsert */ Reduced number of spaces to try and make it fit better on some screens.

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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">

<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">


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

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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.
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]

== 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]]

Modding Tutorials/PatchOperations

2019-02-04T17:32:33Z

Lilwhitemouse: Added another leading / - keeps xpath from looking for "Defs" in subnodes ><

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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">

<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">


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

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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.
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]

== 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]]

Modding Tutorials/PatchOperations

2019-02-04T17:31:28Z

Lilwhitemouse: Added "Success" options

{{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.

=="Success" option==
The ''<code><success>...</success></code>'' term specifies whether the entire operation is considered a success or not. If the overall patch operation is not considered a success, an error is thrown. This is particularly used in Sequences and Tests.

Options available are:
* Always - this patch operation is considered a success - sometimes used for Sequences so that if an early test in the sequence fails, an error is not reported (because the sequence is still a successful patch)
* Normal - this patch operation is considered a success if it succeeded (content patched, test passed, etc)
* Invert - If the patch failed (e.g., a test), then it's considered a success (useful for a negative test in a sequence)
* Never - this patch operation "failed." Even if it patched whatever it was supposed to correctly. If you ever use this, leave a note here for the curious.

==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">

<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">


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

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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.
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]

== 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]]

Modding Tutorials/PatchOperations

2019-02-04T17:12:31Z

Lilwhitemouse: /* XPath syntax */ put leading / in front of Defs,which is fastest; note on final /

{{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">

<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">


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

<li Class="PatchOperationFindMod">
<mods>
<li>VGP Xtra Trees and Flowers</li>
</mods>
<match Class="PatchOperationSequence">
<success>Always</success>
<operations>

<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.
- [https://github.com/NoImageAvailable/CombatExtended/blob/88ef1f86d30e6c285e3370bd9faafa92c84195b0/Source/CombatExtended/CombatExtended/PatchOperationMakeGunCECompatible.cs Example PatchOperationMakeGunCECompatible]
- [https://gist.github.com/Lanilor/e326e33e268e78f68a2f5cd3cdbbe8c0 Example PatchOperationAddOrReplace]

== 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]]

Topic:Utertmmn0n8ctg25

2019-02-02T19:43:01Z

Lilwhitemouse (talk | contribs) commented on "You took out Default Comp Class?" (I was talking about the Initialize check (https://rimworldwiki.com/index.php?title=Modding_Tutorials/Custom_Comp_Classes&oldid=62377 - ve...)

Topic:Uteryyravthkibgt

2019-02-02T19:37:02Z

Lilwhitemouse (talk | contribs) commented on "Removed example?" (I think a more complicated example is actually fairly useful. I see what you mean by the potentially unsafe casting - I wrote the example...)

Topic:Uteryyravthkibgt

2019-02-01T21:39:56Z

Lilwhitemouse (talk | contribs) commented on "Removed example?" (Any particular reason you removed the examples of how to access parts of the comp properties? I know those would have been very useful to...)

Topic:Utertmmn0n8ctg25

2019-02-01T21:37:16Z

Lilwhitemouse (talk | contribs) commented on "You took out Default Comp Class?" (@Mehni, I noticed you took out the workaround for having a default CompClass for objects. Why? It's entirely possible to create objects t...)

Modding Tutorials/Custom Comp Classes

2019-01-06T03:50:06Z

Lilwhitemouse: More complicated example...

Creating a custom comp class is a convenient way to add new functionality to RimWorld.

== Prerequisites ==
* You need to have [[Modding Tutorials/Setting up a solution|set up your editor and environment]]
* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]]
* You should probably understand Defs at least somewhat.

== def (xml) and C# structure ==

=== Setup, Defs, and Classes ===
You will have some custom def and it will have something like this:
==== Defs (xml) ====
<ThingDef ...>
...
...
<comps>
<<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties">
<myCustomCompProperty>some value</myCustomCompProperty>
<mySecondCompProp>4</mySecondCompProp>
</<nowiki>li</nowiki>>
<<nowiki>li</nowiki>>
''<<nowiki>!--</nowiki> this is kind of like <tag>MN.MyCustomTag</tag>:-->''
<compClass>MyNamespace.MyCustomThingComp</compClass>
</<nowiki>li</nowiki>>
</comps>
</ThingDef>
==== C# ====
namespace MyNamespace ''// For example, LWM.ModName - by using your ''
''// handle/name/etc, you almost certainly guarantee uniqueness''
{
'''//////////// <<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties"> ////////////'''
public class MyCompProperties : CompProperties ''// Name this as you wish, of course''
{
public Properties() {
this.compClass = typeof(MyNamespace.MyLinkedCompThing); ''// rename as appropriate''
}
public string myCustomCompProperty; ''// Name matches def, of course''
public int mySecondCompProp = 1; ''// Can set default values''
}

''// this ThingComp is used to actually access the comp property defined above''
'''''// this is not "<compClass>MyNamespace.MyCustomThingComp</compClass>"'''''
public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty
{
get
{
return ((MyCompProperties)this.props).myCustomCompProperty;
}
}
public int mySecondCompProperty ''// Have to get all the names right''
{ get { return ((MyCompProperties)this.props).mySecondCompProperty; } } ''//etc''
}
'''//////////// <compClass>MyNamespace.MyCustomThingComp</compClass> ////////////'''
public class MyCustomThingComp : ThingComp
{
public override void CompTick()
{
// do stuff
}
public override void CompTickRare() //etc
public override ... // Check out Verse/ThingComp.cs for more ideas
}
} // end MyNamespace

=== Accessing your Comps ===
Just setting up your custom comps doesn't do you a lot of good if you can't access them!

==== Accessing CompProperty directly ====
This is the "hard" way, but doable if you want:
<source lang="C#">
int importantProperty = ((MyCompProperties)((ThingWithComps)myObject)
.GetComp<MyLinkedCompThing>().props).mySecondCompProp;
// The "(ThingWithComps)" cast may or may not be needed
</source>

==== Use the "get" method we created ====
Easier approach:
<source lang="C#">
// real world example:
SlotGroup slotGroup = GetSlotGroupInEarlierCode();
MyLinkedCompThing comp = ((ThingWithComps)slotGroup.parent).GetComp<MyLinkedCompThing>();
if (comp != null) {
string s = comp.myCustomCompProperty;
int x = otherObject.GetComp<MyLinkedCompThing>().mySecondCompProp; // be sure it exists, etc
} else { /* not a thing with my comp, etc */ }
</source>

=== More Complicated ===
You can do a lot of complicated things...
<source lang="xml">
<comps>
<li Class="MyNS.Properties>
<myThingFilters>
<li>
<filter>
<categories>
<li>Apparel</li>
</categories>
</filter>
</li>
<li>
<filter>
<categories>
<li>Drugs</li>
</categories>
<thingDefs>
<li>ChunkSlagSteel</li>
</thingDefs>
</filter>
</li>
</myThingFilters>
</li>
</comps>
</source>

And then

<source lang="C#">
namespace MyNS {
public class Properties : CompProperties {
public Properties() { this.compClass=typeof(ComplicatedComp); }
public List<ThingFilter> myThingFilters = new List<ThingFilter>;
}
public class ComplicatedComp : ThingComp {
// set up getter as before:
public List<ThingFilter> myThingFilters { get { return ((Properties)this.props).myThingFilters;

public class MyWeirdCode {
// etc
List<ThingFilter> listOfThingFilters = (ThingWithComps)thing.GetComp<ComplicatedComp>().myThingFilters;
// why you would want a list of thing filters is beyond me?
// what could you even do with it?
// but you can have it.
}
</source>

=== Cautions, traps, etc ===
If you have the same comp in an abstract (XML) def and attempt to redefine it in a (XML) child def, it will get counted twice. It's possible to get around this in the code, if you want to have default comps:

<ThingDef Name=ParentWithDefault ... Abstract=true>
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>3</myValue>
</l<nowiki>i</nowiki>>
</comps>
</ThingDef>
<ThingDef ParentName="ParentWihtDefault">
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>5</myValue>
</<nowiki>l</nowiki>i>
</comps>
</ThingDef>

public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty //etc

public override void Initialize (CompProperties props) {
base.Initialize(props);
// Remove duplicate entries and ensure the last entry is the only one left
// This allows a default abstract def with the comp
// and child def to change the comp value:
MyCompProprtiesWithDefault[] list = this.parent.GetComps<MyCompPropertiesWithDefault>().ToArray();
// Remove everything but the last entry; harmless if only one entry:
for (var i = 0; i < list.Length-1; i++)
{
this.parent.AllComps.Remove(list[i]);
}
}

///etc
}

[[Category:Modding tutorials]][[Category:Modding]][[Category:Defs]]

Modding Tutorials/Custom Comp Classes

2019-01-06T03:36:00Z

Lilwhitemouse: /* Accessing your Comps */ Stupid formatting with no documentation :p

Creating a custom comp class is a convenient way to add new functionality to RimWorld.

== Prerequisites ==
* You need to have [[Modding Tutorials/Setting up a solution|set up your editor and environment]]
* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]]
* You should probably understand Defs at least somewhat.

== def (xml) and C# structure ==

=== Setup, Defs, and Classes ===
You will have some custom def and it will have something like this:
==== Defs (xml) ====
<ThingDef ...>
...
...
<comps>
<<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties">
<myCustomCompProperty>some value</myCustomCompProperty>
<mySecondCompProp>4</mySecondCompProp>
</<nowiki>li</nowiki>>
<<nowiki>li</nowiki>>
''<<nowiki>!--</nowiki> this is kind of like <tag>MN.MyCustomTag</tag>:-->''
<compClass>MyNamespace.MyCustomThingComp</compClass>
</<nowiki>li</nowiki>>
</comps>
</ThingDef>
==== C# ====
namespace MyNamespace ''// For example, LWM.ModName - by using your ''
''// handle/name/etc, you almost certainly guarantee uniqueness''
{
'''//////////// <<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties"> ////////////'''
public class MyCompProperties : CompProperties ''// Name this as you wish, of course''
{
public Properties() {
this.compClass = typeof(MyNamespace.MyLinkedCompThing); ''// rename as appropriate''
}
public string myCustomCompProperty; ''// Name matches def, of course''
public int mySecondCompProp = 1; ''// Can set default values''
}

''// this ThingComp is used to actually access the comp property defined above''
'''''// this is not "<compClass>MyNamespace.MyCustomThingComp</compClass>"'''''
public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty
{
get
{
return ((MyCompProperties)this.props).myCustomCompProperty;
}
}
public int mySecondCompProperty ''// Have to get all the names right''
{ get { return ((MyCompProperties)this.props).mySecondCompProperty; } } ''//etc''
}
'''//////////// <compClass>MyNamespace.MyCustomThingComp</compClass> ////////////'''
public class MyCustomThingComp : ThingComp
{
public override void CompTick()
{
// do stuff
}
public override void CompTickRare() //etc
public override ... // Check out Verse/ThingComp.cs for more ideas
}
} // end MyNamespace

=== Accessing your Comps ===
Just setting up your custom comps doesn't do you a lot of good if you can't access them!

==== Accessing CompProperty directly ====
This is the "hard" way, but doable if you want:
<source lang="C#">
int importantProperty = ((MyCompProperties)((ThingWithComps)myObject)
.GetComp<MyLinkedCompThing>().props).mySecondCompProp;
// The "(ThingWithComps)" cast may or may not be needed
</source>

==== Use the "get" method we created ====
<source lang="C#">
// real world example:
SlotGroup slotGroup = GetSlotGroupInEarlierCode();
MyLinkedCompThing comp = ((ThingWithComps)slotGroup.parent).GetComp<MyLinkedCompThing>();
if (comp != null) {
string s = comp.myCustomCompProperty;
int x = otherObject.GetComp<MyLinkedCompThing>().mySecondCompProp; // be sure it exists, etc
} else { /* not a thing with my comp, etc */ }
</source>

=== Cautions, traps, etc ===
If you have the same comp in an abstract (XML) def and attempt to redefine it in a (XML) child def, it will get counted twice. It's possible to get around this in the code, if you want to have default comps:

<ThingDef Name=ParentWithDefault ... Abstract=true>
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>3</myValue>
</l<nowiki>i</nowiki>>
</comps>
</ThingDef>
<ThingDef ParentName="ParentWihtDefault">
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>5</myValue>
</<nowiki>l</nowiki>i>
</comps>
</ThingDef>

public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty //etc

public override void Initialize (CompProperties props) {
base.Initialize(props);
// Remove duplicate entries and ensure the last entry is the only one left
// This allows a default abstract def with the comp
// and child def to change the comp value:
MyCompProprtiesWithDefault[] list = this.parent.GetComps<MyCompPropertiesWithDefault>().ToArray();
// Remove everything but the last entry; harmless if only one entry:
for (var i = 0; i < list.Length-1; i++)
{
this.parent.AllComps.Remove(list[i]);
}
}

///etc
}

[[Category:Modding tutorials]][[Category:Modding]][[Category:Defs]]

Modding Tutorials/Custom Comp Classes

2019-01-06T03:34:41Z

Lilwhitemouse: /* Accessing your Comps */

Creating a custom comp class is a convenient way to add new functionality to RimWorld.

== Prerequisites ==
* You need to have [[Modding Tutorials/Setting up a solution|set up your editor and environment]]
* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]]
* You should probably understand Defs at least somewhat.

== def (xml) and C# structure ==

=== Setup, Defs, and Classes ===
You will have some custom def and it will have something like this:
==== Defs (xml) ====
<ThingDef ...>
...
...
<comps>
<<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties">
<myCustomCompProperty>some value</myCustomCompProperty>
<mySecondCompProp>4</mySecondCompProp>
</<nowiki>li</nowiki>>
<<nowiki>li</nowiki>>
''<<nowiki>!--</nowiki> this is kind of like <tag>MN.MyCustomTag</tag>:-->''
<compClass>MyNamespace.MyCustomThingComp</compClass>
</<nowiki>li</nowiki>>
</comps>
</ThingDef>
==== C# ====
namespace MyNamespace ''// For example, LWM.ModName - by using your ''
''// handle/name/etc, you almost certainly guarantee uniqueness''
{
'''//////////// <<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties"> ////////////'''
public class MyCompProperties : CompProperties ''// Name this as you wish, of course''
{
public Properties() {
this.compClass = typeof(MyNamespace.MyLinkedCompThing); ''// rename as appropriate''
}
public string myCustomCompProperty; ''// Name matches def, of course''
public int mySecondCompProp = 1; ''// Can set default values''
}

''// this ThingComp is used to actually access the comp property defined above''
'''''// this is not "<compClass>MyNamespace.MyCustomThingComp</compClass>"'''''
public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty
{
get
{
return ((MyCompProperties)this.props).myCustomCompProperty;
}
}
public int mySecondCompProperty ''// Have to get all the names right''
{ get { return ((MyCompProperties)this.props).mySecondCompProperty; } } ''//etc''
}
'''//////////// <compClass>MyNamespace.MyCustomThingComp</compClass> ////////////'''
public class MyCustomThingComp : ThingComp
{
public override void CompTick()
{
// do stuff
}
public override void CompTickRare() //etc
public override ... // Check out Verse/ThingComp.cs for more ideas
}
} // end MyNamespace

=== Accessing your Comps ===
Just setting up your custom comps doesn't do you a lot of good if you can't access them!

==== Accessing CompProperty directly ====
This is the "hard" way, but doable if you want:
<code lang="C#">
int importantProperty = ((MyCompProperties)((ThingWithComps)myObject).GetComp<MyLinkedCompThing>().props).mySecondCompProp;
// The "(ThingWithComps) cast may or may not be needed
</code>

==== Use the "get" method we created ====
<code lang="C#">
// real world example:
SlotGroup slotGroup = GetSlotGroupInEarlierCode();
MyLinkedCompThing comp = ((ThingWithComps)slotGroup.parent).GetComp<MyLinkedCompThing>();
if (comp != null) {
string s = comp.myCustomCompProperty;
int x = otherObject.GetComp<MyLinkedCompThing>().mySecondCompProp; // be sure it exists, etc
} else { /* not a thing with my comp, etc */ }
</code>

=== Cautions, traps, etc ===
If you have the same comp in an abstract (XML) def and attempt to redefine it in a (XML) child def, it will get counted twice. It's possible to get around this in the code, if you want to have default comps:

<ThingDef Name=ParentWithDefault ... Abstract=true>
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>3</myValue>
</l<nowiki>i</nowiki>>
</comps>
</ThingDef>
<ThingDef ParentName="ParentWihtDefault">
...
<comps>
<l<nowiki>i</nowiki> Class="MyCompPropertiesWithDefault">
<myValue>5</myValue>
</<nowiki>l</nowiki>i>
</comps>
</ThingDef>

public class MyLinkedCompThing : ThingComp
{
public string myCustomCompProperty //etc

public override void Initialize (CompProperties props) {
base.Initialize(props);
// Remove duplicate entries and ensure the last entry is the only one left
// This allows a default abstract def with the comp
// and child def to change the comp value:
MyCompProprtiesWithDefault[] list = this.parent.GetComps<MyCompPropertiesWithDefault>().ToArray();
// Remove everything but the last entry; harmless if only one entry:
for (var i = 0; i < list.Length-1; i++)
{
this.parent.AllComps.Remove(list[i]);
}
}

///etc
}

[[Category:Modding tutorials]][[Category:Modding]][[Category:Defs]]

Modding Tutorials/Custom Comp Classes

2019-01-05T22:23:51Z

Lilwhitemouse: /* Cautions, traps, etc */ clearer

Modding Tutorials/Custom Comp Classes

2019-01-05T22:23:18Z

Lilwhitemouse: fixed typo

Modding Tutorials/Setting up a solution

2019-01-04T02:27:21Z

Lilwhitemouse: /* Option 2 (Automatic Method): */

{{BackToTutorials}}
{{Credit|[[User:Alistaire|Alistaire]]}} 

In this tutorial you will learn how to set up a solution, along with instructions on setting the output directory and files for more convenient building right into the Assemblies folder.

=Important Note=
There is a [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool available that should be able to set up a lot of these files/etc for you!

=Requirements=

* The manual option in this tutorial requires you to have [[Modding_Tutorials/Mod_folder_structure#The Source and Assemblies folders|set up a Source and Assemblies folder]] (the Visual Studio automatic option sets this up for you).
* You will want to have an IDE installed: [[Modding Tutorials/Recommended software#IDE's|Recommended IDE's]]. 

=Setting up a solution=
Setting up can be different for different IDE's. Feel free to add '''''complete''''' instructions for your IDE of choice.

===Visual Studio Community 2017===
''NOTE: Visual Studio 2017 is a rather heavy application (2-3 GB for basic functionality) but has a bit more functionality. Only Install if your computer can handle it! The tutorial is similar for Visual Studio 2015.''

==== Option 1 (Manual Method):====
# Create a new class library project
## Once loaded, go to File -> New -> Project...
## Go to Templates -> Visual C# -> Class Library (Be sure to select the *.NET Framework* version, not *.NET Standard*) [[File:Capture.png|200px|thumb|right|Installing the .NET framework]]
## Enter your name and solution name in the lower pane.
## Choose a location, preferably: <pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create directory for solution"
# In your project, set target framework and various other porperties
## In your Solution Explorer, right click your project -> Properties
## Once in your properties, select Application -> Set Target Framework to .NET Framework 3.5 (No client profile)
## ''Optional'': Change your Assembly and Namespace names to anything of your choice
## Go to Build -> Advanced... and set "Debugging information" to none
## Leave Advanced..., and set the Output Path to "..\..\Assemblies\" (The Assemblies folder in your mod folder)
# Add references to RimWorld code
## Expand your project. Then right click "References" -> Add Reference...
## Click Browse...
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <pre>Assembly-CSharp.dll
UnityEngine.dll</pre>
## Click "Add"
## Right click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Automatic Method):====
'''Note: As of Jan 2019, the cookiecutter is set up for Windows development. Linux/Mac people can still use it, but they will have a few errors to clean up.'''
# Open Visual Studio
# Once loaded, go to File -> New -> From Cookiecutter...
# Search for ''rimworld''
# Double-click ''cookiecutter-rimworld-mod-development''
# Change the Template Options:
## ''Create To'' => ''Your/Rimworld/Mod/Directory''
## ''mod_name''
## ''namespace_name'' (don't change if unsure)
## ''author'' => ''your steam username''
## ''target_version'' => current RW version (can leave blank for most up-to-date)
## ''in_game_description'' (not required, can change later in About-Release.xml)
## ''url'' (can leave blank for link to your Steam Workshop profile)
# Click "Create and Open Folder"

===Sharpdevelop===
'''Caution:''' Sharpdevelop (or #develop) does NOT CURRENTLY allow for C# 6.0+ syntax without plugins and does NOT ALLOW for C# 7.0+ syntax at all. For your average project this does not matter, however some existing projects are already built entirely upon C# 6.0+ syntax which can not be compiled anymore in Sharpdevelop. Visual Studio does not have these issues and should be your go-to for compiling large projects such as Combat Extended.

# Create a new class library project in your [[Modding Tutorials/Recommended software#IDE.27s|IDE of choice]];
## Go to File -> New -> Solution;
## Go to C# or .NET -> Library or Class Library (NOT portable);
## Enter a project name (solution name automatically updated);
## Choose a location, preferably: <pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create a directory for solution"/"Create a project within the solution directory",
# In your project, add references to Assembly-CSharp.dll and UnityEngine.dll:
## In your IDE project file browser, right-click the "References" folder and "Add reference";
## Choose the ".NET Assembly Browser" tab and "Browse...";
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <pre>Assembly-CSharp.dll
UnityEngine.dll</pre>
## Click "Open" then "OK";
## In the References folder, right-click Assembly-CSharp -> Properties and change "Local copy" to False. Do the same for UnityEngine,
# In your project properties, change the target framework to .NET 3.5:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 3.5",
# In your project properties, change the build events so only a single file is built:
## Go to the "Compiling" tab, "Output", "Debug info" and choose "No debug information";
## Right-click your .cs files -> Properties and change "Copy to output" (If you haven't resized the properties bar, this will be truncated to "Copy to out") to Never,
# In your project properties, fix the output location to put the DLL in the Assemblies folder:
## Go to the "Compiling" tab, "Output", "Output path" and change the output path to "..\..\Assemblies\". 

===Xamarin/MonoDevelop===
The setup is similar as the one above. A few special points to address:
# Mono 4.X isn't backward compatible so you may need to install an older 3.X version of Mono in order to compile against .NET3.5 dlls.
# Make sure you uncheck "Use MSBuild build engine (recommended for this project type)" under project > options > build > general (You might find this by right-clicking on your project - not solution - name and selecting options)
# Changing the framework to 3.5 can be found (for Linux anyway) in the same place.

===Rider (good for Mac)===
JetBrains Rider is a great cross-platform C# IDE, but it isn't cheap. It's $140 for the first year, including perpetual access to that version (access to future updates gets cheaper, but it's still over $100/year). However, the Early Access versions are a bit unstable but free. They also offer free student licenses.

# Open Rider and click New Solution in the welcome dialog.
## Click Class Library under .NET on the left. The option may a second to show up.
## Under Solution Name (and Project Name), enter the name of your mod.
## Set the Solution Directory to [your mod folder]/Source.
## Optionally check "put solution and project in the same directory." This is probably a good idea.
## Change Framework to .Net Framework 3.5.
## Click Create.
# In the left side bar, expand your solution, right click your project (mod name with "C#" icon) and click Properties.
## In the Properties window, select Configurations > Debug on the left and uncheck Debug Symbols.
## For both configurations, change the Output Path to ../../Assemblies.
## Click OK.
# Expand your project, right click References and click Add Reference.
## Click Add From.
## Browse to the folder with the RimWorld DLLs (Mac: /Users/[username]/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Contents/Resources/Data/Managed).
## Select both Assembly-CSharp.dll and UnityEngine.dll and click OK.
## Expand Assemblies under References. For both of the assemblies that you just added:
### Right click the assembly and click Properties.
### Uncheck "Copy Local" (you may need to scroll down) and click OK.

You're done! Note that Rider has a built-in decompiler—to view the source of a RimWorld class or method, just right-click its name and click Go To > Definition.

=See also=
* [[Modding Tutorials/Writing custom code|Writing custom code]] continues on setting up your solution. 

[[Category:Modding tutorials]]

Modding

2019-01-04T01:59:30Z

Lilwhitemouse: /* What you can mod */ +how pawns htink

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [[Modding/Random Bits of Information|Random Bits of Information]] to check if the information you're looking for has been found but just hasn't been organized into the correct article yet.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
You can mod defs, code, images, and sounds.

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils
** Higher level, explanation on how pawns think: https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL%3A-How-Pawns-Think

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Sound'''
* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''More (To be determined)'''

When the game runs, it collects all the definitions into pools. It then semi-randomly draws from these pools in various circumstances. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game means adding your definitions to these pools and watching the game use them in this way.

Definitions are organized into packages. Each package is saved as a single XML file.

Groups of packages are organized into mods. A mod is a unit of interlinked functionality and content. It could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several packages of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. In some cases, several mods can be active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<SomeDefs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</SomeDefs>
</source>
Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure:
<pre>
┌About
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game. Max width 600px.)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│the folder name must be specific here. Look in Core mod to see what are other names supposed to be
│
├Sounds
│
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─Patch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image width to 600 pixels

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_side, Texturename_front, and Texturename_back.
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_side
├╴RoyalCouch_front
└╴RoyalCouch_back
</pre>

===Interactive "things"===
A thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_TurretImprovised</turretGunDef>
<burstCooldownTicks>300</burstCooldownTicks>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==I want my mod to...:==
'''Or, how do I make my mod do ''this''?'''

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

* Save/Load information. See a very useful guide at [https://spdskatr.github.io/RWModdingResources/saving-guide this page]
* Add a new value to a def
** See [[Custom Comp Classes]]
** Also might be helpful: [https://ludeon.com/forums/index.php?topic=46351.0 Mod Extensions]

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[http://ludeon.com/forums/index.php?topic=1681.0 Simple tutorial forum thread]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding

2018-12-18T20:47:53Z

Lilwhitemouse: /* I want my mod to...: */ add new value to a def

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [[Modding/Random Bits of Information|Random Bits of Information]] to check if the information you're looking for has been found but just hasn't been organized into the correct article yet.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
You can mod defs, code, images, and sounds.

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Sound'''
* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''More (To be determined)'''

When the game runs, it collects all the definitions into pools. It then semi-randomly draws from these pools in various circumstances. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game means adding your definitions to these pools and watching the game use them in this way.

Definitions are organized into packages. Each package is saved as a single XML file.

Groups of packages are organized into mods. A mod is a unit of interlinked functionality and content. It could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several packages of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. In some cases, several mods can be active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<SomeDefs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</SomeDefs>
</source>
Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure:
<pre>
┌About
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game. Max width 600px.)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│the folder name must be specific here. Look in Core mod to see what are other names supposed to be
│
├Sounds
│
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─Patch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image width to 600 pixels

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_side, Texturename_front, and Texturename_back.
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_side
├╴RoyalCouch_front
└╴RoyalCouch_back
</pre>

===Interactive "things"===
A thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_TurretImprovised</turretGunDef>
<burstCooldownTicks>300</burstCooldownTicks>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==I want my mod to...:==
'''Or, how do I make my mod do ''this''?'''

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

* Save/Load information. See a very useful guide at [https://spdskatr.github.io/RWModdingResources/saving-guide this page]
* Add a new value to a def
** See [[Custom Comp Classes]]
** Also might be helpful: [https://ludeon.com/forums/index.php?topic=46351.0 Mod Extensions]

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[http://ludeon.com/forums/index.php?topic=1681.0 Simple tutorial forum thread]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding

2018-12-15T17:53:42Z

Lilwhitemouse: /* I want my mod to...: */

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [[Modding/Random Bits of Information|Random Bits of Information]] to check if the information you're looking for has been found but just hasn't been organized into the correct article yet.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
You can mod defs, code, images, and sounds.

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Sound'''
* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''More (To be determined)'''

When the game runs, it collects all the definitions into pools. It then semi-randomly draws from these pools in various circumstances. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game means adding your definitions to these pools and watching the game use them in this way.

Definitions are organized into packages. Each package is saved as a single XML file.

Groups of packages are organized into mods. A mod is a unit of interlinked functionality and content. It could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several packages of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. In some cases, several mods can be active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<SomeDefs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</SomeDefs>
</source>
Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure:
<pre>
┌About
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game. Max width 600px.)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│the folder name must be specific here. Look in Core mod to see what are other names supposed to be
│
├Sounds
│
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─Patch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image width to 600 pixels

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_side, Texturename_front, and Texturename_back.
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_side
├╴RoyalCouch_front
└╴RoyalCouch_back
</pre>

===Interactive "things"===
A thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_TurretImprovised</turretGunDef>
<burstCooldownTicks>300</burstCooldownTicks>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==I want my mod to...:==
'''Or, how do I make my mod do ''this''?'''

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

* Save/Load information. See a very useful guide at [https://spdskatr.github.io/RWModdingResources/saving-guide this page]

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[http://ludeon.com/forums/index.php?topic=1681.0 Simple tutorial forum thread]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding

2018-12-15T17:53:03Z

Lilwhitemouse: /* The other stuff: Code, Graphics, Sound */ Rewriting as collection of links to useful sections

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [[Modding/Random Bits of Information|Random Bits of Information]] to check if the information you're looking for has been found but just hasn't been organized into the correct article yet.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
You can mod defs, code, images, and sounds.

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Sound'''
* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''More (To be determined)'''

When the game runs, it collects all the definitions into pools. It then semi-randomly draws from these pools in various circumstances. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game means adding your definitions to these pools and watching the game use them in this way.

Definitions are organized into packages. Each package is saved as a single XML file.

Groups of packages are organized into mods. A mod is a unit of interlinked functionality and content. It could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several packages of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. In some cases, several mods can be active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<SomeDefs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</SomeDefs>
</source>
Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure:
<pre>
┌About
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game. Max width 600px.)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│the folder name must be specific here. Look in Core mod to see what are other names supposed to be
│
├Sounds
│
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─Patch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image width to 600 pixels

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_side, Texturename_front, and Texturename_back.
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_side
├╴RoyalCouch_front
└╴RoyalCouch_back
</pre>

===Interactive "things"===
A thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_TurretImprovised</turretGunDef>
<burstCooldownTicks>300</burstCooldownTicks>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==I want my mod to...:==
'''Or, how do I make my mod do this?'''

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

* Save/Load information. See a very useful guide at [https://spdskatr.github.io/RWModdingResources/saving-guide this page]

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[http://ludeon.com/forums/index.php?topic=1681.0 Simple tutorial forum thread]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding

2018-12-15T17:10:33Z

Lilwhitemouse: /* What you can mod */ added link to useful jobs wiki

{| align=center
| {{Basics_Nav}}
|}
<hr>

{{See also|List of mods}}
'''Mods''' (short for modifications) are small packages that add to or otherwise affect gameplay in RimWorld. They include art packs (for reskinning the game), more weapons, more incidents, furniture, and game-balancing mods.

This page is about making mods. For info about using mods, see [[Installing mods]].

==Mod-making tutorials==
Mod-making tutorials are available at the [[Modding Tutorials]] page. If you can't find what you need, you should try looking in [[Modding/Random Bits of Information|Random Bits of Information]] to check if the information you're looking for has been found but just hasn't been organized into the correct article yet.

===Mod-making Templates===
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]

==What you can mod==
You can mod defs, code, images, and sounds.

* '''Defs''': XML files containing lists of definitions for use by the game. There are a lot of these. They define every thing, skills, storyteller, and many other types of data. Find them in YourModName/Defs. More about this later.
* '''Code''': You can add .NET assemblies and the game will load them. Place your DLLs in YourModName/Assemblies. More about this later.
* '''Images''': You can add images.
* '''Sounds''': You can add sound files.
* '''Jobs''': A useful link here https://github.com/Mehni/ExampleJob/wiki - covers JobGivers WorkGivers and Toils

==The basics: Defs==
The most basic kind of RimWorld modding is done by editing '''defs'''.

Definitions each define some piece of the game. Different kinds of definitions can define:

* '''Sound'''
* '''Weapons'''
* '''Buildings'''
* '''Plants'''
* '''Animals'''
* '''More (To be determined)'''

When the game runs, it collects all the definitions into pools. It then semi-randomly draws from these pools in various circumstances. It will randomly draw guns of a certain category to arm a new enemy mercenary. Or, it will randomly spawn an animal type on the edge of the map. Modding the game means adding your definitions to these pools and watching the game use them in this way.

Definitions are organized into packages. Each package is saved as a single XML file.

Groups of packages are organized into mods. A mod is a unit of interlinked functionality and content. It could be a pack of new weapons, a new animal, or a total conversion of the game. A mod will usually contain several packages of various types, as well as content like images and sounds.

The base game is defined in a single mod called Core.

Players can choose which mods to activate. In some cases, several mods can be active at once. You could use a medieval mod to replace the core mod, and add on a weapons pack created by someone else. The game will run with the medieval mod content, and also randomly spawn in weapons from the extra weapons pack.

==Mod file structure==
For defining new game content, '''[[wikipedia:XML|XML]]''' files are used. Here is an example of the format, that applies to most of the definitions:
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<SomeDefs>
<SomeDef>
<defName>MyNewDefinitionOfContent</defName>

</SomeDef>
</SomeDefs>
</source>
Remember, that the word '''Some''' must be replaced by the name of whatever are you defining. For thing it's '''<ThingDef>'''.

The RimWorld mods use the following directory structure:
<pre>
┌About
├─About.xml (Contains info about the mod)
├─Preview.png (Image that appears above the mod info in game. Max width 600px.)
│
├Assemblies (If your mod uses any DLL files put them here)
├─MyMod.dll
│
├Defs (Contains xml definitions of the mod)
├┬ThingDefs
│├─Things.xml
│└─Buildings.xml
│
├┬ResearchProjectDefs
│└─MyProjects.xml
│
│the folder name must be specific here. Look in Core mod to see what are other names supposed to be
│
├Sounds
│
├Source
├─MyMod.cs (Optionally, put the source code of your mod here)
│
├Patches
├─Patch.xml
│
├Languages
├┬English (Replace with the language name)
│├┬Keyed
││└─Keys.xml
│├┬Strings
││└┬Names
││ └─PawnNames.xml
│├┬DefInjected
││└┬ThingDef
││ └─Thing.xml
│├─LanguageInfo.xml
│└─LangIcon.png
│
├Textures (Put any image textures here, preferably in .png format.)
├┬Things
│├─MyMod_ImageA.png
│└─MyMod_ImageB.png
</pre>

===Mod info===
This is found in <code>MODNAME/About</code>
*The contents of About.xml are plain text. HTML Markup tags cause NullRef's.
*You can have an image for your mod. Restrict the image width to 600 pixels

===Textures===
These are found in <code>MODNAME/Textures</code>
*You can have any path you want from this point on.
*When referencing textures in your mod, using <graphicPath>, have the complete path relative to your mod, including the filename (but not the file extension). Example for the RoyalBed Testmod: <code><graphicPath>Things/Building/RoyalBed</graphicPath></code>

For textures that have multiple faces, like animals and furniture which can be rotated; You can use the Graphic_multi class. Immediately following your <graphicPath></graphicPath>. Your Path should point to the folder containing the different textures: Texturename_side, Texturename_front, and Texturename_back.
<source lang="xml" >
<graphicPath>Things/Buildings/RoyalCouch/RoyalCouch</graphicPath>
<graphicClass>Graphic_multi</graphicClass>
</source>

Inside your folder:
<pre>
┌Textures
└┬Things
└┬Buildings
└┬RoyalCouch
├╴RoyalCouch_side
├╴RoyalCouch_front
└╴RoyalCouch_back
</pre>

===Interactive "things"===
A thing is anything that exists in the game world. It includes resources, races (humanoid and animal), buildings, furniture, and many others.

These are defined in <code>MODNAME/Defs/ThingDefs</code>
If you make a new workbench, you'll need to define a recipe for it. This is a list, so you can have many new recipes listed.

The recipes themselves are defined in: <code>MODNAME/Defs/RecipeDefs</code>
In here you can define what ingredients/resources are required, what can be used, and what the default recipe is.

Any new resources will need to be defined in: <code>MODNAME/Defs/ThingDefs</code>

===Turrets===
These are defined in two files in: <code>MODNAME/Defs/ThingDefs/Buildings_Big.xml</code> and <code>Weapons_Guns.xml</code> (Remember, these can be named anything)

Buildings_Big.xml defines the structure of the turret itself. For example:
<source lang="xml" >
<building>
<turretGunDef>Gun_TurretImprovised</turretGunDef>
<burstCooldownTicks>300</burstCooldownTicks>
</building>
</source>
Weapons_Gun.xml defines the weapon the turret uses. Anything can be used as a weapon for turrets, including grenades.

===Resources===
These are defined in: <code>MODNAME/Defs/ThingDefs/Resources.xml</code>

===Research projects===
These are found in: <code>MODNAME/Defs/ResearchProjectDefs</code>

You can have research trees as well, where additional research projects get unlocked as you move through.
This is how to add prerequisites:
<source lang="xml" >
<prerequisites>
<li>-this is the <defName> of the prerequisite-</li>
</prerequisites>
</source>
Because it's a list, you can have multiple prerequisites for a research project.

==Advice==
*The tilde key (` or ~) brings up the development console, which will report any errors or warnings it encounters when a mod loads or during gameplay. This is the quickest way to see what, if any, errors exist in your mod. (You don't need to turn on development mode for this.)
*Use development mode (found in the options menu) to help debug your mod, spawn items related to your mod, or fire incidents at will. (Or just mess around, if you'd like.)

==The other stuff: Code, Graphics, Sound==

You can find links to tutorials on the [[Modding Tutorials]] page. There's also more tutorials about the basics there, so don't miss out on that.

== References ==
*[https://github.com/roxxploxx/RimWorldModGuide/wiki A good guide to assist people trying to mod RimWorld]
*[https://ludeon.com/forums/index.php?topic=39038.0 Mod Development Cookiecutter (automatically build your mod development environment)]
*[http://ludeon.com/forums/index.php?topic=1681.0 Simple tutorial forum thread]
*[https://ludeon.com/forums/index.php?topic=2325.0 RimWorld core art source thread]

== Notes ==
*You can have as many mods as you like, however too many mods may affect performance.
*If the game crashes due to a mod-related reason on startup, or mods conflict with each other, then the game will reset the mods.
*Mods for previous versions may be usable, however most of the time they are not compatible.

[[Category:Modding]]

Modding Tutorials/Custom Comp Classes

2018-12-15T16:33:31Z

Lilwhitemouse: /* Cautions, traps, etc */ better example

Modding Tutorials/Setting up a solution

2018-12-01T18:59:08Z

Lilwhitemouse: link to cookiecutter

{{BackToTutorials}}
{{Credit|[[User:Alistaire|Alistaire]]}} 

In this tutorial you will learn how to set up a solution, along with instructions on setting the output directory and files for more convenient building right into the Assemblies folder.

=Important Note=
There is a [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool available that should be able to set up a lot of these files/etc for you!

=Requirements=

* The manual option in this tutorial requires you to have [[Modding_Tutorials/Mod_folder_structure#The Source and Assemblies folders|set up a Source and Assemblies folder]] (the Visual Studio automatic option sets this up for you).
* You will want to have an IDE installed: [[Modding Tutorials/Recommended software#IDE's|Recommended IDE's]]. 

=Setting up a solution=
Setting up can be different for different IDE's. Feel free to add '''''complete''''' instructions for your IDE of choice.

===Visual Studio Community 2017===
''NOTE: Visual Studio 2017 is a rather heavy application (2-3 GB for basic functionality) but has a bit more functionality. Only Install if your computer can handle it! The tutorial is similar for Visual Studio 2015.''

==== Option 1 (Manual Method):====
# Create a new class library project
## Once loaded, go to File -> New -> Project...
## Go to Templates -> Visual C# -> Class Library (Be sure to select the *.NET Framework* version, not *.NET Standard*) [[File:Capture.png|200px|thumb|right|Installing the .NET framework]]
## Enter your name and solution name in the lower pane.
## Choose a location, preferably: <pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create directory for solution"
# In your project, set target framework and various other porperties
## In your Solution Explorer, right click your project -> Properties
## Once in your properties, select Application -> Set Target Framework to .NET Framework 3.5 (No client profile)
## ''Optional'': Change your Assembly and Namespace names to anything of your choice
## Go to Build -> Advanced... and set "Debugging information" to none
## Leave Advanced..., and set the Output Path to "..\..\Assemblies\" (The Assemblies folder in your mod folder)
# Add references to RimWorld code
## Expand your project. Then right click "References" -> Add Reference...
## Click Browse...
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <pre>Assembly-CSharp.dll
UnityEngine.dll</pre>
## Click "Add"
## Right click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Automatic Method):====
# Open Visual Studio
# Once loaded, go to File -> New -> From Cookiecutter...
# Search for ''rimworld''
# Double-click ''cookiecutter-rimworld-mod-development''
# Change the Template Options:
## ''Create To'' => ''Your/Rimworld/Mod/Directory''
## ''mod_name''
## ''namespace_name'' (don't change if unsure)
## ''author'' => ''your steam username''
## ''target_version'' => current RW version (can leave blank for most up-to-date)
## ''in_game_description'' (not required, can change later in About-Release.xml)
## ''url'' (can leave blank for link to your Steam Workshop profile)
# Click "Create and Open Folder"

===Sharpdevelop===
'''Caution:''' Sharpdevelop (or #develop) does NOT CURRENTLY allow for C# 6.0+ syntax without plugins and does NOT ALLOW for C# 7.0+ syntax at all. For your average project this does not matter, however some existing projects are already built entirely upon C# 6.0+ syntax which can not be compiled anymore in Sharpdevelop. Visual Studio does not have these issues and should be your go-to for compiling large projects such as Combat Extended.

# Create a new class library project in your [[Modding Tutorials/Recommended software#IDE.27s|IDE of choice]];
## Go to File -> New -> Solution;
## Go to C# or .NET -> Library or Class Library (NOT portable);
## Enter a project name (solution name automatically updated);
## Choose a location, preferably: <pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create a directory for solution"/"Create a project within the solution directory",
# In your project, add references to Assembly-CSharp.dll and UnityEngine.dll:
## In your IDE project file browser, right-click the "References" folder and "Add reference";
## Choose the ".NET Assembly Browser" tab and "Browse...";
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <pre>Assembly-CSharp.dll
UnityEngine.dll</pre>
## Click "Open" then "OK";
## In the References folder, right-click Assembly-CSharp -> Properties and change "Local copy" to False. Do the same for UnityEngine,
# In your project properties, change the target framework to .NET 3.5:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 3.5",
# In your project properties, change the build events so only a single file is built:
## Go to the "Compiling" tab, "Output", "Debug info" and choose "No debug information";
## Right-click your .cs files -> Properties and change "Copy to output" (If you haven't resized the properties bar, this will be truncated to "Copy to out") to Never,
# In your project properties, fix the output location to put the DLL in the Assemblies folder:
## Go to the "Compiling" tab, "Output", "Output path" and change the output path to "..\..\Assemblies\". 

===Xamarin/MonoDevelop===
The setup is similar as the one above. A few special points to address:
# Mono 4.X isn't backward compatible so you may need to install an older 3.X version of Mono in order to compile against .NET3.5 dlls.
# Make sure you uncheck "Use MSBuild build engine (recommended for this project type)" under project > options > build > general (You might find this by right-clicking on your project - not solution - name and selecting options)
# Changing the framework to 3.5 can be found (for Linux anyway) in the same place.

===Rider (good for Mac)===
JetBrains Rider is a great cross-platform C# IDE, but it isn't cheap. It's $140 for the first year, including perpetual access to that version (access to future updates gets cheaper, but it's still over $100/year). However, the Early Access versions are a bit unstable but free. They also offer free student licenses.

# Open Rider and click New Solution in the welcome dialog.
## Click Class Library under .NET on the left. The option may a second to show up.
## Under Solution Name (and Project Name), enter the name of your mod.
## Set the Solution Directory to [your mod folder]/Source.
## Optionally check "put solution and project in the same directory." This is probably a good idea.
## Change Framework to .Net Framework 3.5.
## Click Create.
# In the left side bar, expand your solution, right click your project (mod name with "C#" icon) and click Properties.
## In the Properties window, select Configurations > Debug on the left and uncheck Debug Symbols.
## For both configurations, change the Output Path to ../../Assemblies.
## Click OK.
# Expand your project, right click References and click Add Reference.
## Click Add From.
## Browse to the folder with the RimWorld DLLs (Mac: /Users/[username]/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Contents/Resources/Data/Managed).
## Select both Assembly-CSharp.dll and UnityEngine.dll and click OK.
## Expand Assemblies under References. For both of the assemblies that you just added:
### Right click the assembly and click Properties.
### Uncheck "Copy Local" (you may need to scroll down) and click OK.

You're done! Note that Rider has a built-in decompiler—to view the source of a RimWorld class or method, just right-click its name and click Go To > Definition.

=See also=
* [[Modding Tutorials/Writing custom code|Writing custom code]] continues on setting up your solution. 

[[Category:Modding tutorials]]

Modding Tutorials/Recommended software

2018-11-30T05:39:56Z

Lilwhitemouse: /* IDE's */ Linux!

{{BackToTutorials}}
{{Credit|[[User:Alistaire|Alistaire]]}} 

=What you'll learn=

This tutorial lists a few programs you could use to edit XML and C# code. 

=XML Code Editors=

===Basic Editors===

Just about any text editor can write XML code, but as a modder you will want to at the very least see when you forgot closing brackets, a closing tag and other syntax errors. 

Notepad doesn't do this, so if you're even somewhat serious about modding, the following software will help you immensely: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [NotepadQQ] || Linux || Notepadqq is a Notepad++-like editor for the Linux desktop so has the exact same UI and functions as Notepad++
|-
| [http://notepad-plus-plus.org/download/ Notepad++] || Windows || Has well implemented auto-completion and a very customizable user interface. Can be used to write both XML and C# code, although C# software usually has its own text editor
|-
| [http://www.sublimetext.com/ Sublime Text] || Linux/Windows/Mac || Natively supports many programming languages and markup languages, and its functionality can be extended by users with plugins - A brief overview of its functionality can be found [http://webdesign.tutsplus.com/tutorials/useful-shortcuts-for-a-faster-workflow-in-sublime-text-3--cms-22185 here] and a full course [http://code.tutsplus.com/courses/perfect-workflow-in-sublime-text-2 here]
|-
| [http://www.pnotepad.org/download/ Programmer's Notepad] || Windows || More lightweight with a less cluttered interface than Notepad++, also capable of editing both XML and C# code
|-
| [http://xmlnotepad.codeplex.com/releases/ XML Notepad] || Windows || XML-oriented editor with a lot of features you will most likely never use in Rimworld modding
|-
| [http://www.geany.org/ Geany] || Linux/Windows/Mac || Extremely lightweight text editor with syntax highlighting and some other basic features oriented towards XML and code editing.
|} 

===Advanced Editors===

There's many editors out there specifically made for XML code. Because Rimworld uses XML in a very simple way, advanced code editors are rarely needed. In case you're ever in need of one, however, the following ones might help: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/xpontus/files/ XPontus] || Windows || Has a tree view and is capable of checking XML for errors, fixing tabs and creating schema's detailing every tag's data types
|-
| [http://xmlgrid.net/ XMLGrid] || - || Capable of validating XML and turning it into Excel Spreadsheets, XSD Charts and an online table detailing each tag of a certain type and its contents
|-
| [http://codebeautify.org/xmlviewer Codebeautify's xmlviewer] || - || Can display as a tree view, automatically format/indent your code and can validate and show errors too. Also have a function share code (like [http://codebeautify.org/xmlviewer/b39586 that])
|} 

=IDE's=

C# code is best edited in an IDE (Integrated Development Environment) to make the process of editing code, managing a solution's content and compiling its projects both easier and faster. Any IDE for C# will probably work just fine, so here's a list of suggested editors: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.visualstudio.com/ Visual Studio] || Windows || Very extensive IDE with paid, trial and free versions. Any of these versions will probably work, so you might as well take [https://www.visualstudio.com/products/visual-studio-community-vs Visual Studio Community 2015] which is free for individuals and small teams
|-
| [http://www.icsharpcode.net/OpenSource/SD/Download/ SharpDevelop] || Windows || Free IDE specifically made for C#
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || Free, cross-platform IDE with customizable user interface. Has support for C# as well as some other languages you won't need for Rimworld
|-
| [http://www.xamarin.com/platform Xamarin] || Mac || It's free but you need to register to download it. Probably your best option on a mac.
|}

'''For Linux users:''' See also [https://ludeon.com/forums/index.php?topic=46775.0 this thread] about working with C# on ArchLinux - it may be useful.

Whichever IDE you choose, make sure it's capable of compiling for .NET Framework 3.5. If you for whatever reason don't have this framework installed, you can download it [https://www.microsoft.com/en-us/download/details.aspx?id=21 here]. 

=Additional C# Software=

Besides your IDE it's strongly recommended to install the following software for decompiling: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [https://github.com/0xd4d/dnSpy dnSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding (some authors have had better luck with dnSpy than ILSpy?)
|-
| [http://ilspy.net/ ILSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || The Linux version of the software has an integrated decompiler for .DLLs
|} 

=Graphics Software=

For making textures you will need graphics software. Any image editing program should work, and if you have an alternative to the following links that's probably okay: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.photofiltre-studio.com/download-en.htm Photofiltre Studio] || Windows || Functional software with very little user interface clutter for its applications. Doesn't support pen tablet, and has a 100% free (non-trial) version called [http://photofiltre.free.fr/download_en.htm Photofiltre]
|-
| [http://inkscape.org/en/download/ Inkscape] || Linux/Windows/Mac || Free vector graphic program with a steeper learning curve due to the vector based image editing. Vector graphics can look better than bitmap graphics in Rimworld
|-
| [http://www.photoshop.com/products Photoshop] || Windows/Mac || Paid software with a trial version. Rimworld's original graphics are made in Photoshop (they're .PSD files)
|-
| [http://www.gimp.org/ Gimp] || Linux/Windows/Mac || A free, open-source alternative to Photoshop that's been around since 1998. Gimp has a large user community, with great list of [http://www.gimp.org/tutorials/ tutorials] on the official sites
|-
| [https://krita.org/en/homepage/ Krita] || Linux/Windows/Mac || A free digital painting software. Better suited than GIMP for painting and should feel like home pretty quick for Photoshop users.
|} 

=Audio Software=

Recording your own audio for mods might be too much to ask, but editing audio is always possible. This can be done with the following software or your own alternative: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/audacity/ Audacity] || Linux/Windows/Mac || Audio editing software with many tutorials online, lots of useful functionality and a relatively readable interface
|} 

=Next up=

# [[Modding Tutorials/XML file structure|XML File Structure]] starts you off with the XML side of modding.
# [[Modding_Tutorials/Setting up a solution|Setting up]] starts you off with the C# side of modding. Knowledge of the XML part can and will be very useful. 

[[Category:Modding tutorials]]

Modding Tutorials/Recommended software

2018-11-30T05:38:42Z

Lilwhitemouse: /* Additional C# Software */ typo

{{BackToTutorials}}
{{Credit|[[User:Alistaire|Alistaire]]}} 

=What you'll learn=

This tutorial lists a few programs you could use to edit XML and C# code. 

=XML Code Editors=

===Basic Editors===

Just about any text editor can write XML code, but as a modder you will want to at the very least see when you forgot closing brackets, a closing tag and other syntax errors. 

Notepad doesn't do this, so if you're even somewhat serious about modding, the following software will help you immensely: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [NotepadQQ] || Linux || Notepadqq is a Notepad++-like editor for the Linux desktop so has the exact same UI and functions as Notepad++
|-
| [http://notepad-plus-plus.org/download/ Notepad++] || Windows || Has well implemented auto-completion and a very customizable user interface. Can be used to write both XML and C# code, although C# software usually has its own text editor
|-
| [http://www.sublimetext.com/ Sublime Text] || Linux/Windows/Mac || Natively supports many programming languages and markup languages, and its functionality can be extended by users with plugins - A brief overview of its functionality can be found [http://webdesign.tutsplus.com/tutorials/useful-shortcuts-for-a-faster-workflow-in-sublime-text-3--cms-22185 here] and a full course [http://code.tutsplus.com/courses/perfect-workflow-in-sublime-text-2 here]
|-
| [http://www.pnotepad.org/download/ Programmer's Notepad] || Windows || More lightweight with a less cluttered interface than Notepad++, also capable of editing both XML and C# code
|-
| [http://xmlnotepad.codeplex.com/releases/ XML Notepad] || Windows || XML-oriented editor with a lot of features you will most likely never use in Rimworld modding
|-
| [http://www.geany.org/ Geany] || Linux/Windows/Mac || Extremely lightweight text editor with syntax highlighting and some other basic features oriented towards XML and code editing.
|} 

===Advanced Editors===

There's many editors out there specifically made for XML code. Because Rimworld uses XML in a very simple way, advanced code editors are rarely needed. In case you're ever in need of one, however, the following ones might help: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/xpontus/files/ XPontus] || Windows || Has a tree view and is capable of checking XML for errors, fixing tabs and creating schema's detailing every tag's data types
|-
| [http://xmlgrid.net/ XMLGrid] || - || Capable of validating XML and turning it into Excel Spreadsheets, XSD Charts and an online table detailing each tag of a certain type and its contents
|-
| [http://codebeautify.org/xmlviewer Codebeautify's xmlviewer] || - || Can display as a tree view, automatically format/indent your code and can validate and show errors too. Also have a function share code (like [http://codebeautify.org/xmlviewer/b39586 that])
|} 

=IDE's=

C# code is best edited in an IDE (Integrated Development Environment) to make the process of editing code, managing a solution's content and compiling its projects both easier and faster. Any IDE for C# will probably work just fine, so here's a list of suggested editors: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.visualstudio.com/ Visual Studio] || Windows || Very extensive IDE with paid, trial and free versions. Any of these versions will probably work, so you might as well take [https://www.visualstudio.com/products/visual-studio-community-vs Visual Studio Community 2015] which is free for individuals and small teams
|-
| [http://www.icsharpcode.net/OpenSource/SD/Download/ SharpDevelop] || Windows || Free IDE specifically made for C#
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || Free, cross-platform IDE with customizable user interface. Has support for C# as well as some other languages you won't need for Rimworld
|-
| [http://www.xamarin.com/platform Xamarin] || Mac || It's free but you need to register to download it. Probably your best option on a mac.
|}

Whichever IDE you choose, make sure it's capable of compiling for .NET Framework 3.5. If you for whatever reason don't have this framework installed, you can download it [https://www.microsoft.com/en-us/download/details.aspx?id=21 here]. 

=Additional C# Software=

Besides your IDE it's strongly recommended to install the following software for decompiling: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [https://github.com/0xd4d/dnSpy dnSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding (some authors have had better luck with dnSpy than ILSpy?)
|-
| [http://ilspy.net/ ILSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || The Linux version of the software has an integrated decompiler for .DLLs
|} 

=Graphics Software=

For making textures you will need graphics software. Any image editing program should work, and if you have an alternative to the following links that's probably okay: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.photofiltre-studio.com/download-en.htm Photofiltre Studio] || Windows || Functional software with very little user interface clutter for its applications. Doesn't support pen tablet, and has a 100% free (non-trial) version called [http://photofiltre.free.fr/download_en.htm Photofiltre]
|-
| [http://inkscape.org/en/download/ Inkscape] || Linux/Windows/Mac || Free vector graphic program with a steeper learning curve due to the vector based image editing. Vector graphics can look better than bitmap graphics in Rimworld
|-
| [http://www.photoshop.com/products Photoshop] || Windows/Mac || Paid software with a trial version. Rimworld's original graphics are made in Photoshop (they're .PSD files)
|-
| [http://www.gimp.org/ Gimp] || Linux/Windows/Mac || A free, open-source alternative to Photoshop that's been around since 1998. Gimp has a large user community, with great list of [http://www.gimp.org/tutorials/ tutorials] on the official sites
|-
| [https://krita.org/en/homepage/ Krita] || Linux/Windows/Mac || A free digital painting software. Better suited than GIMP for painting and should feel like home pretty quick for Photoshop users.
|} 

=Audio Software=

Recording your own audio for mods might be too much to ask, but editing audio is always possible. This can be done with the following software or your own alternative: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/audacity/ Audacity] || Linux/Windows/Mac || Audio editing software with many tutorials online, lots of useful functionality and a relatively readable interface
|} 

=Next up=

# [[Modding Tutorials/XML file structure|XML File Structure]] starts you off with the XML side of modding.
# [[Modding_Tutorials/Setting up a solution|Setting up]] starts you off with the C# side of modding. Knowledge of the XML part can and will be very useful. 

[[Category:Modding tutorials]]

Modding Tutorials/Recommended software

2018-11-30T05:38:25Z

Lilwhitemouse: /* Additional C# Software */ dnSpy

{{BackToTutorials}}
{{Credit|[[User:Alistaire|Alistaire]]}} 

=What you'll learn=

This tutorial lists a few programs you could use to edit XML and C# code. 

=XML Code Editors=

===Basic Editors===

Just about any text editor can write XML code, but as a modder you will want to at the very least see when you forgot closing brackets, a closing tag and other syntax errors. 

Notepad doesn't do this, so if you're even somewhat serious about modding, the following software will help you immensely: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [NotepadQQ] || Linux || Notepadqq is a Notepad++-like editor for the Linux desktop so has the exact same UI and functions as Notepad++
|-
| [http://notepad-plus-plus.org/download/ Notepad++] || Windows || Has well implemented auto-completion and a very customizable user interface. Can be used to write both XML and C# code, although C# software usually has its own text editor
|-
| [http://www.sublimetext.com/ Sublime Text] || Linux/Windows/Mac || Natively supports many programming languages and markup languages, and its functionality can be extended by users with plugins - A brief overview of its functionality can be found [http://webdesign.tutsplus.com/tutorials/useful-shortcuts-for-a-faster-workflow-in-sublime-text-3--cms-22185 here] and a full course [http://code.tutsplus.com/courses/perfect-workflow-in-sublime-text-2 here]
|-
| [http://www.pnotepad.org/download/ Programmer's Notepad] || Windows || More lightweight with a less cluttered interface than Notepad++, also capable of editing both XML and C# code
|-
| [http://xmlnotepad.codeplex.com/releases/ XML Notepad] || Windows || XML-oriented editor with a lot of features you will most likely never use in Rimworld modding
|-
| [http://www.geany.org/ Geany] || Linux/Windows/Mac || Extremely lightweight text editor with syntax highlighting and some other basic features oriented towards XML and code editing.
|} 

===Advanced Editors===

There's many editors out there specifically made for XML code. Because Rimworld uses XML in a very simple way, advanced code editors are rarely needed. In case you're ever in need of one, however, the following ones might help: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/xpontus/files/ XPontus] || Windows || Has a tree view and is capable of checking XML for errors, fixing tabs and creating schema's detailing every tag's data types
|-
| [http://xmlgrid.net/ XMLGrid] || - || Capable of validating XML and turning it into Excel Spreadsheets, XSD Charts and an online table detailing each tag of a certain type and its contents
|-
| [http://codebeautify.org/xmlviewer Codebeautify's xmlviewer] || - || Can display as a tree view, automatically format/indent your code and can validate and show errors too. Also have a function share code (like [http://codebeautify.org/xmlviewer/b39586 that])
|} 

=IDE's=

C# code is best edited in an IDE (Integrated Development Environment) to make the process of editing code, managing a solution's content and compiling its projects both easier and faster. Any IDE for C# will probably work just fine, so here's a list of suggested editors: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.visualstudio.com/ Visual Studio] || Windows || Very extensive IDE with paid, trial and free versions. Any of these versions will probably work, so you might as well take [https://www.visualstudio.com/products/visual-studio-community-vs Visual Studio Community 2015] which is free for individuals and small teams
|-
| [http://www.icsharpcode.net/OpenSource/SD/Download/ SharpDevelop] || Windows || Free IDE specifically made for C#
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || Free, cross-platform IDE with customizable user interface. Has support for C# as well as some other languages you won't need for Rimworld
|-
| [http://www.xamarin.com/platform Xamarin] || Mac || It's free but you need to register to download it. Probably your best option on a mac.
|}

Whichever IDE you choose, make sure it's capable of compiling for .NET Framework 3.5. If you for whatever reason don't have this framework installed, you can download it [https://www.microsoft.com/en-us/download/details.aspx?id=21 here]. 

=Additional C# Software=

Besides your IDE it's strongly recommended to install the following software for decompiling: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [https://github.com/0xd4d/dnSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding (some authors have had better luck with dnSpy than ILSpy?)
|-
| [http://ilspy.net/ ILSpy] || Windows || Software which is capable of [[Modding Tutorials/Decompiling source code|decompiling source code]], which is very useful in Rimworld modding
|-
| [http://www.monodevelop.com/download/ MonoDevelop] || Linux/Windows/Mac || The Linux version of the software has an integrated decompiler for .DLLs
|} 

=Graphics Software=

For making textures you will need graphics software. Any image editing program should work, and if you have an alternative to the following links that's probably okay: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://www.photofiltre-studio.com/download-en.htm Photofiltre Studio] || Windows || Functional software with very little user interface clutter for its applications. Doesn't support pen tablet, and has a 100% free (non-trial) version called [http://photofiltre.free.fr/download_en.htm Photofiltre]
|-
| [http://inkscape.org/en/download/ Inkscape] || Linux/Windows/Mac || Free vector graphic program with a steeper learning curve due to the vector based image editing. Vector graphics can look better than bitmap graphics in Rimworld
|-
| [http://www.photoshop.com/products Photoshop] || Windows/Mac || Paid software with a trial version. Rimworld's original graphics are made in Photoshop (they're .PSD files)
|-
| [http://www.gimp.org/ Gimp] || Linux/Windows/Mac || A free, open-source alternative to Photoshop that's been around since 1998. Gimp has a large user community, with great list of [http://www.gimp.org/tutorials/ tutorials] on the official sites
|-
| [https://krita.org/en/homepage/ Krita] || Linux/Windows/Mac || A free digital painting software. Better suited than GIMP for painting and should feel like home pretty quick for Photoshop users.
|} 

=Audio Software=

Recording your own audio for mods might be too much to ask, but editing audio is always possible. This can be done with the following software or your own alternative: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [http://sourceforge.net/projects/audacity/ Audacity] || Linux/Windows/Mac || Audio editing software with many tutorials online, lots of useful functionality and a relatively readable interface
|} 

=Next up=

# [[Modding Tutorials/XML file structure|XML File Structure]] starts you off with the XML side of modding.
# [[Modding_Tutorials/Setting up a solution|Setting up]] starts you off with the C# side of modding. Knowledge of the XML part can and will be very useful. 

[[Category:Modding tutorials]]

Bed

2018-11-30T04:22:07Z

Lilwhitemouse: Colonists can sleep in dumb places

{{infobox main|furniture|
|name = Bed
|image = Bed.png|Bed
|description = A cozy mattress and sheets on a frame for resting.
|type = Furniture
|placeable = Yes
|size = 1|2
|hp = 140
|beauty = 1
|material amount = 45
|flammability = 1
|work to build = 800
|comfort = 0.75
|rest effectiveness = 1
|immunity gain speed factor = 1.07
|surgery success chance factor = 1
|mass base = 50
|cover = 0.4
}}
{{#set:
facility = dresser
|facility = end table
}}
{{Info|A bed is used by [[colonists]] for sleeping to recover their [[rest]]. It can be made out of any material but its [[Rest Effectiveness]] is 100% only when made of [[wood]] or metal. [[Quality]] can further influence the rest effectiveness and [[comfort]].

While resting in a bed, colonists heal by an additional 3 HP per day.

Beds can be walked over, although at a slower rate.

A newly constructed bed is shown as 'unowned'. A colonist without an assigned bed will claim an unowned bed which will then show their name. A bed's ownership can be set or overridden by clicking the 'Set owner' button. Manually setting bed ownership is often unnecessary except when the player finds it desirable to control where a colonist sleeps, such as near their work area. If there are beds in terrible sleeping places (outside, cold, whatever), colonists have a strong ability to choose them. Also, sometimes married colonists will not choose double beds on their own, and will end up sleeping alone.

There is a version for two colonists called the [[double bed]], and a deluxe version known as the [[royal bed]].}}

===Prisoner bed===
A bed may be assigned for [[prisoner]] use by clicking 'Set for prisoners'. The bed must be in an enclosed room. Once a bed is set for prisoners the entire room is set as a prisoner room and all other beds within are changed to prisoner beds. A prisoner bed is clearly indicated by its gold color. The game will not allow a non-colonist to be captured or arrested without an available prisoner bed. A bed may be switched back for colonist use by clicking 'Set for colonists' and all beds in the same room will also revert to the green colonist bed. However, if any prisoner bed has an owner the player will be required to confirm the action and the prisoners will be unable to use the beds.

===Medical bed===
A bed may be designated as a medical bed by clicking 'Set as medical'. This is not to be confused with a [[hospital bed]], which is unlocked with [[research]]. Colonists can be assigned to this bed to Rest Until Healed, however it cannot be assigned an owner and will lose any ownership it had. A medical colonist bed is indicated by its blue color. A medical prisoner bed is indicated by its dark brown color. Newly captured prisoners are usually [[injury|injured]], therefore their captors will prioritise medical prisoner beds over regular prisoner beds. Clicking 'Set as non medical' reverts a medical bed to its original type.

=== Stats ===

Beds can be made out of the following materials:

[[Rest Effectiveness Base::1| ]] [[Flammability Base::1| ]] [[Comfort Base::0.75| ]] [[Immunity Gain Speed Factor::1.07| ]] [[Work To Make Base::800| ]]

{| {{STDT| sortable c_08 text-center}}
! Material
!data-sort-type="number"| [[Beauty]]
!data-sort-type="number"| Flammability
!data-sort-type="number"| Market value
!data-sort-type="number"| Max health
!data-sort-type="number"| Work to make
!data-sort-type="number"| Rest effectiveness
|-
|Silver || 42 || 20% || 505.00 || 105 || 12 || 100%
|-
|Gold || 155 || 20% || 7505.00 || 90 || 13 || 100%
|-
|Steel || 8 || 20% || 55.22 || 150 || 10 || 100%
|-
|Plasteel || 10 || 10% || 685.00 || 420 || 19 || 100%
|-
|Wood || 12 || 100% || 38.65 || 75 || 7 || 100%
|-
|Uranium || 3 || 0% || 2510.00 || 375 || 18 || 100%
|-
|Sandstone || 11 || 0% || 76.66 || 360 || 54 || 90%
|-
|Granite || 12 || 0% || 81.66 || 405 || 54 || 90%
|-
|Limestone || 12 || 0% || 76.66 || 380 || 54 || 90%
|-
|Slate || 11 || 0% || 76.66 || 345 || 54 || 90%
|-
|Marble || 14 || 0% || 76.66 || 330 || 54 || 90%
|}

Rest effectiveness varies by quality and material. Stone materials only offer 90% of the rest effectiveness of a bed made from non-stone materials at the same quality level.

{| {{STDT| sortable c_08 text-center}}
! Material
!data-sort-type="number"| Awful
!data-sort-type="number"| Poor
!data-sort-type="number"| Normal
!data-sort-type="number"| Good
!data-sort-type="number"| Excellent
!data-sort-type="number"| Masterwork
!data-sort-type="number"| Legendary
|-
|Non-stone materials|| 86% || 92% || 100% || 108% || 114% || 125% || 160%
|-
|Stone materials|| 77% || 83% || 90% || 97% || 103% || 113% || 144%
|}

{{see also|Hospital bed}}

<noinclude>
{{nav|furniture|wide}}
</noinclude>
[[Category:Furniture]]
[[Category:Environment]]

Modding Tutorials/Custom Comp Classes

2018-11-29T19:46:17Z

Lilwhitemouse: /* C# */

Modding Tutorials/Custom Comp Classes

2018-11-29T19:37:43Z

Lilwhitemouse: duplicate comps can cause problems :p

Modding Tutorials/Custom Comp Classes

2018-11-29T17:06:29Z

Lilwhitemouse:

Modding Tutorials/Custom Comp Classes

2018-11-29T17:01:34Z

Lilwhitemouse: look at thingcomp

Modding Tutorials/Custom Comp Classes

2018-11-29T16:57:38Z

Lilwhitemouse: more C#

Modding Tutorials/Custom Comp Classes

2018-11-29T16:45:40Z

Lilwhitemouse: C#

Modding Tutorials/Custom Comp Classes

2018-11-29T16:17:24Z

Lilwhitemouse: Fixed formatting :p