Modding Tutorials/Xml Adding Weapons Traits Research

< 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 files 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 a 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. Set up a mod folder structure
2. Created an About.xml file
3. Added a new item to the game
4. Tested the mod in game using the Debug menu

Then you should go back a read the previous tutorial.

Goal of this tutorial

By the end of this tutorial you will have:

1. Created a weapon with custom stats
2. Learned how to add sounds to your mod
3. Learned how to add a new trait to the game
4. Learned how to create a new research project
5. Learned how to create a new recipe

lets get started.

Mod template

Rimworld dotnet template is a mod template that can be used to quickly set up a mod. as by now you should have a basic understanding of how mods work it is recommended to use the template to save time. If you want to do things manually thats fine (Your life).

Visual Studio Code Snippets

In order to make modding easier I have created a set of code snippets for Visual Studio Code. These snippets will help you create the Xml structure for your mod. To use these snippets open VsCode then:

File -> Preferences -> Configure User Snippets -> XML

this will open a file called xml.json. copy this code and paste it into the xml.json file. save the file and you are ready to go.

This will allow you to type "rwweapon" to generate the skeleton for a new weapon. you can then fill in the details for your weapon.

Creating a new weapon

The first thing we are going to do is create a new weapon.

Creating the xml file

Start by creating a new file in the Defs folder called "ThingDefs_Weapons.xml". this is where we will put the xml for our new weapon.
Start by adding the Xml header to the file.

<?xml version="1.0" encoding="utf-8" ?>

If using VsCode simply type "rwxml" and press tab to generate the header.

Making a bullet def

Before we can make a weapon there needs to be a bullet that the weapon can fire.

<Defs>
    <ThingDef ParentName="BaseBullet">
        <defName>MM_Bullet</defName>
        <label>Tutorial Bullet</label>
        <graphicData>
            <texPath>Things/Projectile/Bullet_Small</texPath> 
            <!-- unlike the other tutorials, we are using a pre-existing texture that is already in the game. -->  
            <graphicClass>Graphic_Single</graphicClass>
            <drawSize>1.1</drawSize> <!-- bigger the number, bigger the bullet -->
        </graphicData>
        <projectile>
            <!-- Now we define the projectiles damage. -->
            <damageDef>Bullet</damageDef>
            <damageAmountBase>10</damageAmountBase>
            <stoppingPower>1</stoppingPower>
            <speed>44</speed>
        </projectile>
    </ThingDef>
</Defs>

If you added the code snippets you can save time by typing "rwbullet" and pressing tab. this will generate the skeleton for the bullet, you can then fill in the details (pushing tab will move you to the next field).

Making a weapon def

Note: The weapon def is long and extremely picky with spelling, formatting and capitalization. if you have not added the code snippets I recommend you add them now.

Awesome we now have a bullet but we need a weapon to fire it. for now lets uses sounds and textures that are already in the game.

Code Block

<ThingDef ParentName="BaseHumanMakeableGun">
        <defName>MM_Our_Gun</defName>
        <label>Tutorial Gun</label>
        <description>A simple gun for learning purposes. (Mod learning purposes dont give it to a child or something)</description>
        <graphicData>
            <texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
            <graphicClass>Graphic_Single</graphicClass>
        </graphicData>
        <uiIconScale>1.4</uiIconScale>
        <soundInteract>Interact_Revolver</soundInteract>
        <!-- Now we define the weapon's stats. -->
        <statBases>
            <WorkToMake>2000</WorkToMake>
            <Mass>1.6</Mass>
            <AccuracyTouch>0.95</AccuracyTouch>
            <AccuracyShort>0.90</AccuracyShort>
            <AccuracyMedium>0.80</AccuracyMedium>
            <AccuracyLong>0.70</AccuracyLong>
            <RangedWeapon_Cooldown>1.5</RangedWeapon_Cooldown>
        </statBases>
        <!-- now we define the weapon's tags. -->
        <weaponTags>
            <li>SimpleGun</li>
            <li>Revolver</li>
        </weaponTags>
        <!-- Now we choose what will be used to make the weapon. -->
        <costList>
            <Steel>10</Steel>
            <Plasteel>1</Plasteel>
            <ComponentIndustrial>1</ComponentIndustrial>
        </costList>
        <!-- Now the weapon's requirements. -->
        <recipeMaker>
            <skillRequirements>
                <Crafting>5</Crafting>
            </skillRequirements>
        </recipeMaker>
        <!--verbs are what the weapon does. -->
        <verbs>
            <li>
                <verbClass>Verb_Shoot</verbClass>
                <hasStandardCommand>true</hasStandardCommand>
                <!-- Now we define the Bullet the weapon uses. -->
                <defaultProjectile>MM_Bullet</defaultProjectile>
                <warmupTime>0.9</warmupTime>
                <burstShotCount>3</burstShotCount>
                <ticksBetweenBurstShots>22</ticksBetweenBurstShots>
                <range>20</range>
                <soundCast>Shot_Revolver</soundCast>
                <soundCastTail>GunTail_Light</soundCastTail>
                <muzzleFlashScale>8</muzzleFlashScale>
            </li>
        </verbs>
        <!-- nice, we have shooting, but what happens when we get in melee? -->
        <tools>
            <li>
                <label>handle</label>
                <capacities>
                    <li>Blunt</li>
                </capacities>
                <power>7</power>
                <cooldownTime>3.1</cooldownTime>
            </li>
            <!-- you can add lots of melee but we will just add two. -->
            <li>
                <label>barrel</label>
                <capacities>
                    <li>Blunt</li>
                    <li>Poke</li>
                </capacities>
                <power>5</power>
                <cooldownTime>2.1</cooldownTime>
            </li>
        </tools>
    </ThingDef> 

If using the code snippets use "rwweapon" to generate the skeleton for the weapon.

Code Breakdown

Thats a lot of code so lets break it down.

Names and Description

<ThingDef ParentName="BaseHumanMakeableGun">
        <defName>MM_Our_Gun</defName>
        <label>Tutorial Gun</label>
        <description>A simple gun for learning purposes.</description>

We start by defining the weapon as a makeable gun. Then we give it a gameId (defName), a user friendly name (label) and a description.

Textures and Sounds

            
<graphicData>
    <texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
    <graphicClass>Graphic_Single</graphicClass>
</graphicData>
<uiIconScale>1.4</uiIconScale>
<soundInteract>Interact_Revolver</soundInteract>

now we define the texture (in this case we have specified the vanilla revolver texture) and the sound the weapon makes when a pawn picks it up.

Stats and Tags

<statBases>
    <WorkToMake>2000</WorkToMake>
    <Mass>1.6</Mass>
    <AccuracyTouch>0.95</AccuracyTouch>
    <AccuracyShort>0.90</AccuracyShort>
    <AccuracyMedium>0.80</AccuracyMedium>
    <AccuracyLong>0.70</AccuracyLong>
    <RangedWeapon_Cooldown>1.5</RangedWeapon_Cooldown>
</statBases>
<!-- now we define the weapon's tags. -->
<weaponTags>
    <li>SimpleGun</li>
    <li>Revolver</li>
</weaponTags>

The stats are the weapons weight and its accuracy at different ranges.

Requirements and Cost

<costList>
    <Steel>10</Steel>
    <Plasteel>1</Plasteel>
    <ComponentIndustrial>1</ComponentIndustrial>
</costList>
<recipeMaker>
    <skillRequirements>
        <Crafting>5</Crafting>
    </skillRequirements>
</recipeMaker>

As we are using BaseHumanMakeableGun the weapon will be at a machining table. We define the resources and skill required to make the weapon.

Verbs

<verbs>
    <li>
        <verbClass>Verb_Shoot</verbClass>
        <hasStandardCommand>true</hasStandardCommand>
        <!-- Now we define the Bullet the weapon uses. -->
        <defaultProjectile>MM_Bullet</defaultProjectile>
        <warmupTime>0.9</warmupTime>
        <burstShotCount>3</burstShotCount>
        <ticksBetweenBurstShots>22</ticksBetweenBurstShots>
        <range>20</range>
        <soundCast>Shot_Revolver</soundCast>
        <soundCastTail>GunTail_Light</soundCastTail>
        <muzzleFlashScale>8</muzzleFlashScale>
    </li>
</verbs>

The verbs define (in this case) the how the weapon shoots. We define the projectile we made earlier, the warmup time and the burst shot count. Verbs is also where you define the range and shooting sound.

Melee

<tools>
    <li>
        <label>handle</label>
        <capacities>
            <li>Blunt</li>
        </capacities>
        <power>7</power>
        <cooldownTime>3.1</cooldownTime>
    </li>
</tools>

In this case the tools are used to define the melee attacks of the weapon. Making sure to enclose each attack in a "li" tag give your attack a label, define the damage type, how much damage it does and lastly give it a cooldown time.

Before we forget we need to close the "ThingDef"

</ThingDef>

Final Notes

And with that we have a working weapon with a custom bullet and recipe. to improve the weapon you could add a custom sound and texture or change the stats to your liking. The best way to learn is to experiment or look at other mods (I recommend looking at Vanilla Weapons Expanded as their mods keep the code clean and tidy).

Adding a Research Project

Currently the weapon is unlocked by default. Lets add a research project to unlock it.

Making the File

While we could add the research project to the same file as the weapon it is good practice to keep things tidy. So let's make a new file in the "Defs" folder called "ResearchProjectDef.xml"
Remember to add the Xml header and "Defs" tag. (Remember this can be done with "rwxxml")

Adding the Research Project

The Xml for the research project is shorter than the weapon however it still requires correct spelling and syntax.

Code Block

<ResearchProjectDef>
    <defName>tutorial_Research</defName>
    <label>My Mods Research</label>
    <description>Craft the mithical tutorial gun.</description>
    <baseCost>500</baseCost>
    <techLevel>Industrial</techLevel>
    <prerequisites>
        <li>Gunsmithing</li>
    </prerequisites>
    <researchViewX>9.00</researchViewX>
    <researchViewY>4.80</researchViewY>
</ResearchProjectDef>

If using the code snippets use "rwresearch"

Code Breakdown

Ok lets break down the code.

Names and Description

<defName>tutorial_Research</defName>
<label>My Mods Research</label>
<description>Craft the mithical tutorial gun.</description>

Just like the weapon we give the project a gameId, and a user friendly name and a description.

Cost, Tech Level and Prerequisites

<techLevel>Industrial</techLevel>
<prerequisites>
    <li>Gunsmithing</li>
</prerequisites>

The tech level will scale the cost of the research project based on the colony's tech level (Tribal starts will be more expensive than crashlanded). the baseCost is the cost of the project before scaling for tech level. prerequisites are the research projects that must be completed before this project can be researched. (In this case we are requiring Gunsmithing)

Position

<researchViewX>9.00</researchViewX>
<researchViewY>4.80</researchViewY>

This is the position of the project in the research tree. This may take some trial and error to get right (Or you could use a mod like "ResearchPowl" that makes the tree easier to navigate)

Locking the Weapon

Right we have a research project but we need to tell the game to use it. to do this we need to edit our weapons recipeMaker.

<recipeMaker>
    <skillRequirements>
        <Crafting>5</Crafting>
    </skillRequirements>
    <researchPrerequisite>tutorial_Research</researchPrerequisite>
</recipeMaker>

By simply adding the researchPrerequisite tag and giving it the gameId of the research project we have locked the weapon behind the research project.

Adding New Traits

Traits are a great way to add new gameplay mechanics to your mod. For now we will be adding a trait that makes the colonist have a higher Crafting skill and lower carrying capacity.

Making the File

To keep things tidy we will make a new file in the "Defs" folder called "TraitDef.xml" (Remember to add the Xml header and "Defs" tag. [Remember this can be done with "rwxxml"])

Adding the Trait

The Xml for the trait is quite straight forward once you know what each tag does (for code snippets use "rwtrait")

Code Block

<TraitDef>
    <defName>Epic_crafting</defName>
    <commonality>1</commonality>
    <disabledWorkTags>
        <li>Animals</li>
    </disabledWorkTags>
    <degreeDatas>
        <li>
            <label>Epic Crafting</label>
            <description>[PAWN_nameDef] excels at crafting. [PAWN_pronoun] can carry heavy things and crafts very well</description>
            <degree>1</degree>
                <statOffsets>
                    <CarryingCapacity>25</CarryingCapacity>
                    <WorkSpeedGlobal>0.20</WorkSpeedGlobal>
                </statOffsets>
                <skillGains>
                    <li><key>Crafting</key><value>4</value></li>
                </skillGains>
        </li>
    </degreeDatas>
</TraitDef>

Code Breakdown

Right, let's break down the code.

Basic Tags

<defName>Epic_crafting</defName>
<commonality>1</commonality>

Like the other defs we give the trait a gameId however this time we also give it a commonality. This is the chance that the trait will be given to a colonist. also note that the Label and Description are inside the degreeDatas tag and not the main tag.

Disabled Work Tags

<disabledWorkTags>
    <li>Animals</li>
</disabledWorkTags>

Disabling work tags is a great way to make traits more unique. In this case we are disabling the animals work type. Remember to put all the work tags you want to disable inside their own <li> tag.

Degree Data

<degreeDatas>
    <li>
        <label>Epic Crafting</label>
        <description>[PAWN_nameDef] excels at crafting. [PAWN_pronoun] can carry heavy things and crafts very well</description>
        <degree>1</degree>
        <statOffsets>
            <CarryingCapacity>25</CarryingCapacity>
            <WorkSpeedGlobal>0.20</WorkSpeedGlobal>
        </statOffsets>
        <skillGains>
            <li><key>Crafting</key><value>4</value></li>
        </skillGains>
    </li>
</degreeDatas>

The degree data is where we define the effects of the trait. This also includes the label (player friendly name) and description. Stat offsets are changes to the colonists stats. In this case we are increasing the colonists carrying capacity by 25 and increasing work speed by 20%. Skill gains are static increases to the colonists skills. In this case we are increasing the colonists crafting skill by 4.

Final Notes About Traits

The Trait In Game

Congratulations you have made your first trait. for now it only changes stats and skills however traits can do a lot more. The best way to learn about the more advanced possibilities is to look at other mods that add traits.

Github

As with the other tutorials I have made I have the example mods on github for you to download and look at.

Next Steps

Now that you have made a mod with content you can start to look at more advanced topics such as adding new buildings, and starting to use frameworks like Vanilla Expanded Framework.