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

From RimWorld Wiki
Jump to navigation Jump to search
(now to refactor it)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{BackToTutorials}}
 
{{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 functionality.<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
 
−
#* 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.
 
−
# ThingWithComps.InitializeComps will set the parent of the ThingComp.
 
−
#* Parent in this context is the ThingWithComps that has the Comp. For example: [[Electric stove]]s have a CompFlickable. The stove is the parent of this instance of comp.
 
−
# 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 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;
 
−
        }
 
−
    }
 
−
}
 
−
</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===
 
−
If you want to add your Comp to a Def, you use the following XML:
 
−
<source lang ="xml">
 
−
<Defs>
 
−
    <ThingDef>
 
−
        <comps>
 
−
            <li Class="MyExampleNamespace.MyExampleCompProperties">
 
−
                <myExampleBool>false</myExampleBool>
 
−
                <myExampleFloat>0.005</myExampleFloat>
 
−
            </li>
 
−
        </comps>
 
−
    </ThingDef>
 
−
</Defs>
 
−
</source>
 
−
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:
 
−
<source lang ="xml">
 
−
<Defs>
 
−
    <ThingDef>
 
−
        <comps>
 
−
            <li>
 
−
                <compClass>MyExampleNamespace.MyExampleComp</compClass>
 
−
            </li>
 
−
        </comps>
 
−
    </ThingDef>
 
−
</Defs>
 
−
</source>
 
−
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:
 
−
 
 
−
<source lang = "xml">
 
−
<!-- 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>
 
−
</source>
 
−
 
 
−
=== 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 <nowiki><></nowiki> 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:
 
−
<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]]
 

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.

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