Editing Modding Tutorials/Plague Gun (1.1)
Jump to navigation
Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
− | This is a | + | This tutorial is a rewrite of the [[Plague Gun/Introduction|original]] by Jecrell ({{LudeonThread|33219}}), updated to 1.1 by dninemfive. |
== Introduction == | == Introduction == | ||
− | In this tutorial we will be using most of the tools available to a Rimworld | + | 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 | + | 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. | + | 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. | 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. | ||
Line 14: | Line 14: | ||
=== The Completed Mod === | === The Completed Mod === | ||
− | + | ||
+ | TODO: fork and update the repo, link here. | ||
== Required Items == | == Required Items == | ||
Line 22: | Line 23: | ||
{| class="wikitable" | {| 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://notepad-plus-plus.org/ Notepad++] or [https://atom.io Atom] or{{br}}[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://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. | ||
Line 29: | Line 30: | ||
|} | |} | ||
− | For more detailed recommendations, see [[Modding Tutorials/Recommended software|here] | + | For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]]. |
== XML Stage == | == XML Stage == | ||
Line 35: | Line 36: | ||
In this stage we will set up the mod and create XML files which add our things to the database. | 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}}<small>RimWorld>Mods>PlagueGun</small> |
− | + | #* 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. | #* Go into the Mods folder. | ||
#* Make a new folder with our mod's title: '''PlagueGun''' | #* Make a new folder with our mod's title: '''PlagueGun''' | ||
− | # Inside '''PlagueGun''', make an '''About''' folder. | + | # Inside '''PlagueGun''', make an '''About''' folder.{{br}}<small>RimWorld>Mods>PlagueGun>About</small> |
− | + | # Inside the '''About''' folder, make a new text file and rename it About.xml.{{br}}<small>RimWorld>Mods>PlagueGun>About>About.xml</small> | |
− | |||
− | # Inside the '''About''' folder, make a new text file and rename it 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. | #* 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.'' | #* 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> | #* Then add the MetaData tags for the Workshop and in-game Mod list.<source lang ="xml"><ModMetaData> | ||
Line 66: | Line 56: | ||
</source> | </source> | ||
#* Save the file. | #* Save the file. | ||
− | # Add a Preview.png or Preview.jpeg to your '''About''' folder. | + | # Add a Preview.png or Preview.jpeg to your '''About''' folder.{{br}}<small>RimWorld>Mods>PlagueGun>About>Preview.png</small> |
− | |||
− | |||
#* This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop. | #* 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. | #* The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb. | ||
#* Example: [[File:Preview.png]] | #* Example: [[File:Preview.png]] | ||
− | # Make a '''Defs''' folder in your Mod's directory. | + | # Make a '''Defs''' folder in your Mod's directory.{{br}}<small>RimWorld>Mods>PlagueGun>Defs</small> |
− | |||
− | |||
#* 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. | #* 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]] | #* 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. | #** 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. | + | # Make a new '''ThingDefs''' folder in your '''Defs''' folder.{{br}}<small>RimWorld>Mods>PlagueGun>Defs>ThingDefs</small> |
− | + | # Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.{{br}}<small>RimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml</small> | |
− | |||
− | # Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml. | ||
− | |||
− | |||
#* This file will contain the blueprints (ThingDefs) for our new gun and bullets. | #* 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. | #* 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 | + | #* In RimWorld, it is often best to use the XML attribute ParentName="BaseBullet" when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: [[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> | # First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> | ||
− | # Add the | + | # Add the <Defs> opening and closing tags to the XML to hold our new code.<source lang = "xml> |
<?xml version="1.0" encoding="utf-8"?> | <?xml version="1.0" encoding="utf-8"?> | ||
<Defs> | <Defs> | ||
Line 95: | Line 77: | ||
</source> | </source> | ||
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file. | # Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file. | ||
− | #* Find in Files is | + | #* For me, Find in Files is a function I use repeatedly. 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: | + | #* So, start by using Find in Files... and find this: defName>Bullet_Revolver |
− | #* When you find Bullet_Revolver, copy from its beginning | + | #* When you find Bullet_Revolver, copy from its beginning <ThingDef> all the way until its closing </ThingDef> tag into your XML File. |
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to 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. | #* 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. | #* 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 defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique. | ||
− | #* ''' | + | #* '''Change the <defaultProjectile> 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 <defaultProjectile> 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 | + | #* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <defName>Tobacco</defName>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <defName>VGP_Tobacco</defName> and <defName>ROM_Tobacco</defName>, 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. | #* 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 | + | <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 texturePath to your unique art, and whatever else. |
=== Completed Example === | === Completed Example === | ||
− | ''Note'': The example is up-to-date for [[Version|1. | + | ''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"> | <source lang ="xml"> | ||
<?xml version="1.0" encoding="utf-8" ?> | <?xml version="1.0" encoding="utf-8" ?> | ||
Line 122: | Line 104: | ||
</graphicData> | </graphicData> | ||
<projectile> | <projectile> | ||
+ | <flyOverhead>false</flyOverhead> | ||
<damageDef>Bullet</damageDef> | <damageDef>Bullet</damageDef> | ||
<damageAmountBase>12</damageAmountBase> | <damageAmountBase>12</damageAmountBase> | ||
Line 137: | Line 120: | ||
<graphicClass>Graphic_Single</graphicClass> | <graphicClass>Graphic_Single</graphicClass> | ||
</graphicData> | </graphicData> | ||
− | |||
<soundInteract>Interact_Revolver</soundInteract> | <soundInteract>Interact_Revolver</soundInteract> | ||
− | |||
<statBases> | <statBases> | ||
<WorkToMake>4000</WorkToMake> | <WorkToMake>4000</WorkToMake> | ||
Line 153: | Line 134: | ||
<li>Revolver</li> | <li>Revolver</li> | ||
</weaponTags> | </weaponTags> | ||
− | |||
− | |||
− | |||
<costList> | <costList> | ||
<Steel>30</Steel> | <Steel>30</Steel> | ||
Line 200: | Line 178: | ||
</source> | </source> | ||
− | == C# | + | == C# Assembly Setup == |
{{Main|Modding Tutorials/Setting up a solution}} | {{Main|Modding Tutorials/Setting up a solution}} | ||
Line 206: | Line 184: | ||
# Open your compiler of choice for C#. | # Open your compiler of choice for C#. | ||
− | #* This tutorial will assume you're using Visual Studio Community | + | #* 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 | # 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). | #* File → New → Project → Class Library (.NET Framework). | ||
Line 215: | Line 193: | ||
#* Forgetting to do this will cause lots of errors. | #* Forgetting to do this will cause lots of errors. | ||
#* Select Yes when it asks you if you're sure to change the framework. | #* 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 | # Change the output path to be RimWorld\Mods\PlagueGun\Assemblies | ||
#* All .dll files will go into this directory when we "build" our code library. | #* All .dll files will go into this directory when we "build" our code library. | ||
Line 224: | Line 202: | ||
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent. | #* 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. | # In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference. | ||
− | # Click Browse | + | # Click Browse and go to RimWorld\RimWorldWin64_Data\Managed |
− | # Add references to Assembly-CSharp.dll | + | # Add references to Assembly-CSharp.dll and UnityEngine.CoreModule.dll |
− | #* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module. | + | #* 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 the core module. |
− | |||
− | |||
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list. | # 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. | # 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 | + | # Do this (Copy Local to FALSE) for 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! | #* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice! | ||
Line 237: | Line 213: | ||
'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod. | '''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |