Difference between revisions of "Modding Tutorials/Xml Patches"

From RimWorld Wiki
Jump to navigation Jump to search
(Fixed case sensitivity on <xpath> tags.)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{BackToTutorials}}
 
{{BackToTutorials}}
  
This page is a tutorial on how to create a Rimworld mod it will step you through the process of creating a mod from scratch. from basic file structure to writing code for your mod. This tutorial is aimed at people who have never created a mod before and are looking to get started. and is meant to be an updated guide to the old tutorials on the wiki.
+
This page is a tutorial on how to create a RimWorld mod, it will step you through the process of creating a mod from scratch. From basic file structure to writing code for your mod. This tutorial is aimed at people who have never created a mod before and are looking to get started. And is meant to be an updated guide to the old tutorials on the wiki.
  
This is a follow-up to my [[Modding Tutorials/Xml_Adding_Weapons_Traits_Research|previous tutorial]] on how to make a mod. if you have not:
+
This is a follow-up to my [[Modding Tutorials/Xml_Adding_Weapons_Traits_Research|previous tutorial]] on how to make a mod. If you have not:
 
# Started adding items with XML
 
# Started adding items with XML
 
# Added basic traits
 
# Added basic traits
 
# Added and linked research
 
# Added and linked research
  
Then you should go back a read the [[Modding_Tutorials/Getting_started_with_mods|previous tutorial]].
+
Then you should go back and read the [[Modding_Tutorials/Getting_started_with_mods|previous tutorial]].
  
 
=Goal of this tutorial=
 
=Goal of this tutorial=
By the end of this tutorial you will have:
+
By the end of this tutorial, you will have:
 
# Made a patch for an existing item
 
# Made a patch for an existing item
 
# Making the assault rifle even more powerful
 
# Making the assault rifle even more powerful
 
  
 
=Useful Tools=
 
=Useful Tools=
There are a few tools that will make your life easier when modding Rimworld.
+
There are a few tools that will make your life easier when modding RimWorld.
 
# [https://github.com/Zeta-of-the-rim/Rimwold-Dotnet-Template Rimworld dotnet template] is a mod template that can be used to quickly set up a mod.
 
# [https://github.com/Zeta-of-the-rim/Rimwold-Dotnet-Template Rimworld dotnet template] is a mod template that can be used to quickly set up a mod.
# [https://raw.githubusercontent.com/Zeta-of-the-rim/RimWorld-Mod-Tutorials/master/2.%20Wepons%20and%20Traits/CodeSnippets.json Rimworld code snippets] is a collection of code snippets that can be used to quickly add code to your mod.
+
# [https://raw.githubusercontent.com/Zeta-of-the-rim/RimWorld-Mod-Tutorials/master/2.%20Wepons%20and%20Traits/CodeSnippets.json RimWorld code snippets] is a collection of code snippets that can be used to quickly add code to your mod.
# On any game map with dev mode click the Magnifying glass on the top of the screen will open the Debug inspector. Next to the visibility button is a toggle for "Deep inspection mode" This will allow you to see the XML of any object in the game. This can be used to find the XPath for any value in the game.
+
# On any game map with dev mode, click the Magnifying glass at the top of the screen will open the Debug inspector. Next to the visibility button is a toggle for “Deep inspection mode” This allows you to see the XML of any object in the game. This can be used to find the XPath for any value in the game.
 
=Patching=
 
=Patching=
 
Patching is the process of adding or changing existing values in the game. For simple mods, this can be done with XML.
 
Patching is the process of adding or changing existing values in the game. For simple mods, this can be done with XML.
  
==Patching with xml==
+
==Patching with XML==
For this tutorial, we will be making the vanilla revolver do 100 damage instead of 12. To do this we will need to patch the revolver's stats.
+
For this tutorial, we will be making the vanilla revolver do 100 damage instead of 12. To do this, we will need to patch the revolver's stats.
 
===Code Block===
 
===Code Block===
<pre>
+
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
 
 
<Patch>
 
<Patch>
 
     <Operation Class="PatchOperationReplace">
 
     <Operation Class="PatchOperationReplace">
Line 37: Line 35:
 
     </Operation>
 
     </Operation>
 
</Patch>
 
</Patch>
</pre>
+
</source>
</br>
+
'''''If using the code snippets, use "rwpatch" to generate the basic XML. '''''
'''''If using the code snippets use "rwpatch" to generate the basic XML. ''''' </br>
 
  
 
===Breakdown===
 
===Breakdown===
To start we add the XML header and the patch tag.
+
To start, we add the XML header and the patch tag.
 
====Operation====
 
====Operation====
The operation tag is used to tell the game what we want to do with the patch. In this case, we want to use the PatchOperationReplace class. This class will replace the value of the xpath with the value tag.
+
The operation tag is used to tell the game what we want to do with the patch. In this case, we want to use the PatchOperationReplace class. This class will replace the value of the XPath with the value tag.
  
what is happening is that the game is looking for the xpath and replacing the value with the value tag.  
+
What is happening is that the game is looking for the XPath and replacing the value with the value tag.  
 
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
 
{| class="wikitable" style="margin-left: auto; margin-right: auto;"
 
! Our Patch !! Before !! After
 
! Our Patch !! Before !! After
 
|-
 
|-
| style="vertical-align: top;" |<pre>
+
| style="vertical-align: top;" |<source lang="xml">
 
<Operation Class="PatchOperationReplace">
 
<Operation Class="PatchOperationReplace">
 
     <xpath>/Defs/ThingDef[defName = "Bullet_Revolver"]/projectile/damageAmountBase</xpath>
 
     <xpath>/Defs/ThingDef[defName = "Bullet_Revolver"]/projectile/damageAmountBase</xpath>
Line 57: Line 54:
 
     </value>
 
     </value>
 
</Operation>
 
</Operation>
</pre>
+
</source>
| style="vertical-align: top;" |<pre>
+
| style="vertical-align: top;" |<source lang="xml">
 
<projectile>
 
<projectile>
 
     <damageDef>Bullet</damageDef>
 
     <damageDef>Bullet</damageDef>
Line 65: Line 62:
 
     <speed>55</speed>
 
     <speed>55</speed>
 
</projectile>
 
</projectile>
</pre>
+
</source>
 
| style="vertical-align: top;" |<source lang="xml">
 
| style="vertical-align: top;" |<source lang="xml">
 
<projectile>
 
<projectile>
Line 76: Line 73:
 
|-
 
|-
 
|}
 
|}
====xpath====
+
 
The xpath tag needs to point to the value you want to change and must be the exact path including all tags the value is in. Because of this, it is best to find the value you want to change in its XML file before you start on the patch. This will make it easier to find the xpath (Remember the Defs of the base game and its DLCs are found in the Data folder in the game folder). This method can also change the values of any mod that uses XML to add content to the game.  
+
====XPath====
 +
The XPath tag needs to point to the value you want to change and must be the exact path including all tags the value is in. Because of this, it is best to find the value you want to change in its XML file before you start on the patch. This will make it easier to find the XPath (Remember, the Defs of the base game and its DLCs are found in the Data folder in the game folder). This method can also change the values of any mod that uses XML to add content to the game.  
  
 
====value====
 
====value====
Now you have pointed to the value you want to change, it's time to change it. The value tag is where you put the new value. As we are using "PatchOperationReplace" anything in the value tag will replace the value of the xpath.
+
Now you have pointed to the value you want to change, it's time to change it. The value tag is where you put the new value. As we are using "PatchOperationReplace" anything in the value tag will replace the value of the XPath.
  
 
==Patching Sequence==
 
==Patching Sequence==
Now that we have a basic understanding of how to patch the game with xml let's look at a more complex example. for this example, we will make the assault rifle fire explosive bullets. To do this we will need to patch the assault rifle's stats and add a new projectile.
+
Now that we have a basic understanding of how to patch the game with XML, let's look at a more complex example. For this example, we will make the assault rifle fire explosive bullets. To do this, we will need to patch the assault rifle's stats and add a new projectile.
  
 
===Making the explosive bullet===
 
===Making the explosive bullet===
 
First, we need to make a new projectile that will be used by the assault rifle.  
 
First, we need to make a new projectile that will be used by the assault rifle.  
<pre>
+
<source lang="xml">
<ThingDef ParentName="BaseBullet"> <!-- even though this is an explosive it is still a bullet -->
+
<ThingDef ParentName="BaseBullet"> <! --even though this is an explosive, it is still a bullet -->
 
     <defName>mm_Twist</defName>
 
     <defName>mm_Twist</defName>
 
     <label>explosive</label>
 
     <label>explosive</label>
Line 105: Line 103:
 
     </projectile>
 
     </projectile>
 
</ThingDef>
 
</ThingDef>
</pre>
+
</source>
</br>
 
 
Just like the previous tutorial but with a few changes.
 
Just like the previous tutorial but with a few changes.
  
# In "DamageDef" instead of using "Bullet" we are using "Bomb" This will make the bullet do explosive damage.
+
# In "DamageDef" instead of using “Bullet” we are using “Bomb” This will make the bullet do explosive damage.
 
# The bullet has "explosionRadius", "arcHeightFactor" and "shadowSize" these are the values that control the explosion.
 
# The bullet has "explosionRadius", "arcHeightFactor" and "shadowSize" these are the values that control the explosion.
  
 
===Patching the assault rifle===
 
===Patching the assault rifle===
Now that we have a new projectile we need to patch the assault rifle to use it.
+
Now that we have a new projectile, we need to patch the assault rifle to use it.
<pre>
+
<source lang="xml">
 
<Operation Class="PatchOperationSequence">
 
<Operation Class="PatchOperationSequence">
 
     <success>Normal</success>
 
     <success>Normal</success>
Line 136: Line 133:
 
     </operations>
 
     </operations>
 
</Operation>
 
</Operation>
</pre>
+
</source>
</br>
+
<br>
  
 
===Breakdown===
 
===Breakdown===
By using the "PatchOperationSequence" class we can make a patch that does multiple things. The first thing we do is replace the default projectile of the assault rifle with our new explosive bullet. However now that the assault rifle is using an explosive bullet we need to add a few more values to the assault rifle's XML. This is done by using the "PatchOperationAdd" class. By entering the xpath of the assault rifle's verbs we can add a forced miss radius and allow the assault rifle to target locations.
+
By using the "PatchOperationSequence" class we can make a patch that does multiple things. The first thing we do, is replacing the default projectile of the assault rifle with our new explosive bullet. However, now that the assault rifle is using an explosive bullet, we need to add a few more values to the XML file of the assault rifle. “This is done by using the "PatchOperationAdd" class. By entering the XPath of the assault rifle's verbs, we can add a forced miss radius and allow the assault rifle to target locations.
 
 
</br>
 
 
Enjoy your new explosive assault rifle.
 
Enjoy your new explosive assault rifle.
 
 
  
 
==Other Patching Operations==
 
==Other Patching Operations==
There are a few other patching operations that can be used to change the values of the game. While you can get away with using Add, Remove, and Replace for most basic patches there are a few other operations that can be used to make more complex patches. It can be useful to familiarize yourself with these [[Modding_Tutorials/PatchOperations| operations]].
+
There are a few other patching operations that can be used to change the values of the game. While you can get away with using Add, Remove, and Replace for most basic patches, there are a few other operations that can be used to make more complex patches. It can be useful to familiarize yourself with these [[Modding_Tutorials/PatchOperations| operations]].
  
=Github=
+
=GitHub=
As with the previous tutorial example code with comments can be found on [https://github.com/Zeta-of-the-rim/RimWorld-Mod-Tutorials github].
+
As with the previous tutorial, example code with comments can be found on [https://github.com/Zeta-of-the-rim/RimWorld-Mod-Tutorials github].
  
 
=Next Tutorial=
 
=Next Tutorial=

Latest revision as of 06:53, 6 May 2024

Modding Tutorials

This page is a tutorial on how to create a RimWorld mod, it will step you through the process of creating a mod from scratch. From basic file structure to writing code for your mod. This tutorial is aimed at people who have never created a mod before and are looking to get started. And is meant to be an updated guide to the old tutorials on the wiki.

This is a follow-up to my previous tutorial on how to make a mod. If you have not:

  1. Started adding items with XML
  2. Added basic traits
  3. Added and linked research

Then you should go back and read the previous tutorial.

Goal of this tutorial[edit]

By the end of this tutorial, you will have:

  1. Made a patch for an existing item
  2. Making the assault rifle even more powerful

Useful Tools[edit]

There are a few tools that will make your life easier when modding RimWorld.

  1. Rimworld dotnet template is a mod template that can be used to quickly set up a mod.
  2. RimWorld code snippets is a collection of code snippets that can be used to quickly add code to your mod.
  3. On any game map with dev mode, click the Magnifying glass at the top of the screen will open the Debug inspector. Next to the visibility button is a toggle for “Deep inspection mode” This allows you to see the XML of any object in the game. This can be used to find the XPath for any value in the game.

Patching[edit]

Patching is the process of adding or changing existing values in the game. For simple mods, this can be done with XML.

Patching with XML[edit]

For this tutorial, we will be making the vanilla revolver do 100 damage instead of 12. To do this, we will need to patch the revolver's stats.

Code Block[edit]

<?xml version="1.0" encoding="utf-8"?>
<Patch>
    <Operation Class="PatchOperationReplace">
        <xpath>/Defs/ThingDef[defName = "Bullet_Revolver"]/projectile/damageAmountBase</xpath>
        <value>
            <damageAmountBase>100</damageAmountBase>
        </value>
    </Operation>
</Patch>

If using the code snippets, use "rwpatch" to generate the basic XML.

Breakdown[edit]

To start, we add the XML header and the patch tag.

Operation[edit]

The operation tag is used to tell the game what we want to do with the patch. In this case, we want to use the PatchOperationReplace class. This class will replace the value of the XPath with the value tag.

What is happening is that the game is looking for the XPath and replacing the value with the value tag.

Our Patch Before After
<Operation Class="PatchOperationReplace">
    <xpath>/Defs/ThingDef[defName = "Bullet_Revolver"]/projectile/damageAmountBase</xpath>
    <value>
        <damageAmountBase>100</damageAmountBase>
    </value>
</Operation>
<projectile>
    <damageDef>Bullet</damageDef>
    <damageAmountBase>12</damageAmountBase>
    <stoppingPower>1</stoppingPower>
    <speed>55</speed>
</projectile>
<projectile>
    <damageDef>Bullet</damageDef>
    <damageAmountBase>100</damageAmountBase>
    <stoppingPower>1</stoppingPower>
    <speed>55</speed>
</projectile>

XPath[edit]

The XPath tag needs to point to the value you want to change and must be the exact path including all tags the value is in. Because of this, it is best to find the value you want to change in its XML file before you start on the patch. This will make it easier to find the XPath (Remember, the Defs of the base game and its DLCs are found in the Data folder in the game folder). This method can also change the values of any mod that uses XML to add content to the game.

value[edit]

Now you have pointed to the value you want to change, it's time to change it. The value tag is where you put the new value. As we are using "PatchOperationReplace" anything in the value tag will replace the value of the XPath.

Patching Sequence[edit]

Now that we have a basic understanding of how to patch the game with XML, let's look at a more complex example. For this example, we will make the assault rifle fire explosive bullets. To do this, we will need to patch the assault rifle's stats and add a new projectile.

Making the explosive bullet[edit]

First, we need to make a new projectile that will be used by the assault rifle.

<ThingDef ParentName="BaseBullet"> <! --even though this is an explosive, it is still a bullet -->
    <defName>mm_Twist</defName>
    <label>explosive</label>
    <graphicData>
        <texPath>Things/Projectile/LauncherShot</texPath>
        <graphicClass>Graphic_Single</graphicClass>
        <shaderType>TransparentPostLight</shaderType>
    </graphicData>
    <thingClass>Projectile_Explosive</thingClass>
    <projectile>
        <speed>35</speed>
        <damageDef>Bomb</damageDef> <!-- using the vanilla bomb damage -->
        <explosionRadius>1.5</explosionRadius>
        <arcHeightFactor>0.2</arcHeightFactor>
        <shadowSize>0.6</shadowSize>
    </projectile>
</ThingDef>

Just like the previous tutorial but with a few changes.

  1. In "DamageDef" instead of using “Bullet” we are using “Bomb” This will make the bullet do explosive damage.
  2. The bullet has "explosionRadius", "arcHeightFactor" and "shadowSize" these are the values that control the explosion.

Patching the assault rifle[edit]

Now that we have a new projectile, we need to patch the assault rifle to use it.

<Operation Class="PatchOperationSequence">
    <success>Normal</success>
    <operations>
        <li Class="PatchOperationReplace">
            <xpath>/Defs/ThingDef[defName = "Gun_AssaultRifle"]/verbs/li/defaultProjectile</xpath>
            <value>
                <defaultProjectile>mm_Twist</defaultProjectile>
            </value>
        </li>
        <!-- Now we need to add the Defs that explosive bullets need -->
        <li Class="PatchOperationAdd">
            <xpath>/Defs/ThingDef[defName = "Gun_AssaultRifle"]/verbs/li</xpath>
            <value>
                <forcedMissRadius>1.9</forcedMissRadius>
                <targetParams>
                    <canTargetLocations>true</canTargetLocations>
                </targetParams>
            </value>
        </li>
    </operations>
</Operation>


Breakdown[edit]

By using the "PatchOperationSequence" class we can make a patch that does multiple things. The first thing we do, is replacing the default projectile of the assault rifle with our new explosive bullet. However, now that the assault rifle is using an explosive bullet, we need to add a few more values to the XML file of the assault rifle. “This is done by using the "PatchOperationAdd" class. By entering the XPath of the assault rifle's verbs, we can add a forced miss radius and allow the assault rifle to target locations. Enjoy your new explosive assault rifle.

Other Patching Operations[edit]

There are a few other patching operations that can be used to change the values of the game. While you can get away with using Add, Remove, and Replace for most basic patches, there are a few other operations that can be used to make more complex patches. It can be useful to familiarize yourself with these operations.

GitHub[edit]

As with the previous tutorial, example code with comments can be found on github.

Next Tutorial[edit]

Next, we will look at a couple of frameworks that allow you to make advanced mods easier.