Editing Modding Tutorials/Getting started with mods

{{BackToTutorials}}

This page is a tutorial on how to create a RimWorld mod, it will step you through the process of creating a mod from scratch. From basic file structure to writing code for your mod. This tutorial is aimed at people who have never created a mod before and are looking to get started. And is meant to be an updated guide for the old tutorials on the wiki. If you're still facing issues after using this tutorial, head over to the [https://discord.gg/rimworld/ RimWorld Discord server]. In the server, there's a Modding Resources section where you might find help if you're stuck during mod creation.

=Introduction=
RimWorld mods are created using XML and C# code. XML is used to define the content of the mod, and C# is used to add functionality to the mod, and also to modify existing items. For now, we will focus on XML and later tutorials will cover C#. Tweaks are mostly done with XML; new mechanics uses C#. New weapons, creatures and armor - learn to draw, preferably in vector and use XML or C#, depending on thing's complexity. To get started, we will create the basic files and folders that are needed for a mod. We will then add some basic content to the mod and test it in the game.

=Goal of this tutorial=
By the end of this tutorial, you will have:
# Install software needed to make a mod
# Create a mod folder structure
# Edit the About.xml file
# Add a new item to the game
# Test the mod in-game using the Debug menu

=Software=
To get started making a mod with XML, you will need to download/choose the following (program):

* RimWorld base game (official License) From Ludeon.com or GOG, Steam or Epic Gamestore.
* Code editor like Notepad++ or Visual Studio (Code)
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1847679158 RimPy] (This is a Mod manager that will make it easier to test your mod)
* [https://git-scm.com/ Git] can be scary at first, but it is a very useful tool. And can be used to keep track of changes to your mod. (Optional but highly recommended)
* GitHub account; Using GitHub repositories for handling small mod changes and fixing bugs helps mod creators easily keep track of their modifications.

==Code Editor==
There are many code editors out there, some of the most commonly used are:
* [https://code.visualstudio.com/ Visual Studio Code] is a free code editor and has a lot of useful features and tools You can add extensions tools to make coding work easier (this is what we will use in this tutorial).
* [https://visualstudio.microsoft.com/ Visual Studio] you can get the Windows, MAC or Linux version, a program made by Microsoft.
* [https://notepad-plus-plus.org/ Notepad++] is a very lightweight code editor that is very easy to use, however it is missing some features that make it less useful for larger projects. It is easy to use when you are a beginner in coding.
* [https://www.sublimetext.com/ Sublime Text] is a free code editor that is popular.

'''''About IDEs:'''''
IDEs are Integrated Development Environments. They are a code editor and a compiler all in one. They are very useful for larger projects, but can be overkill for smaller projects. IDEs are also very resource intensive and can slow down your computer. I would recommend using a simple code editor for now and when you are ready to start using C# you can look into IDEs.

=Making the folder structure=
'''''There are mod templates available for quick setup, however it is recommended to create the folder structure manually at least once to get a better understanding of how mods work.'''''
To start making a mod, we need to create a folder for the mod. This folder will contain all the files and folders that make up the mod. To keep things organized, we will create a folder in RimWorld's mod local folder. This is located at:
<pre>(RimWorldInstallFolder)/Mods/</pre>
'''''Note: it is not recommended to put your mod in the steam mods' folder''''' since it is a local mod and not yet published on the Steam workshop.

==Making an "about” file. ==
Now let's make an About folder inside the mod folder. This folder will contain information about the mod and the mods preview image.
Inside the About folder, we will create a file called About.xml. This file will contain information about the mod. Inside the file, we will add the following code:
<pre>
<?xml version="1.0" encoding="UTF-8"?> <! -- Comments in XML look like this-->
</pre>
This is the first line of every XML file. It tells the computer that this is an XML file and what encoding to use. Get used by putting this line in every XML file you make)<br>
now we will add the following code to the file:
<pre>
<ModMetaData>
<name>Mod Name Here</name> <!-- This is the name of the mod -->
    <author>Your Name Here</author> 
    <packageId>yourName.ModName</packageId> <!-- It is best to use this format-->
    <description>This mod will make your life on the Rim more enjoyable.</description> <!-- Be creative, the description is what people will see when they look at your mod and don't leave space between description tags -->
    <supportedVersions>
     <li>1.4</li>
    </supportedVersions> <!-- This is the version of RimWorld that the mod is compatible with -->
</ModMetaData> <!-- be sure to close all tags you open -->
</pre>
'''''XML is picky about spacing, formatting, and Capitalization. If you get an error when loading your mod, it is most likely because of a typo or missing <tag> or forgot the closing </tag>.'''''
Now save the file and close it. '''Note: the name of the file must be exactly "About.xml"'''
Open RimPy and sort by local mods. You should see your mod listed. If you click on it, you should see the information you have entered in the About.xml file. <br>
'''''When adding a preview image to your mod you must name the image "Preview.png" and place it in the About folder, the image resolution should be 512×512 pixels and the size must be under 2mb''''' 

==Creating the other folder==
Now let's make a Def's folder inside the mod folder. This folder will contain all the XML files that define the content the mod will add.<br>
Start by creating a folder called "Defs" inside the mod folder, inside the Defs folder create a file called "ThingDefs.xml" <br>
In the root of the mod folder create a folder called "Patches". this folder will contain XML files that will be used to patch existing content in the game. Inside the Patches folder create a file called "ThingDefs_Patch.xml" <br>
let's also create a folder called "Textures" inside the mod folder. this folder will contain all the images that will be used in the mod.<br>
Your mod folder should now look like this: 
<pre>
ModName
    About
        About.xml
        Preview.png
    Defs
        ThingDefs.xml
    Patches
        ThingDefs_Patch.xml
    Textures
</pre>

=Adding content to the mod=
Now that we have the basic folder structure set up, we can start adding content to the mod.

==Adding a new item==
Remember, this is the first line of every XML file.
<pre>
<?xml version="1.0” encoding="UTF-8”?>
</pre>
Let's start by adding a new item to the game, open the “ThingDefs.xml” file and add the following code:
<pre>
<Defs>
    <ThingDef ParentName="ResourceBase">
        <thingClass>ThingWithComps</thingClass>
        <defName>MM_Resource</defName>
        <label>Resource</label>
        <description>Resource</description>
        <statBases>
            <MarketValue>1</MarketValue>
            <MaxHitPoints>300</MaxHitPoints>
            <Mass>1</Mass>
            <Flammability>0</Flammability>
            <DeteriorationRate>0.1</DeteriorationRate>
            <Beauty>2</Beauty>
        </statBases>
    </ThingDef>
</Defs>
</pre>
Now save the file and close it. In RimPy enable the mod and start the game. When in-game, go to settings and enable [https://rimworldwiki.com/wiki/Development_mode development mode]. On the main menu, you'll see a new button named “Dev quick test.” Clicking it starts a new game on a test map. After the game loads, open the Debug actions menu and click on the “Spawn Thing” button. In the “Spawn Thing” menu, type in the def name of the item you just added. Click on the item, then click anywhere on the map to spawn it. Congratulations, you have just added your first item to the game. [[File:empty_item.png|200px|thumb|right|You have now added a new item to the game.]]

==Adding a texture to the item==
While we have added an item to the game currently, it has no texture and shows a pink box, this means it has no texture yet. We can fix this by adding a corresponding texture to the item. We do this by adding a Texture folder which contains the corresponding ItemName.PNG. Take the example texture from the RimWorld wiki (this means the image will be the correct size and format). The "Animal Gear Base" mod [https://steamcommunity.com/workshop/filedetails/?id=1541438907/ Animal Gear] has folders meant to help you create a mod for animal apparel. In these folders, you'll find an ItemName.png file which can act as placeholder image.<br>
Here's what your texture folder should look like:
<pre>
Textures
    Things
        Item
            Resource
                Resource.png
</pre>
It is best to organize your textures into folders that match the folder structure of the game. After you have added your texture to the mod folder, open the "ThingDefs.xml" file and add the following code to your items ThingDef:
<pre>
<graphicData>
    <texPath>Things/Item/Resource/Resource</texPath>
    <graphicClass>Graphic_Single</graphicClass>
</graphicData>
</pre>
''''''Note how you don't add the file extension to the texture path.'''''' <br>
Now that looks much better! [[File:Adding_Textures.png|200px|thumb|right|Look at that lovely item]]

==Important when adding textures==
* You have the option to use either vector-based programs or grid-based programs. 
* Textures must be exported as PNG files in order for them to be usable within the game. 
* PNG files should not exceed 1 GB in size and can be up to 2 MB per texture.<br>
For optimal performance and visual quality, consider keeping PNG texture files at a moderate resolution that suits your mod's style. Aim for a balance between 2 MB and 10 MB per texture, as larger files might affect loading times.

==Adding more complex properties==
Now that we have added a new item to the game, we can add some more features to it. to start we will make the item rot. open the "ThingDefs.xml" file and add the following code to your items ThingDef:
<pre>
<comps>
     <li Class="CompProperties_Rottable"> <!-- This means that the comp can be rotated -->
        <daysToRotStart>2</daysToRotStart> <!-- This is the number of days it takes for the item to start rotting -->
        <daysToDessicated>3</daysToDessicated> <!-- This is the number of days it takes for the item to start desiccating -->
    </li>
</comps>
</pre>
The best way to learn how to add more features to your items is to look at the existing items in the game. You can find the XML files for the existing items in the RimWorld install folder located at: 
<pre>
steamapps/common/RimWorld/Data/Core (Or any DLC you have) or Games/RimWorld/Data/Core
</pre>
You can for example open the RimWorld/Data/Core/Defs folder in your Code editor to see all the items, to understand its structure. It will be easier to navigate through all the folders.
Also, here you can find a Cheatsheet which you can use for Git commands [https://phoenixnap.com/kb/git-commands-cheat-sheet#ftoc-heading-10/ Cheatsheet]

=GitHub files=
* All the files made in this tutorial can be found [https://github.com/Zeta-of-the-rim/RimWorld-Mod-Tutorials here] on GitHub. this allows you to download the files and use them as a reference when making your own mods.
* Bradson made a Mod template on GitHub, you can clone this to your profile and select is as template when you want to make your first mod. You can find it here: [https://github.com/bbradson/ModTemplate/ Mod template]
GitHub is a great tool for sharing code and is especially useful when you are ready to start programming in C#.

=Next steps=
After completing this tutorial, you'll have a basic understanding of modding in RimWorld. Now, you can begin adding more features to your mod, starting with recipes, weapons, and traits.[[Modding_Tutorials/Xml_Adding_Weapons_Traits_Research|Next Tutorial]]

[[Category:Modding tutorials]]