Latest revision as of 00:43, 12 September 2021

< Modding Tutorials
Creating a custom comp class is a convenient way to add new functionality to RimWorld. Comps aren't a formal concept in the code: they're a design pattern used in different places. They allow for a more modular approach to adding functionality to different objects.

The types of Components[edit]

These are the places where the Comps design pattern is used, each with differing behaviour suited for their respective area. From most specific to most generic:

HediffComp[edit]

A relatively simple Comp for adding more complex behaviour to Hediffs.

ThingComp[edit]

Main article: Modding Tutorials/ThingComp

A very powerful Component that is tied to a specific Thing. These are often used to store data, give special functionality to the Thing they're tied to and are one of the building blocks of RimWorld modding and RimWorld in general. While not as powerful as a fully custom class, they provide plenty of functionality for a lot of general use cases without compatibility issues.

WorldObjectComp[edit]

Like a ThingComp, but for WorldObjects.

MapComponent[edit]

Main article: Modding Tutorials/GameComponent

Much like a ThingComp, except these exist at the Map level. They're most useful for keeping tracks of multiple things at once, storing data, and can serve as a coordinator or general managing entity.

WorldComponent[edit]

Main article: Modding Tutorials/GameComponent

Similar to a MapComponent, but lives on the World level.

GameComponent[edit]

Main article: Modding Tutorials/GameComponent

Similar to a WorldComponent, but lives at the Game level.

The distinction between a GameComponent and a WorldComponent might not be too obvious, but a GameComponent gets instantiated when a new Game is started:

Upon start of the tutorial
When the player starts the Scenario Configuration (rolling for colonists)
When a save is loaded from the main menu

StorytellerComp[edit]

These are a specific type of Component that determines the behaviour of the storyteller.

Which one to use[edit]

Use whatever is most appropriate, really. Does it deal with a Pawn's health? HediffComp. Is it functionality at Thing level? ThingComp. Does it have to do with two pawns, or multiple items on a map? Probably a MapComponent, or maybe a WorldComponent.

Difference between revisions of "Modding Tutorials/Custom Comp Classes"

Latest revision as of 00:43, 12 September 2021

Contents

The types of Components[edit]

HediffComp[edit]

ThingComp[edit]

WorldObjectComp[edit]

MapComponent[edit]

WorldComponent[edit]

GameComponent[edit]

StorytellerComp[edit]

Which one to use[edit]

Navigation menu

Search

@@ Line 1: / Line 1: @@
 {{BackToTutorials}}
-Creating a custom comp class is a convenient way to add new functionality to RimWorld.
+Creating a custom comp class is a convenient way to add new functionality to RimWorld. Comps aren't a formal concept in the code: they're a design pattern used in different places. They allow for a more modular approach to adding functionality to different objects.
-'''Benefits''':<br/>
+=The types of Components=
-<nowiki>+</nowiki> Are very well supported by RimWorld.<br/>
+These are the places where the Comps design pattern is used, each with differing behaviour suited for their respective area. From most specific to most generic:
-<nowiki>+</nowiki> Exposes (part of its) functionality to XML.<br/>
+==HediffComp==
-<nowiki>+</nowiki> Compatible with savefiles, other mods, you name it.</br>
+A relatively simple Comp for adding more complex behaviour to Hediffs.
-<nowiki>+</nowiki> Does not come with the compatibility issues and pitfalls of creating a custom Def class.<br/>
-<nowiki>+</nowiki> Can save data.<br/>
-<nowiki>+</nowiki> Can access its parent.<br/>
-<nowiki>+</nowiki> Certain functionality gets automatically called RimWorld.<br/>
-'''Downsides''':<br>
+==ThingComp==
-<nowiki>-</nowiki> Only works on ThingWithComps.<br/>
+{{Main|Modding Tutorials/ThingComp}}
-<nowiki>-</nowiki> Requires a few extra steps to expose their functionality to XML.<br/>
+A very powerful Component that is tied to a specific Thing. These are often used to store data, give special functionality to the Thing they're tied to and are one of the building blocks of RimWorld modding and RimWorld in general. While not as powerful as a [[Modding Tutorials/Def classes|fully custom class]], they provide plenty of functionality for a lot of general use cases without compatibility issues.
-<nowiki>-</nowiki> Not suited for every type of functionaliy.<br/>
-== Requirements ==
+==WorldObjectComp==
-* You need to have [[Modding Tutorials/Setting up a solution|set up your editor and environment]]
+Like a ThingComp, but for WorldObjects.
-* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]]
-* You should probably understand Defs at least somewhat.
-== What you'll learn ==
+==MapComponent==
-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.
+{{Main|Modding Tutorials/GameComponent}}
+Much like a ThingComp, except these exist at the Map level. They're most useful for keeping tracks of multiple things at once, storing data, and can serve as a coordinator or general managing entity.
-== Setting up ==
+==WorldComponent==
-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.
+{{Main|Modding Tutorials/GameComponent}}
+Similar to a MapComponent, but lives on the World level.
-== The Code ==
+==GameComponent==
-RimWorld will initialise your Comp like thus:
+{{Main|Modding Tutorials/GameComponent}}
-# First the ThingMaker will create a new instance of a Def, and call this a Thing.
+Similar to a WorldComponent, but lives at the Game level.
-# ThingMaker will then call PostMake() on the instance of Thing (in our case, a ThingWithComps).
-# PostMake() will call ThingWithComps.InitializeComps().
-# For every entry in the Def's Comp list, ThingWithComps.InitializeComps will create a new instance of each compClass (in every case, something that inherits from ThingComp)
-# ThingWithComps.InitializeComps will set the parent of the ThingComp.
-# ThingWithComps.InitializeComps calls the Initialize() method of the ThingComp instance.
-# ThingComp.Initialize() will set the CompProperties, with the properties as defined in the Def.
-Note that this is [https://en.wikipedia.org/wiki/Object-oriented_programming Object Oriented Programming]: the (JIT) compiler first looks for overridden methods to call before calling the parent.
+The distinction between a GameComponent and a WorldComponent might not be too obvious, but a GameComponent gets instantiated when a new Game is started:
+* Upon start of the tutorial
+* When the player starts the Scenario Configuration (rolling for colonists)
+* When a save is loaded from the main menu
-==An Example==
+==StorytellerComp==
-The below is a simple example. We'll use this later on.
+These are a specific type of Component that determines the behaviour of the storyteller.
-<source lang = "csharp">
-using Verse;
-using System;
-namespace MyExampleNamespace
+=Which one to use=
-{
+Use whatever is most appropriate, really. Does it deal with a Pawn's health? HediffComp. Is it functionality at Thing level? ThingComp. Does it have to do with two pawns, or multiple items on a map? Probably a MapComponent, or maybe a WorldComponent.
-    public class MyExampleComp : ThingComp
-    {
-        public override void CompTick()
-        {
-            Log.Error("Let's error on every tick!");
-        }
-        /// <summary>
+[[Category:Modding tutorials]][[Category:Modding]]
-        /// By default this.props returns the base CompProperties class.
-        /// You can get this.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;
-        }
-    }
-}
-</source>
-===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 [[Time|Tick]], but only if the TickerType of the parent is TickerType Normal.
-==== CompTickRare====
-Runs once every [[Time|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 [[Modding Tutorials/Gizmos|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===
-=== Setup, Defs, and Classes ===
-You will have some custom def and it will have something like this:
-==== Defs (xml) ====
-  <ThingDef ...>
-    ...
-    ...
-    <comps>
-      <<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties">
-        <myCustomCompProperty>some value</myCustomCompProperty>
-        <mySecondCompProp>4</mySecondCompProp>
-      </<nowiki>li</nowiki>>
-      <<nowiki>li</nowiki>>
-        ''<<nowiki>!--</nowiki> this is kind of like <tag>MN.MyCustomTag</tag>:-->''
-        <compClass>MyNamespace.MyCustomThingComp</compClass>
-      </<nowiki>li</nowiki>>
-    </comps>
-  </ThingDef>
-==== C# ====
-  namespace MyNamespace ''// For example, LWM.ModName - by using your ''
-                        ''//   handle/name/etc, you almost certainly guarantee uniqueness''
-  {
-  '''//////////// <<nowiki>li</nowiki> Class="MyNamespace.MyCompProperties"> ////////////'''
-  public class MyCompProperties : CompProperties ''// Name this as you wish, of course''
-  {
-    public Properties() {
-      this.compClass = typeof(MyNamespace.MyLinkedCompThing); ''// rename as appropriate''
-    }
-    public string myCustomCompProperty; ''// Name matches def, of course''
-    public int mySecondCompProp = 1; ''// Can set default values''
-  }
-  ''// this ThingComp is used to actually access the comp property defined above''
-  '''''// this is not "<compClass>MyNamespace.MyCustomThingComp</compClass>"'''''
-  public class MyLinkedCompThing : ThingComp
-  {
-    public string myCustomCompProperty
-    {
-      get
-      {
-        return ((MyCompProperties)this.props).myCustomCompProperty;
-      }
-    }
-    public int mySecondCompProperty ''// Have to get all the names right''
-    { get  { return ((MyCompProperties)this.props).mySecondCompProperty; } } ''//etc''
-  }
-  '''//////////// <compClass>MyNamespace.MyCustomThingComp</compClass> ////////////'''
-  public class MyCustomThingComp : ThingComp
-  {
-    public override void CompTick()
-    {
-      // do stuff
-    }
-    public override void CompTickRare() //etc
-    public override ... // Check out Verse/ThingComp.cs for more ideas
-  }
-  } // end MyNamespace
-=== 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 ====
-This is the "hard" way, but doable if you want:
-<source lang="C#">
-    int importantProperty = ((MyCompProperties)((ThingWithComps)myObject)
-                             .GetComp<MyLinkedCompThing>().props).mySecondCompProp;
-    //     The "(ThingWithComps)" cast may or may not be needed
-</source>
-==== Use the "get" method we created ====
-Easier approach:
-<source lang="C#">
-    // real world example:
-    SlotGroup slotGroup = GetSlotGroupInEarlierCode();
-    MyLinkedCompThing comp = ((ThingWithComps)slotGroup.parent).GetComp<MyLinkedCompThing>();
-    if (comp != null) {
-        string s = comp.myCustomCompProperty;
-        int x = otherObject.GetComp<MyLinkedCompThing>().mySecondCompProp; // be sure it exists, etc
-    } else { /* not a thing with my comp, etc */ }
-</source>
-=== 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:
-<source lang ="csharp">
-Thing thing;
-MyExampleComp comp = thing.TryGetComp<MyExampleComp>();
-if (comp != null)
-{
-    //do stuff
-}</source>
-* Ticking! Make sure the TickerType and your Tick method matches. If the ThingWithComp has the Normal TickerType, CompTickRare() will never get called.
-[[Category:Modding tutorials]][[Category:Modding]][[Category:Defs]]