Modding Tutorials/Modifying defs
This tutorial shows you several ways to modify existing Defs and alternatives to changing the XML format for them.
There are several ways to achieve this goal. The table below is the TL;DR version of this article. C# related operations are marked bold.
| Method | Pros | Cons | When to use |
|---|---|---|---|
| Overwrite the Def | Braindead easy | So incompatible you gotta be braindead | When you don't care about the original, or anyone else |
| XPath change | Highly specific, highly compatible | Limited to XML-defined Defs | When you need to change a few XML values |
| Adding a (self-made) Comp | Very flexible, well-supported, highly-compatible | Does not work on every Def | When you want to add functionality |
| DefModExtension | Very simple, well-supported, highly-compatible | Static data | When you want to add fields/data |
| SubClassing | Fairly powerful, half the work is already done | Compatibility issues, not very flexible | When neither a Comp nor a DefModExtension works |
| Custom Def | Full control | Very specific to your mod | When the given Defs don't suffice for you |
Requirements[edit]
- Understanding Defs helps.
- For the C# portions:
- Decompiling source code is required.
- This tutorial requires you to know how to write custom code.
- Introduction to Def Classes is highly recommended.
Overwriting Defs[edit]
If two mods share the same defName for a single type of Def, the last mod wins. If mod A adds a ResearchDef with defName Pemmican and mod B also adds a ResearchDef with defName Pemmican, the game will use mod B's Pemmican.
Pros[edit]
Braindead easy.
Cons[edit]
No compatibility.
When to use[edit]
Not.
XPath[edit]
XPath allows you to change specific values of Defs (multiple in a single operation, if you want) across mods with surgical precision.
Pros[edit]
Highly flexible, highly compatible.
Cons[edit]
Limited to Defs defined in XML (no meat, corpses or other generated Defs). More complex operations require more fiddly syntax.
When to use[edit]
All the time.
Adding a (self-made) Comp[edit]
ThingComps are like little modules you can add to any ThingWithComp to give them added functionality.
Pros[edit]
Very flexible, well-supported and highly-compatible. There are many ready-made (example) Comps available that can be employed to do a wide variety of things.
Cons[edit]
Not suited for every type of functionality.
When to use[edit]
When you want to add functionality, non-static data or behaviour.
DefModExtensions[edit]
DefModExtensions can be seen as a way to add fields to Defs.
Pros[edit]
Very simple, very lightweight, highly compatible.
Cons[edit]
Static data only.
When to use[edit]
When you want to add (static) fields/data to Defs.
Subclassing[edit]
Inherit from a Def and explicitly tell RimWorld to use that specific Type.
Pros[edit]
They're you're own Type, so you can extend their functionality until your heart is content.
Cons[edit]
- Still bound to the base Def without access to its private methods
- Using them requires a lot of casting
- Only one custom class per Def
- They don't offer a lot of extra functionality over DefModExtensions or C# Extension methods
When to use[edit]
When neither a Comp nor a DefModExtension works.
Custom Def[edit]
(Optionally) inherit from a Def and tell RimWorld to use your custom Def.
Pros[edit]
Fully your own Type, complete control. No incompatibility issues, because they're all yours.
Cons[edit]
Implementation from scratch.
When to use[edit]
If your Def is really unique to your mod or specific goal.
Other ways[edit]
Sometimes creative, sometimes hacky:
Checking for tags[edit]
Instead of using custom defClasses and comps you could also use tags. This is especially useful for lightweight features and simple compatibility.
Some tags are never used by a certain Thing such as ApparelTag on a Building. If a tag is never used it doesn't throw an error and therefore you could introduce as many useless tags as you want to a mod without the game complaining. When other mods check for these tags they can also do it without a problem. This way you could add tags of whatever name you want and let others check for this tag for compatibility.
Pros[edit]
Lightweight, easy.
Cons[edit]
Risk of potential side-effects. Kinda hacky.
Changing the class used by the Def[edit]
A lot of Defs have a field entry that specifies the C# class they are tied to. For instance, the GameConditionDef for the Eclipse has a conditionClass of GameCondition_Eclipse. Modders who wish to add some sparkles to the Eclipse could create a new GameCondition class called GameCondition_EclipseWithSparkles and use XPath to change the conditionClass to MyNameSpace.GameCondition_EclipseWithSparkles.
Pros[edit]
Pretty easy. Keeps most values of the original Def intact as well.
Cons[edit]
Subverts any Harmony patches on the original Class, so potential issues with compatibility.
Harmony patching[edit]
If you still want to use Harmony in the face of all these alternatives, you might have fallen for the Golden Hammer Design Pattern. But sure, go ahead.
See also[edit]
- Compatibility with defs explains compatibility from the XML side of things.