Difference between revisions of "Modding Tutorials"

From RimWorld Wiki
Jump to navigation Jump to search
(Add my post on getting started with Linux)
(→‎C# Guides: Change XML info to C#)
 
(16 intermediate revisions by 7 users not shown)
Line 5: Line 5:
 
<hr>
 
<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.
+
This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.
  
−
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.  
+
As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.
 +
 
 +
'''NEW: [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod_Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.5. '''THERE MAY BE ANOMALY SPOILERS, YOU HAVE BEEN WARNED.'''
  
 
-----
 
-----
  
−
==What's a mod?==
+
==About RimWorld==
−
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]].
+
RimWorld is a multi-platform game written on Unity 2019.4. However, the Unity Editor is not used for creating mods unless you are creating new shaders.
 +
 
 +
* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
 +
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
 +
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly
 +
* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
 +
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
 +
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
 +
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them directly
 +
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
 +
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
 +
 
 +
===XML Tutorials===
 +
 
 +
The following are step-by-step tutorials for creating basic content mods.
 +
 
 +
Basic Tutorials:
 +
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
 +
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
 +
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
 +
* Custom Animal (Upcoming)
 +
* Simple Building (Upcoming)
 +
* Custom Workbench (Upcoming)
 +
* Custom Drug (Upcoming)
 +
 
 +
Advanced Tutorials:
 +
* Custom Faction (Upcoming)
 +
* Custom Culture (Upcoming)
 +
* Custom Trader Type (Upcoming)
 +
 
 +
===C# Guides===
 +
 
 +
C# is used to create and define custom game behaviors
 +
 
 +
* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
 +
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
 +
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
 +
* Custom Consumable (Upcoming)
 +
* Custom Overlays (Upcoming)
 +
 
 +
===Slightly Outdated===
 +
 
 +
* [[Modding_Tutorials/Plague_Gun_(1.1)|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.
  
−
==Getting Started==
+
===Uploading to Steam Workshop===
−
1. [[Modding_Tutorials/Barebones_Mod|Setting up your first mod]]
+
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
 +
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
 +
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
 +
* If you get a <code>OnItemSubmitted Fail</code> error, this usually means that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
 +
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].
  
−
2. [[Modding_Tutorials/Change_Traits|Changing simple traits of things]]
+
-----
  
−
3. [[Modding_Tutorials/Create_new_thing|Creating a new thing (XML only)]]
+
'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!
  
−
==Introduction to modding==
+
==Outdated / Under Review==
−
# [[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]]
 
−
# [[Modding Troubleshooting Tips and Guides]]
 
  
−
==General modding==
+
The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.
  
 +
* [[Modding Tutorials/First Steps|First Steps and Some Links]]
 +
* [[Modding Tutorials/Essence| Essence of Modding]]
 +
* [[Modding Troubleshooting Tips and Guides]]
 
* [[Modding Tutorials/Testing mods|Testing Mods]]
 
* [[Modding Tutorials/Testing mods|Testing Mods]]
 
** [[Modding Tutorials/Testing mods#Development mode|Development Mode]]
 
** [[Modding Tutorials/Testing mods#Development mode|Development Mode]]
Line 43: Line 81:
 
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
 
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
 
* [[Modding Tutorials/Compatibility|Compatibility]]
 
* [[Modding Tutorials/Compatibility|Compatibility]]
−
* [[Modding_Tutorials/Distribution|Distribution]]</br>
+
* [[Modding_Tutorials/Distribution|Distribution]]
−
 
 
−
==Must-knows==
 
 
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
 
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
 
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
 
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
  
−
==XML tutorials==
+
(Redundant, need to be reviewed and consolidated or removed)
 +
* [[Modding_Tutorials/Getting_started_with_mods|Getting Started With XML]]
 +
* [[Modding_Tutorials/Xml_Adding_Weapons_Traits_Research|Adding a New Weapon, Trait and Research to the game]]
 +
* [[Modding_Tutorials/Xml_Patches|Making Patches using Xml]]
  
−
# [[Modding Tutorials/XML file structure|XML File Structure]]
+
===XML tutorials===
−
# [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
 
−
#* [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
 
−
#* [https://7tsvn.github.io/RimWorld-AutoDocs Auto Documentation]
 
−
# 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/XML file structure|XML File Structure]]
−
# [[Modding_Tutorials/Setting up a solution|Setting up]]
+
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
−
# [[Modding_Tutorials/Hello World|Hello World]]
+
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
−
# [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]]
+
** [[Modding Tutorials/ThingDef|ThingDef explained]]
−
# [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
+
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.
−
# [[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.
 
−
# [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]
 
  
−
==Art Tutorials==
+
===C# tutorials===
 +
* [[Modding_Tutorials/Hello World|Hello World]]
 +
* [[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
 +
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
 +
* [[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.
 +
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
 +
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
 +
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]
 +
 
 +
===Art Tutorials===
 
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
 
* [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://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
Line 90: Line 126:
 
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]
 
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]
  
−
<br/><br/>
+
===Under Construction===
−
==Examples==
+
 
 +
These are currently unfinished and need to be cleaned up or removed
 +
 
 +
* [[Modding Tutorials/Quests]]
 +
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]
 +
 
 +
===Dangerously Outdated===
 +
 
 +
* [[RimWorld 1.3: XML Mod Creation]]
 
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
 
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
 
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.  
 
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.  
 +
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer
  
−
===Dangerously Outdated===
 
 
* [[Modding Tutorials/Smelter]]
 
* [[Modding Tutorials/Smelter]]
 
* [[Modding Tutorials/Items]]
 
* [[Modding Tutorials/Items]]
−
* [[Modding Tutorials/Weapons]]
 
 
* [[Modding Tutorials/Furniture]]
 
* [[Modding Tutorials/Furniture]]
−
* [[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==
+
==External Links==
 
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
 
* [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]
 
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

Latest revision as of 19:35, 23 May 2024

Basics Menus Game Creation Gameplay Pawns Plants Resources Gear Mods
Modding Modding Tutorials

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general Modding hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

NEW: RimWorld 1.5 Mod_Updates - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.5. THERE MAY BE ANOMALY SPOILERS, YOU HAVE BEEN WARNED.

About RimWorld[edit]

RimWorld is a multi-platform game written on Unity 2019.4. However, the Unity Editor is not used for creating mods unless you are creating new shaders.

  • Recommended Software - Editors and other useful software for mod development
  • Mod Folder Structure - Explore the basic folder structure of a mod
    • About.xml - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly
  • Defs - XML Definitions are used to define and configure content in a way that does not require compiling code
    • MayRequire - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
  • Localization - Define text strings used for translations and word lists used in name and text generation
  • PatchOperations - PatchOperations are used to modify XML Defs without overwriting them directly
  • Sounds - (Needs Rewriting) Adding sound files for mods
  • Textures - How to create and add textures to mods

XML Tutorials[edit]

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:

  • Basic Melee Weapon - How to create a basic melee weapon with a texture mask
  • Basic Ranged Weapon - How to create a basic ranged weapon with custom sound effects
  • Basic Plant - How to create a custom plant with both a cultivated and wild variant
  • Custom Animal (Upcoming)
  • Simple Building (Upcoming)
  • Custom Workbench (Upcoming)
  • Custom Drug (Upcoming)

Advanced Tutorials:

  • Custom Faction (Upcoming)
  • Custom Culture (Upcoming)
  • Custom Trader Type (Upcoming)

C# Guides[edit]

C# is used to create and define custom game behaviors

  • Decompiling Source Code - How to set up and use a decompiler to read vanilla game code
  • Setting up a Solution - How to set up a solution for compiling a custom mod assembly
  • Application Startup - Describes the application startup process and the order in which game data is loaded
  • Custom Consumable (Upcoming)
  • Custom Overlays (Upcoming)

Slightly Outdated[edit]

  • Plague Gun - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

Uploading to Steam Workshop[edit]

  • You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
  • Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
  • Your Preview.png should be a 640x360 or 1280x720 PNG and must be under 1MB. If it is too large, then your upload will be rejected with Error : Limit Exceeded
  • If you get a OnItemSubmitted Fail error, this usually means that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
  • Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the Steam text formatting guide.

Note: All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the RimWorld Discord in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

Outdated / Under Review[edit]

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

(Redundant, need to be reviewed and consolidated or removed)

XML tutorials[edit]

C# tutorials[edit]

Art Tutorials[edit]

Under Construction[edit]

These are currently unfinished and need to be cleaned up or removed

Dangerously Outdated[edit]

External Links[edit]

Retrieved from "https://rimworldwiki.com/index.php?title=Modding_Tutorials&oldid=146048"