RimWorld Wiki - User contributions [en]

Modding Tutorials

2020-10-20T23:39:46Z

Dninemfive: Update plague gun link

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

This is the table of contents for the modding tutorial. Here, you'll learn step by step how to create mods of gradually increasing complexity.

In light of little official documentation, most of the knowledge here was gained by experience, trial-and-error, decompiling and learning from the source. Keep in mind that RimWorld is a big game that underwent substantial code changes during its alphas. While most of this wiki was updated for 1.0, some information you find may be outdated.

-----

==What's a mod?==
A mod is a folder containing data the game reads/loads. Mods can add, remove or alter the content of other mods (including the Core mod) in the broadest sense of the word. For more info, see also [[Modding]].

==Introduction to modding==
# [[Modding Tutorials/First Steps|First Steps and Some Links]]
# [[Modding Tutorials/Essence| Essence of Modding]]
# [[Modding Tutorials/Folder structure|Exploring the Folder Structure]]
# [[Modding Tutorials/Mod folder structure|Mod Folder Structure]]
#* [[Modding Tutorials/Mod folder structure#The About folder|About folder]]
#* [[Modding Tutorials/Mod folder structure#The Defs folder|Defs folder]]
#* [[Modding Tutorials/Mod folder structure#The Source and Assemblies folders|Assemblies folder]]
#* [[Modding Tutorials/Mod folder structure#The Languages folder|Languages folder]]
#* [[Modding Tutorials/Mod folder structure#The Textures and Sounds folders|Textures folder]]
#* [[Modding Tutorials/Mod folder structure#The Textures and Sounds folders|Sounds folder]]
#* [[Modding Tutorials/Mod folder structure#The Patches folder|Patches folder]]
# [[Modding Tutorials/Recommended software|Recommended Software]]

==General modding==

* [[Modding Tutorials/Testing mods|Testing Mods]]
** [[Modding Tutorials/Testing mods#Development mode|Development Mode]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]

==Must-knows==
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]

==XML tutorials==

# [[Modding Tutorials/XML file structure|XML File Structure]]
# [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
#* [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
# In-depth XML Def tutorials
#* [[Modding Tutorials/ThingDef|ThingDef explained]]
#* [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.
# [[Modding Tutorials/PatchOperations|PatchOperations]], replace specific xml elements of core files while keeping the rest untampered. Uses xpath.

==C# tutorials==
# [[Modding_Tutorials/Setting up a solution|Setting up]]
# [[Modding_Tutorials/Hello World|Hello World]]
# [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]]
# [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
# [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
# [[Modding_Tutorials/Harmony | Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
# The wonderful things you will want to do with C#
#* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
# Useful things:
#* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
#* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
#* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
#** [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
#** [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
#* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
#* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
#* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
#* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
#* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
#* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
#* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.

==Art Tutorials==
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

 
==Examples==
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.

===Dangerously Outdated===
* https://rimworldwiki.com/wiki/Modding_Tutorials/Smelter
* https://rimworldwiki.com/wiki/Modding_Tutorials/Items
* https://rimworldwiki.com/wiki/Modding_Tutorials/Weapons
* [[Plague Gun/Introduction|The Plague Gun]] based on the Plague Gun tutorial by Jecrell, updated for 1.0. {{LudeonThread|33219}}.
# [[Plague Gun/Required Items|Required Items]]
# [[Plague Gun/XML Stage|XML Stage]]
# [[Plague Gun/Connecting XML and Csharp|Connecting XML and C#]]
# [[Plague Gun/Csharp Assembly Setup|C# Assembly Setup]]
# [[Plague Gun/Csharp Coding|C# Coding]]
# [[Plague Gun/Localisation|Localisation]]

==See also==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

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

User:Dninemfive

2020-09-14T02:07:17Z

Dninemfive: Delete a single apostrophe

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== IfModLoaded ===
You can use the <code>IfModLoaded</code> and <code>IfModNotLoaded</code> attributes in <code>LoadFolders.xml</code> to conditionally load defs, treating Royalty as a mod.
<source lang="xml">
<loadFolders>
<default>
<li>/</li>
<li IfModLoaded="Royalty">RoyaltyDefs</li>
</default>
</loadFolders>
</source>
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* [O21] Toolbox
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* OgsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

User:Dninemfive

2020-09-14T01:51:05Z

Dninemfive: /* Introduction to reading Def classes */

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields'''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== IfModLoaded ===
You can use the <code>IfModLoaded</code> and <code>IfModNotLoaded</code> attributes in <code>LoadFolders.xml</code> to conditionally load defs, treating Royalty as a mod.
<source lang="xml">
<loadFolders>
<default>
<li>/</li>
<li IfModLoaded="Royalty">RoyaltyDefs</li>
</default>
</loadFolders>
</source>
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* [O21] Toolbox
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* OgsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

User:Dninemfive

2020-09-14T00:17:14Z

Dninemfive: Add IfModLoaded

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Modding Tutorials/Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields'''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== IfModLoaded ===
You can use the <code>IfModLoaded</code> and <code>IfModNotLoaded</code> attributes in <code>LoadFolders.xml</code> to conditionally load defs, treating Royalty as a mod.
<source lang="xml">
<loadFolders>
<default>
<li>/</li>
<li IfModLoaded="Royalty">RoyaltyDefs</li>
</default>
</loadFolders>
</source>
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* [O21] Toolbox
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* OgsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

Modding Tutorials/Recommended software

2020-09-02T06:32:08Z

Dninemfive: update .NET version

{{BackToTutorials}}
 

=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 some are better suited than others. Rich text editors (WordPad, anything part of any Office suite) should be avoided. Windows' simple notepad will work, but you'll want something which offers things like "Find in Files" functionality and syntax highlighting. If you're even somewhat serious about modding, the following software will help you immensely: 

{| class="wikitable"
! Software !! OS !! Description
|-
| [https://notepadqq.com/s/ 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 || Light-weight editor with extension support.
|-
| [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]
|-
| [https://atom.io/ Atom] || Linux/Windows/Mac || A hackable electron-based text editor with emphasis on extensions and GitHub collaboration.
|-
| [https://code.visualstudio.com/ Visual Studio Code] || Linux/Windows/Mac || A text editor with emphasis on productivity and extension support.
|-
| [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])
|} 
An alternative to "Advanced editors" are plugins/extensions. Good extensions can highlight syntax (if not already standard), format XML, find xpath, auto-close XML tags, supports renaming tags, and more.
 

=IDEs=

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] which is free for individuals and small teams. Always the most up-to-date
|-
| [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 4.7.2. If you for whatever reason don't have this framework installed, you can download it [https://dotnet.microsoft.com/download/dotnet-framework/net472 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]]

User:Dninemfive

2020-08-05T05:34:02Z

Dninemfive: /* Sandbox */

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Modding Tutorials/Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields'''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* [O21] Toolbox
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* OgsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

Modding Tutorials/Plague Gun

2020-07-26T06:29:47Z

Dninemfive: fix INCREDIBLY INCORRECT lack of newlines

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun
{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
{
}
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-07-26T06:27:35Z

Dninemfive: fix EXTREMELY GLARING typo

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

User:Dninemfive

2020-07-20T22:12:40Z

Dninemfive: /* Framework Mods */

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Modding Tutorials/Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields'''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* OgsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

User:Dninemfive

2020-07-16T23:35:45Z

Dninemfive: /* Sandbox */

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Introduction to reading Def classes ==
This article is intended for XML modders who don't want to work with C# (even though it's [[Modding Tutorials/Plague Gun (1.1)|much less imposing than you think]]) but want to know what exactly they can write in their defs.

=== Definitions ===
'''Fields'''' are variables in C# class defintions defined at the top of classes (when decompiled). For example, <source lang="csharp">
public class ExampleDef : Def {
public bool exampleBool = true;
public int exampleInteger = 1;
public float exampleFloat = 1.2f;
public bool exampleNonInitializedField;
public RaceProperties exampleClass;
}
</source>

'''Nodes''' are XML entries, for example <source lang="xml">
<ExampleDef ExampleAnnotation="ExampleValue">
<exampleBool>true</exampleBool?
<exampleInteger>1</exampleInteger>
<exampleFloat>1.2</exampleFloat>
<exampleNonInitializedField>false</exampleNonInitializedField>
<exampleClass>
<intelligence>Animal</intelligence>
<fleshType>Mechanoid</fleshType>
<hasGenders>false</hasGenders>
</exampleClass>
</ExampleDef>
</source>

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

User:Dninemfive

2020-07-07T03:40:45Z

Dninemfive: /* Framework Mods */

Hello! I'm a modder who's trying to clean up the modding tutorials pages, which are quite out-of-date. So far, I've [[Plague Gun (1.1)|rewritten]] the classic [[Plague Gun/Introduction|Plague Gun tutorial]].

If you've been helped by my contributions on this site please check out my mods on [https://github.com/users/dninemfive/projects/1 Github] and [https://steamcommunity.com/id/dninemfive/myworkshopfiles/?appid=294100 Steam].

= Sandbox =

== Royalty compatibility ==
After the release of Royalty, mods are governed by rules 13b and c of the [https://ludeon.com/forums/index.php?topic=40838.0 Ludeon community rules]. Unfortunately, these are inconsistently applied and end up being vaguer than intended, but a good TL;DR to follow would be:
# Don't use any code flagged as Royalty only. They will throw errors when loaded for people without Royalty, so these are easy to tell.
#* The page lists explicit exceptions; at the time of writing, only gendered apparel and <code>Sketch</code>es are exempt.
# Avoid using features added in 1.1 or later. Unfortunately, not all Royalty-specific code is flagged and it's ambiguous whether some features are permitted.
# Avoid making anything included in Royalty, broadly defined. Another unfortunate ambiguity is the nuance in this rule - it's currently unclear whether some Royalty features, like shield projectors, count as "royalty features" for this purpose as old mods which included them have not been banned but no new ones have yet been made.
# If in doubt, set your mod to require Royalty to install on Steam, and you'll be fine.
=== MayRequire ===
You can use the <code>MayRequire</code> annotation on XML nodes to disable Royalty-specific features when Royalty is not installed.
=== ModLister.RoyaltyInstalled ===
In C#, the canonical check for whether Royalty is installed is <code>ModLister.RoyaltyInstalled</code>. Notably, this check whether the Steam user ''owns'' Royalty, rather than whether it's enabled in the load order.
=== Other Options ===
If you set your mod to require [https://github.com/dninemfive/d9framework D9 Framework], you can use <code>PatchOperationFindPackage</code> (with the packageId <code>Ludeon.RimWorld.Royalty</code>) or <code>PatchOperationRoyaltyInstalled</code> to check whether Royalty is installed, with the former checking whether it's enabled and the latter checking if the user owns it. Using the vanilla <code>PatchOperationFindMod</code> would not be sufficient because it would be enabled if any local mod was called Royalty.

== Framework Mods ==
''intended to be a comprehensive list of mods which add features for XML users''
* Advanced Animal Frameworks
* BiomesKit
* D9 Framework
* HugsLib ''(I think)''
* JecsTools
* Universal Fermenter

== Version Control Intro ==

An introduction to using Github for version control, with an eye toward Rimworld modding. Will go through my particular setup, and various tips and tricks, like:
* Having a separate dev folder from the Rimworld mods folder
* Build events copying from the dev folder into the build folder
* .gitignore settings
&c

== Example Comp Project ==

This project will teach players how to use <code>ThingComp</code>s, load textures in C#, and make gizmos.

== Introduction to core mods ==

This project will teach players how to use basic Harmony patches and demonstrate the use of <code>MapComponent</code>s (or maybe game/world ones, idk)

User:Dninemfive

2020-07-06T16:35:45Z

Dninemfive: /* Royalty compatibility */

User:Dninemfive

2020-07-05T22:31:05Z

Dninemfive: /* Framework Mods */

User:Dninemfive

2020-07-05T22:29:06Z

Dninemfive: /* Sandbox */

User:Dninemfive

2020-07-05T22:24:55Z

Dninemfive: /* Royalty compatibility */

User:Dninemfive

2020-07-05T22:24:45Z

Dninemfive: /* Royalty compatibility */

User:Dninemfive

2020-07-05T22:15:42Z

Dninemfive: /* Royalty compatibility */

User:Dninemfive

2020-07-05T22:15:15Z

Dninemfive: /* Sandbox */

Modding Tutorials/Plague Gun

2020-07-01T04:05:49Z

Dninemfive: fix Discord invite

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

User:Dninemfive

2020-06-27T21:48:37Z

Dninemfive: typo

User:Dninemfive

2020-06-27T21:48:20Z

Dninemfive: /* Sandbox */

Modding Tutorials/Plague Gun

2020-06-27T06:10:35Z

Dninemfive: capitalize

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Setting up a solution

2020-06-27T06:07:47Z

Dninemfive: 3.5 -> 4.7.2 (and remove reference to it being ancient)

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

=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 4.7.2 (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"
## Click "OK" to close the Reference Manager.
## Right click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Automatic Method):====
This option uses the [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool.
'''Note: despite being automatic and potentially taking away some of the tedium away, the environment it sets up is very particular and this tool is currently not recommended for newcomers.'''
''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 4.7.2:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 4.7.2",
# 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 .NET4.7.2 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 4.7.2 can be found (for Linux anyway) in the same place.

More detailed installation instructions for Linux can be found [https://blog.rubenwardy.com/2016/07/21/rimworld-setup-monodevelop/ here] and [https://spdskatr.github.io/RWModdingResources/mono-arch here].

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

=Common issues=
* Can't find the option to target .NET Framework 4.7.2? It may require additional installation steps. In Visual Studio, Tools => Get Tools and features => Individual Components => Select ''.NET Framework 4.7.2 development tools'' (or google installation instructions). Also make sure your project is a ''Class Library (.NET '''Framework''')''. Not .NET Core or .NET Standard.

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

[[Category:Modding tutorials]]

Modding Tutorials/Setting up a solution

2020-06-27T06:06:33Z

Dninemfive: .NET 3.5 -> 4.7.2

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

=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 4.7.2 (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"
## Click "OK" to close the Reference Manager.
## Right click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Automatic Method):====
This option uses the [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool.
'''Note: despite being automatic and potentially taking away some of the tedium away, the environment it sets up is very particular and this tool is currently not recommended for newcomers.'''
''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 4.7.2:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 4.7.2",
# 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 .NET4.7.2 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 4.7.2 can be found (for Linux anyway) in the same place.

More detailed installation instructions for Linux can be found [https://blog.rubenwardy.com/2016/07/21/rimworld-setup-monodevelop/ here] and [https://spdskatr.github.io/RWModdingResources/mono-arch here].

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

=Common issues=
* Can't find the option to target .NET Framework 3.5? Due to its age, it may require additional installation steps. In Visual Studio, Tools => Get Tools and features => Individual Components => Select ''.NET Framework 3.5 development tools'' (or google installation instructions). Also make sure your project is a ''Class Library (.NET '''Framework''')''. Not .NET Core or .NET Standard.

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

[[Category:Modding tutorials]]

Modding Tutorials/Plague Gun

2020-06-19T23:33:01Z

Dninemfive: Add note about commenting, per JC and Garthor

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:26:14Z

Dninemfive: remove yet another digression

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:22:06Z

Dninemfive: Add link to ModExtensions page at Jamaican Castle's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:20:26Z

Dninemfive: Remove digression about property at Garthor's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:12:39Z

Dninemfive: Delete "base"

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:09:39Z

Dninemfive: Reword another note, at Garthor's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:07:54Z

Dninemfive: Reword a note, at Garthor's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T23:03:51Z

Dninemfive: Standardize on camelCase, at Garthor's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between addHediffChance and hediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.addHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:59:53Z

Dninemfive: Clarify defNames, at Garthor's recommendation

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:52:15Z

Dninemfive: Explain the RimWorld folder location better, at Garthor's suggestion

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:14:56Z

Dninemfive: link my name bc why not

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by [[User:Dninemfive|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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:11:59Z

Dninemfive: Formatting tweak: remove backticks

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:11:19Z

Dninemfive: Formatting tweak: add missing <code> block

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/First Steps

2020-06-19T22:07:41Z

Dninemfive: Link to the updated Plague Gun tutorial

{{BackToTutorials}}
----

Roaring to go? [[Plague Gun (1.1)|Here's a good tutorial that introduces a lot of things gradually]]. Want to take it slow? Smart. It's '''strongly''' recommended to do the following before you start making a mod:

= Step 1: Search for a mod already doing what you want =

Seriously. There are so many mods, there is generally one, probably of high quality, doing what you want it to. You might not need to make a mod!

* Search [https://steamcommunity.com/workshop/about/?appid=294100 Steam's Workshop]. These have ready to go and managed by Steam mods. Click to use them.
* Check the [https://ludeon.com/forums/index.php?board=12.0 RimWorld Mod Forum]
* Use [http://google.com Google] because it works.
* Ask on [https://discord.gg/RimWorld Discord] or [https://reddit.com/r/RimWorld reddit] to see if they know of one.

= Step 2: Read Other Info On Modding =

* [[Modding | RimWorld Wiki - Modding ]]
* [[Modding_Tutorials | RimWorld Wiki - Modding Tutorials]]
* [https://ludeon.com/forums/index.php?board=14.0 RimWorld Forum - Modding Help]
* Tynan's Readme.txt in your Rimworld directory (in RimWorldMac.app for Mac people)

= Step 3: One Time Reads =

* [[Modding_Tutorials/XML_file_structure | RimWorld Wiki - XML file structure and loading]]
* [[Modding_Tutorials/Testing_mods | RimWorld Wiki - Testing]]
* A17 Modding Updates - https://ludeon.com/forums/index.php?topic=32735.0 - by ZorbaTHut

= Step 4: Useful Links, Reference Constantly =

* [[Modding_Tutorials/Folder_structure | Wiki - Folder Structure]]
* [https://ludeon.com/forums/index.php?board=14.0 Ludeon Forum - Modding Help]
* [https://github.com/RimWorldMod/RimworldModdingFiles RimWorld XML Database] - xml explained for XML modders

= Step 5: Tutorials by Others =

* How to make a .dll-mod (Power Generation) - https://ludeon.com/forums/index.php?topic=3408.0

= Step 6: Reference the works of others =

It's how most of us learned how2mod.

* Core. If it's (close to) something that already exists in RimWorld, use what RimWorld provides you. What better source of "how to do X" than the game itself?
* Maybe there's some inspiration [https://spdskatr.github.io/RWModdingResources/telephonebook on this list of modders and their GitHub links]
* Use [https://github.com/search?q=RimWorld+worldcomponent&type=Code GitHub search] to find how other modders handled a problem
* Use [http://google.com Google] because it works.

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

Modding Tutorials/Plague Gun

2020-06-19T22:07:09Z

Dninemfive: /* See also */

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

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

Modding Tutorials/Plague Gun

2020-06-19T22:06:07Z

Dninemfive: Finish(?) article

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/rimworld Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

[[Category: Modding tutorials]]
[[Category: Modding]]
[[Category: Plague Gun]]

Modding Tutorials/Plague Gun

2020-06-19T21:59:14Z

Dninemfive: Finish localization section

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:{{br}}Languages>English>Keyed
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

Modding Tutorials/Plague Gun

2020-06-19T21:48:59Z

Dninemfive: ...well, almost

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

Modding Tutorials/Plague Gun

2020-06-19T21:48:24Z

Dninemfive: Actually finish projectile section

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
}
}
}
}</source>

Modding Tutorials/Plague Gun

2020-06-19T21:46:10Z

Dninemfive: Formatting

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
* Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

Modding Tutorials/Plague Gun

2020-06-19T21:45:01Z

Dninemfive: Finish projectile section, I think

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ===
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <thingClass> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.AddHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.AddHediffChance), 12f);
}
</source>
#* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
#* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.
# Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

Modding Tutorials/Plague Gun

2020-06-19T21:36:10Z

Dninemfive: /* Writing the Projectile */

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing)
{
base.Impact(hitThing);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>

Modding Tutorials/Plague Gun

2020-06-19T21:33:58Z

Dninemfive: More projectile stuff

This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), 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 [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

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

{| class="wikitable"
|-
| [https://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or [https://www.sublimetext.com/ Sublimetext] or [https://code.visualstudio.com/ VSCode] || Use any text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/0xd4d/dnSpy/releases dnSpy] or [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

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

# Create a mod folder.{{br}}RimWorld>Mods>PlagueGun
#* Go to your RimWorld's base folder. For myself, that is D<nowiki>:</nowiki>\SteamLibrary\steamapps\common\RimWorld\. Others may find it in C<nowiki>:</nowiki>\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'''
# Inside '''PlagueGun''', make an '''About''' folder.{{br}}RimWorld>Mods>PlagueGun>About
# Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}RimWorld>Mods>PlagueGun>About>About.xml
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|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. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''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.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<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>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}RimWorld>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: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.{{br}}RimWorld>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: [[Modding Tutorials/XML Defs|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.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}RimWorld>Mods>PlagueGun>Defs>ThingDefs
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}RimWorld>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 <code>ParentName="BaseBullet"</code> 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: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''Change the <code><defaultProjectile></code> tag inside the PlagueGun's Verbs to use the defName of your bullet (TST_Bullet_PlagueGun)'''. Failing to do this will result in a no errors, but your gun will shoot regular bullets (and not give the plague effect). {{br}}Once again, under the verbs. Please make sure <code><defaultProjectile></code> references the bullet. e.g.<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.1]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<flyOverhead>false</flyOverhead>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<soundInteract>Interact_Revolver</soundInteract>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# Go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# Change Debugging Information to none.
#* This prevents a simple error that occurs when RimWorld doesn't know what to do with the debug .pdb files.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun;
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
# First, let's add a way to read XML data into your assembly.
#* '''Note:''' Previous versions of this tutorial used a custom class inheriting ThingDef, which was the standard at the time, but this one will use a ModExtension, which is much less prone to various mod conflicts.
# Rename public class Class1 to ModExtension_Plaguebullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float AddHediffChance = 0.05f;
public HediffDef HediffToAdd;
</source>
#* Here, we're giving the field AddHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Personally, I give fields which are exposed to XML camelCase names, instead of the PascalCase used here, for consistency with vanilla XML. You can do either; this format was retained from earlier versions of this tutorial.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<AddHediffChance>0.05</AddHediffChance>
<HediffToAdd>Plague</HediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' This is the key intuition of pretty much this entire tutorial. The fields you set in classes exposed to XML, like ModExtensions, are directly and automatically filled by the base game by their names. Notice the exact correspondence between AddHediffChance and HediffToAdd between the C# and XML.
#* Additionally, take care to note you can set the value of AddHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. However, it's much easier to navigate when you have a separate file for separate concepts.
#* I tend to only keep closely related classes (such as ThingComps and their associated CompProperties) together in the same file; in most cases, you should only have one or two classes per file.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
#* It also isn't ''strictly'' necessary, but do you really want to retype or copy-and-paste the right-hand side of that expression over and over?
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.AddHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
#* You could avoid declaring the <code>rand</code> variable (i.e. doing <code>if (Rand.Value <= Props.AddHediffChance)</code>), since it's not used later, but there's no harm in declaring it.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.HediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.HediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

Modding Tutorials/Plague Gun

2020-06-19T21:01:17Z

Dninemfive: fix typo

Modding Tutorials/Plague Gun

2020-06-19T21:00:31Z

Dninemfive: Formatting pass: add <code/> blocks in various places

Modding Tutorials/Plague Gun

2020-06-19T20:54:48Z

Dninemfive: A bit more