Modding Tutorials/Plague Gun (1.1)

This tutorial is a rewrite of the original by Jecrell (Thread), updated to 1.1 by dninemfive.

Introduction

In this tutorial we will be using most of the tools available to a Rimworld modder to create a custom weapon, known as the Plague Gun.

This weapon will, when its shots hit a living target, have a chance to apply the Plague hediff ("health difference") to that target.

To do this, we will create XML `ThingDefs` for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.

This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.

If you have no XML or C# experience, there are good tutorials for XML here and C# here.

The Completed Mod

TODO: fork and update the repo, link here.

Required Items

Make sure to have the following installed, at least one per row:

Notepad++ or Atom orTemplate:BrSublimetext or VSCode	Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
Visual Studio Community	Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
dnSpy or ILSpy	This is for referencing the game's decompiled C# scripts.

For more detailed recommendations, see here.

XML Stage

In this stage we will set up the mod and create XML files which add our things to the database.

1. Create a mod folder.Template:BrRimWorld>Mods>PlagueGun
   • Go to your RimWorld's base folder. For myself, that is D:\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C:\Program Files (x86)\Steam\steamapps\common\RimWorld or a custom directory.
   • Go into the Mods folder.
   • Make a new folder with our mod's title: PlagueGun

1. Inside PlagueGun, make an About folder.Template:BrRimWorld>Mods>PlagueGun>About

1. Inside the About folder, make a new text file and rename it About.xml.Template:BrRimWorld>Mods>PlagueGun>About>About.xml
   • You will need a good text editor to make a proper XML file -- see required items. I always make a .txt file first and change it to .xml. If you can't rename your file's type, make sure you have filetypes visible in your operating system's file view settings.
   • About.xml is the file that shows your mod in the mod list inside the RimWorld game. It is also used when creating a Workshop upload for Steam.
   • At the top of an XML file, always include this for RimWorld.

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

     Note: the version tag should always be "1.0". It has no relation with the current RimWorld version.
   • Then add the MetaData tags for the Workshop and in-game Mod list.

     <ModMetaData>
       <name>Test Mod - Plague Gun</name> <!-- The name of your mod in the mod list -->
       <author>YourNameHere</author>
       <packageId>YourNameHere.PlagueGun</packageId> <!-- a unique identifier for your mod. Must contain only a-z and periods, no spaces. -->
       <supportedVersions> <!-- the version(s) your mod supports -->
         <li>1.1</li>
       </supportedVersions>
       <description>This mod adds a plague gun, a weapon that has a chance to give your enemies the plague.\n\nFor version 1.1.</description>
     </ModMetaData>

   • Save the file.

1. Add a Preview.png or Preview.jpeg to your About folder.Template:BrRimWorld>Mods>PlagueGun>About>Preview.png
   • This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop.
   • The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb.
   • Example:

1. Make a Defs folder in your Mod's directory.Template:BrRimWorld>Mods>PlagueGun>Defs
   • RimWorld will read your XML files in any subdirectory of Defs. You can name your directories however you like under that folder. Defs>StrangeNewAlienGuns>MyGuns.xml will work. For the purposes of this tutorial, however, we will use the RimWorld standard structure.
   • What are Defs? Main article: Defs
     • RimWorld uses things called Defs (short for "definitions") like blueprints for in-game objects. Instead of using hidden C# code, RimWorld will look up an XML Def and copy it to the game world. This makes things easier for us, the modders. Everything from characters, animals, floors, damages, buildings, and even diseases in RimWorld use Defs. We're going to make Defs for our Plague Gun and Plague Bullet.

1. Make a new ThingDefs folder in your Defs folder.Template:BrRimWorld>Mods>PlagueGun>Defs>ThingDefs
2. Make a new text file in your ThingDefs folder, and change it to RangedWeapon_PlagueGun.xml.Template:BrRimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml
   • This file will contain the blueprints (ThingDefs) for our new gun and bullets.
   • Next we will fill out our XML file by copying an existing revolver's ThingDef and a revolver bullet ThingDef.
   • In RimWorld, it is often best to use the XML attribute ParentName="BaseBullet" when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: Inheritance