Modding Tutorials/Xml Patches

From RimWorld Wiki
Revision as of 05:40, 10 August 2023 by Zeta18 (talk | contribs) (→‎Operation: Changed to using the xml lang formating)
Jump to navigation Jump to search

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 a read the previous tutorial.

Goal of this tutorial

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

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

Patching

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

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

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

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

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.

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

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

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

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

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

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

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.


Enjoy your new explosive assault rifle.


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

Github

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

Next Tutorial

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