Modding Tutorials/Custom Comp Classes

< Modding Tutorials
Creating a custom comp class is a convenient way to add new functionality to RimWorld.

Benefits:
+ Are very well supported by RimWorld.
+ Exposes (part of its) functionality to XML.
+ Compatible with savefiles, other mods, you name it.
+ Does not come with the compatibility issues and pitfalls of creating a custom Def class.
+ Can save data.
+ Can access its parent.
+ Certain functionality gets automatically called RimWorld.

Downsides:
- Only works on ThingWithComps.
- Requires a few extra steps to expose their functionality to XML.
- Not suited for every type of functionality.

Requirements

• You need to have set up your editor and environment
• You need to know how to write custom code
• You should probably understand Defs at least somewhat.

What you'll learn

What ThingComps are, when and how to use them. Since ThingComps are so ubiquitous and practical, every method you can override is also included, along with a short blurb of what it does.

Setting up

To implement a ThingComp, we need to inherit from the ThingComp class. This tutorial assumes you'll want to expose your Comp's functionality to XML, for that we need to inherit from CompProperties as well.

The Code

RimWorld will initialise your Comp like thus:

1. First the ThingMaker will create a new instance of a Def, and call this a Thing.
2. ThingMaker will then call PostMake() on the instance of Thing (in our case, a ThingWithComps).
3. PostMake() will call ThingWithComps.InitializeComps().
4. For every entry in the Def's Comp list, ThingWithComps.InitializeComps will create a new instance of each compClass
   • If the compClass isn't set in the XML, InitializeComps will use the default Type of ThingComp to instantiate. The constructor for CompProperties can specify a different (subclass of) ThingComp to instantiate.
5. ThingWithComps.InitializeComps will set the parent of the ThingComp.
   • Parent in this context is the ThingWithComps that has the Comp. For example: Electric stoves have a CompFlickable. The stove is the parent of this instance of comp.
6. ThingWithComps.InitializeComps calls the Initialize() method of the ThingComp instance.
7. ThingComp.Initialize() will set the CompProperties, with the properties as defined in the Def.

Note that this is Object Oriented Programming: the (JIT) compiler first looks for overridden methods to call before calling the parent.

An Example

The below is a simple example. We'll use this later on.

using Verse;
using System;

namespace MyExampleNamespace
{
    public class MyExampleComp : ThingComp
    {
        public override void CompTick()
        {
            Log.Error("Let's error on every tick!");
        }

        /// <summary>
        /// By default props returns the base CompProperties class.
        /// You can get props and cast it everywhere you use it, 
        /// or you create a Getter like this, which casts once and returns it.
        /// Careful of case sensitivity!
        /// </summary>
        public MyExampleCompProperties Props => (MyExampleCompProperties)this.props;

        public bool ExampleBool => Props.myExampleBool;
    }

    public class MyExampleCompProperties : CompProperties
    {
        public bool myExampleBool;
        public float myExampleFloat;

        /// <summary>
        /// These constructors aren't strictly required if the compClass is set in the XML.
        /// </summary>
        public MyExampleCompProperties()
        {
            this.compClass = typeof(MyExampleComp);
        }

        public MyExampleCompProperties(Type compClass) : base(compClass)
        {
            this.compClass = compClass;
        }
    }
}

ThingComp

It does not make sense to override every method listed here. It therefor goes without saying you should only override those methods need.

Initialize(CompProperties props)

Called once when the ThingComp is instantiated, and called during loading. Used to, well, initialise the props.

ReceiveCompSignal(string signal)

A string based signalling system that allows for communication between comps.

PostExposeData

Used for saving and loading data. Runs after the ThingWithComps ExposeData.

PostSpawnSetup(bool respawningAfterLoad)

Similar to Initialize(), but be aware that there's a difference between "getting initialised" and "spawning". A ThingWithComps can be initialised without getting spawned. Useful for setting up Map- and Thing-related stuff.

PostDeSpawn(Map map)

Gets called after despawning. Useful for cleaning up. Note: getting despawned doesn't mean destroyed. Think: caravans, minifying, etc.

PostDestroy(DestroyMode mode, Map previousMap)

Gets called after being destroyed. Useful for cleaning up.

CompTick

Runs once every Tick, but only if the TickerType of the parent is TickerType Normal.

CompTickRare

Runs once every TickRare, but only if the TickerType of the parent is TickerType Rare.

There is no CompTickLong.

PostPreApplyDamage(DamageInfo dinfo, out bool absorbed)

Runs before damage gets applied to the parent. The bool sets if damage was absorbed or not. Full damage absorption or nothing.

PostPostApplyDamage(DamageInfo dinfo, float totalDamageDealt)

Runs after damage gets applied to the parent.

PostDraw

Called every frame. Only use this for drawing. Do not put game logic in this.

PostDrawExtraSelectionOverlays

Called every frame, if the parent is selected. Used by things like the DeepScanner. Only use this for drawing. Do not put game logic in this.

PostPrintOnto(SectionLayer layer)

Not a clue. Power uses it.

CompPrintForPowerGrid(SectionLayer layer)

Not a clue. Power uses it.

PreAbsorbStack(Thing otherStack, int count)

Used before the parent absorbs count amount of otherStack. Useful for averaging out values of your Comp. e.g. FoodPoisoning.

PostSplitOff(Thing piece)

The opposite of PreAbsorbStack.

TransformLabel(string label)

Returns a string. Neurotrainers use this to identify what type of Neurotrainer they are.

CompGetGizmosExtra

Returns an IEnumerable<Gizmo>. Lets you add Gizmos to the thing. Gizmos are the actions buttons you see when you select something, like the temperature setting buttons.

AllowStackWith(Thing other)

Returns a boolean that determines whether or not two Things can stack.

CompInspectStringExtra

Returns a string. Adds extra things to the selection box.

GetDescriptionPart

Returns a string. Adds extra things to the selection box.

CompFloatMenuOptions(Pawn selPawn)

Returns an IEnumerable<FloatMenuOption>. Lets you add a FloatMenuOption to the thing.

PrePreTraded(TradeAction action, Pawn playerNegotiator, ITrader trader)

Runs before the trade is completed. Useful for making Pawns very attached to a Thing, then make them hate the Pawn that sells it.

PostIngested(Pawn ingester)

Runs after the Thing is eaten.

PostPostGeneratedForTrader(TraderKindDef trader, int forTile, Faction forFaction)

Runs after it's generated for a trader. Used by CompQuality.

Notify_SignalReceived(Signal signal)

The other part of the string based inter comp communication network.

ToString

For debugging.

CompProperties

CompProperties()

A constructor.

CompProperties(Type compClass)

A constructor which takes a parameter.

DrawGhost(IntVec3 center, Rot4 rot, ThingDef thingDef, Color ghostCol, AltitudeLayer drawAltitude)

Used by Fire, and other cases where you'd not recognise the Blueprint without the Comp.

ConfigErrors(ThingDef parentDef)

Returns an IEnumerable<string> with config errors. Don't forget to yield return every error in the base.

ResolveReferences(ThingDef parentDef)

Not a clue. Used for Resolving references, obviously, but dunno the use.

SpecialDisplayStats(StatRequest req)

Returns an IEnumerable<StatDrawEntry>. Useful for when your Comp adds extra stats.

XML

If you want to add your Comp to a Def, you use the following XML:

<Defs>
    <ThingDef>
        <comps>
            <li Class="MyExampleNamespace.MyExampleCompProperties">
                <myExampleBool>false</myExampleBool>
                <myExampleFloat>0.005</myExampleFloat>
            </li>
        </comps>
    </ThingDef>
</Defs>

This adds the ThingComp to your ThingWithComps and populates it fields with the values set in the XML.

If your ThingComp does not have properties, you use the following XML:

<Defs>
    <ThingDef>
        <comps>
            <li>
                <compClass>MyExampleNamespace.MyExampleComp</compClass>
            </li>
        </comps>
    </ThingDef>
</Defs>

This adds the ThingComp to the ThingWithComps and uses the specified compClass.

Somewhat niche but useful: One type of CompProperties can instantiate different type of CompClasses. CompProperties_Power is a good example.

Adding them with xpath

If the ThingWithComps already has comps, you can use a simple PatchOperationAdd to add your comp to the list. If it does not yet have a comps node, you will need to make one. Other mods may also have the same need, which would result in incompatibility issues: Adding a comps entry twice results in only the first entry getting read. To go around this, a PatchOperationConditional is used:

<!-- Add /comps/li/compClass if there are no comps yet. -->
<!-- Add /li/compClass to /comps if exists (i.e. other mod already added the comps field first) -->
    <Operation Class="PatchOperationConditional">
        <xpath>/Defs/WorldObjectDef[defName="Caravan"]/comps</xpath>
        <nomatch Class="PatchOperationAdd">
            <xpath>/Defs/WorldObjectDef[defName="Caravan"]</xpath>
            <value>
                <comps>
                    <li>
                        <compClass>MyExampleNamespace.MyExampleComp</compClass>
                    </li>
                </comps>
            </value>
        </nomatch>
        <match Class="PatchOperationAdd">
            <xpath>/Defs/WorldObjectDef[defName="Caravan"]/comps</xpath>
            <value>
                <li>
                    <compClass>MyExampleNamespace.MyExampleComp</compClass>
                </li>
            </value>
        </match>
    </Operation>

Accessing your Comps

Just setting up your custom comps doesn't do you a lot of good if you can't access them!

Accessing CompProperty directly

Accessing them depends on whether or not you have a Thing or a ThingWithComps.

• ThingWithComps has a GetComp<>() method which will return the type of ThingComp specified in the <> if present, and null otherwise.
• Thing has a TryGetComp<MyExampleComp>() method. It will safely cast to ThingWithComps and return null upon failure. Upon success, it will return the value of ThingWithComps.GetComp<>()

It is wise to nullcheck.

Cautions, traps, etc

• If you have the same comp in an abstract (XML) def and attempt to redefine it in a (XML) child def, it will get counted twice. To get around this in XML, inherit from a newly defined Parent without the Comp. It's not recommended to add the Inherit="False" tag to the comps tag, as that gets rid of all Comps. While you can get around it in code, a newly defined parent is cleaner (and less effort).
• Not every Thing is a ThingWithComps! Only Things that are a ThingWithComps (or subclass thereof) have Comps. Chunks are a notable Thing that aren't ThingWithComps.
• Casting to ThingWithComps is needlessly expensive and explicit casting can lead to InvalidCastExceptions. If it's a Thing you suspect is a ThingWithComps, you can:

Thing thing;
MyExampleComp comp = thing.TryGetComp<MyExampleComp>();
if (comp != null)
{
    //do stuff
}

• Ticking! Make sure the TickerType and your Tick method matches. If the ThingWithComp has the Normal TickerType, CompTickRare() will never get called.