Difference between revisions of "Modding Tutorials/ThingDef"

From RimWorld Wiki
Jump to navigation Jump to search
(: link to custom comp classes)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Tocright}}
 
 
{{BackToTutorials}}
 
{{BackToTutorials}}
  
'''ThingDef''' is a def type for making entities, such as buildings and pawns (NPCs).
+
'''ThingDef''' is one of the many [[Modding_Tutorials/XML_Defs|Defs]] used in RimWorld. Almost every "tangible" (and some intangible) things you see in RimWorld are backed by a ThingDef.
<br/> This has been updated for <b>Alpha 9</b>.
 
  
==Buildings==
+
=What you'll learn=
Buildings are static entities. They usually require construction and perform a special function.
+
You will learn the '''structure''' of ThingDef, how to use a decompiler to learn what a tag does, and along the way you'll learn the meaning of a few select tags.
  
===Elements===
+
=What you will '''not''' learn=
{| class="wikitable sortable"
+
The goal of this tutorial is not to tell you what each XML tag does. ThingDef alone has 200+ valid XML tags, not counting hundreds of subtags. There are simply too many to document, and a lot of them are self-explanatory.
! scope="col"| Tags
 
! scope="col"| Description
 
! scope="col"| Values
 
|----
 
! scope="row"| wantsHopperAdjacent
 
|Whether the building needs adjacent hoppers or not.
 
|Boolean
 
|----
 
! scope="row"| ignoreNeedsPower
 
|When has CompTrader: Whether this building requires power or not.
 
|Boolean
 
|----
 
! scope="row"| soundAmbient
 
|Sound to play whenever its working.
 
|SoundDefs
 
|----
 
! scope="row"| shipPart
 
|Designates the building as one of the ship parts or not.
 
|Boolean
 
|----
 
! scope="row"| canPlaceOverImpassablePlant
 
|Whether the building can be placed over tree or not.
 
|Boolean
 
|----
 
! scope="row"| isEdifice
 
|Whether to register this as a building internally or not.
 
|Boolean
 
|----
 
! scope="row"| canBuildNonEdificeUnder
 
|Whether non-edifice buildings can be built under it or not.
 
|Boolean
 
|----
 
! scope="row"| canPlaceOverWall
 
|Whether the building can be placed over wall.
 
|Boolean
 
|----
 
! scope="row"| preventDeterioration
 
|Whether the building can prevent deterioration of items it is holding.
 
|Boolean
 
|----
 
! scope="row"| isNaturalRock
 
|Designates the building as a natural rock or not.
 
|Boolean
 
|----
 
! scope="row"| isResourceRock
 
|Designates the building as a natural, resource containing rock or not.
 
|Boolean
 
|----
 
! scope="row"| bed_healTickInterval
 
|How much ticks are needed for a patient’s body to heal on the bed.
 
|Integer over 0
 
|----
 
! scope="row"| bed_medicalBonusFactor
 
|How much bonus is provided when a patient is on the bed.
 
|Float value
 
|----
 
! scope="row"| bed_defaultMedical
 
|Whether the bed is set to medical from the spawn.
 
|Boolean
 
|----
 
! scope="row"| bed_showSleeperBody
 
|Whether to hide a person’s body when the person is sleeping on the bed.
 
|Boolean
 
|----
 
! scope="row"| turretGunDef
 
|What weapon the turret will use.
 
|ThingDefs (weapon)
 
|----
 
! scope="row"| turretShellDef
 
|What item it will take as a shell.
 
|ThingDefs
 
|----
 
! scope="row"| turretBurstWarmupTicks
 
|How long the turret will take to aim.
 
|Integer from 0
 
|----
 
! scope="row"| turretBurstCooldownTicks
 
|How much the turret will take between a shot when burst firing.
 
|Integer from 0
 
|----
 
! scope="row"| turretTopGraphicPath
 
|What texture turret’s gun will use.
 
|File path
 
|----
 
! scope="row"| soundDoorOpenPowered
 
|What sound to play when the door is opening and powered.
 
|SoundDefs
 
|----
 
! scope="row"| soundDoorClosePowered
 
|What sound to play when the door is closing and powered.
 
|SoundDefs
 
|----
 
! scope="row"| soundDoorOpenManual
 
|What sound to play when the door is opening and unpowered.
 
|SoundDefs
 
|----
 
! scope="row"| soundDoorCloseManual
 
|What sound to play when the door is closing and unpowered.
 
|SoundDefs
 
|----
 
! scope="row"| sowTag
 
|Plants with same sowTag can be planted on it.
 
|String
 
|----
 
! scope="row"| defaultPlantToGrow
 
|What plants should be default to grow.
 
|ThingDefs
 
|----
 
! scope="row"| soundMined
 
|What sound to play when it is destroyed by mining.
 
|SoundDefs
 
|----
 
! scope="row"| mineableThing
 
|What to spawn when mined.
 
|ThingDefs
 
|----
 
! scope="row"| mineableYield
 
|How much to spawn when mined.
 
|Integer over 0
 
|----
 
! scope="row"| mineableNonMinedEfficiency
 
|Influences how much to spawn when damage source is not mining.
 
|Float value from 0
 
|----
 
! scope="row"| mineableDropChance
 
|How much chance to spawn when mined.
 
|Float value from 0.0 to 1.0
 
|----
 
! scope="row"| mineableScatterCommonality
 
|How common it will be when generating map.
 
|Float value over 0
 
|----
 
! scope="row"| mineableScatterBlotchSize
 
|How big a vein of the rock will be when generating map.
 
|Two integers: <min>x</min> and <max>y</max>
 
|----
 
! scope="row"| fixedStorageSettings
 
|What it can store.
 
|See grave and weapons rack as references.
 
|----
 
! scope="row"| defaultStorageSettings
 
|What settings to store it has.
 
|See grave and weapons rack as references.
 
|----
 
|}
 
  
==Pawns==
+
* If you want a list of all XML tags (not just ThingDef) you'll want [https://ludeon.com/forums/index.php?topic=21440.0 milon's autodocumentation project]. Note that it only includes tags ''in use by'' RimWorld, not necessarily ''all tags available''.
All characters in RimWorld are 'pawns' (including colonists and NPCs).
+
* If you want to see what an earnest attempt at documenting the XML looks like, you'll want the [https://github.com/RimWorldMod/RimworldModdingFiles XML Documentation Database]. Last updated for A15.
 +
* If you want to see what a documentation attempt on this wiki looks like, [https://rimworldwiki.com/index.php?title=Modding_Tutorials/ThingDef&oldid=62403 view the history of this article] and see that was last up to date in Alpha 9.
  
==Items==
+
Fact of the matter is this: there is no documentation that will tell you the meaning and usage of every tag. There probably never will. If there is, it will be out-of-date soon enough.
Items are anything that can be hauled, such as weapons, debris, or resources.
 
  
==Plants==
+
=Requirements=
Plants grow in growing areas, in the landscape, in a hydroponics table, or in a plant pot.
+
* A [[Modding Tutorials/Decompiling_source_code|decompiler]] is advised.
  
===Elements===
+
[[File:ThingDef.PNG|300px|thumb|right|ILSpy v4.0 showing the decompiled ThingDef class, with the analyzer expanded on the smallVolume field. To the left a few of available fields are visible.]]
{| class="wikitable sortable"
 
! scope="col"| Tags
 
! scope="col"| Description
 
! scope="col"| Values
 
|----
 
! scope="row"| wildCommonalityMaxFraction
 
|Affects how common this plant will be in wild.
 
|Float value over 0 (Default: 1.25)
 
|----
 
! scope="row"| wildClusterRadius
 
|How big its "cluster" group will be.
 
|Two integers:<min>x</min> <max>y</max> (Default: 1, 1)
 
|----
 
! scope="row"| wildClusterRadius
 
|How far its "cluster" group can reach.
 
|Float value over 0 (Default: -1 (=Disabled))
 
|----
 
! scope="row"| sowTags
 
|Affects where this plant can be sown.
 
|Any string
 
|----
 
! scope="row"| sowWork
 
|How much work it needs to be sown.
 
|Float value over 0 (Default: 200)
 
|----
 
! scope="row"| blockAdjacentSow
 
|Whether this plant blocks neighboring cells for sowing.
 
|Boolean
 
|----
 
! scope="row"| harvestWork
 
|How much work it needs to be harvested.
 
|Float value over 0 (Default: 150)
 
|----
 
! scope="row"| harvestYieldRange
 
|How much product it will yield when harvested.
 
|Two float values: <min>x</min> <max>y</max> (Default: 0, 0)
 
|----
 
! scope="row"| harvestDestroys
 
|Whether this plant should be destroyed when harvested or not.
 
|Boolean (e.g. Agave)
 
|----
 
! scope="row"| harvestedThingDef
 
|What Thing it will yield when harvested.
 
|ThingDefs
 
|----
 
! scope="row"| harvestTag
 
|?
 
|Any string (Following vanilla value is recommended.)
 
|----
 
! scope="row"| harvestMinGrowth
 
|When it can be harvested, in minimum.
 
|Float value from 0.0 to 1.0 (Default: 0.65)
 
|----
 
! scope="row"| soundHarvesting
 
|Sound to play when a pawn is harvesting this plant.
 
|SoundDefs
 
|----
 
! scope="row"| soundHarvestingFinish
 
|Sound to play when a pawn has finished harvesting this plant
 
|SoundDefs
 
|----
 
! scope="row"| growthPer20kTicks
 
|How much it will grow in every {{ticks|20000}}.
 
|Float value over 0 (Default: 0.25)
 
|----
 
! scope="row"| growMinGlow
 
|How much light it needs to grow.
 
|Dark, Lit, Overlit (Default: Overlit)
 
|----
 
! scope="row"| lifespanDays
 
|How long it can survive.
 
|Float value over 0 (Default: -1 (=Disabled))
 
|----
 
! scope="row"| dieIfLeafless
 
|Whether this plant should die in winter or not.
 
|Boolean
 
|----
 
! scope="row"| fertilityMin
 
|Fertility requirement for this plant.
 
|Float value from? (Default: 0.9)
 
|----
 
! scope="row"| fertilityFactorGrowthRate
 
|How much fertility affects to this plant’s growth rate.
 
|Float value from? 0 (Default: 0.5)
 
|----
 
! scope="row"| shootsSeeds
 
|Whether this plant can shoot its seeds, in order to spread into wilderness.
 
|Boolean (Default: true)
 
|----
 
! scope="row"| seedShootRadius
 
|How far it can shoot its seeds
 
|Float value over 0 (Default: 9)
 
|----
 
! scope="row"| topWindExposure
 
|How much it dwindles when wind is blowing.
 
|Float value from? 0 (Default: 0.25)
 
|----
 
! scope="row"| maxMeshCount
 
|Use it when you need to make a plant consisting lots of small plants.
 
|Integer from 1 (Default: 1) (e.g. Dandeliion, astragalus, grass…)
 
|----
 
! scope="row"| visualSizeRange
 
|Minimum means when growth is 0. Maximum means when fully grown.
 
|Two float values: <min>x</min> <max>y</max> (Default: 0.9, 1.1)
 
|----
 
! scope="row"| leaflessGraphicPath
 
|Texture to use when it is winter, or "leafless."
 
|File path
 
|----
 
|}
 
  
 +
=Introduction=
 +
There are hundreds of XML tags. Some of them are rudimentary tags required for basic operation. Most of them are self-explanatory, and you can always use the Find In Files functionality of [[Modding Tutorials/Recommended software|your favourite text editor]] to see what it is used by, and what values already exist. Sometimes, this does not suffice. This tutorial is for those times.
  
==Filth==
+
=An example=
Filth is just an image that is overlaid above the floor. It contributes to the "ugly environment" thought in pawns.
+
Let's take a look at the ''intricate'' tag. This tag serves as an example because unlike "DeteriorationRate" or "stackLimit" it's not immediately obvious what it does. This tutorial assumed you just used the Find In Files functionality of [[Modding Tutorials/Recommended software|your favourite text editor]] and learned just one thing: Only the [[Component]] and [[Advanced component]] have this tag, and it's set to true.
  
==Global elements==
+
<source lang = "xml">
These elements can be used in all ThingDef types.
+
<Defs>
<br/>(For things listed with *'s look lower on the page)
+
    <ThingDef>
 +
        <defName>ComponentIndustrial</defName>
 +
        <intricate>true</intricate>
 +
    </ThingDef>
 +
</Defs>
 +
</source>
  
{| class="wikitable sortable"
+
[[File:Intricate.PNG|300px|thumb|right|The search result for intricate.]]
! scope="col"| Element
 
! scope="col"|Function
 
! scope="col"| Available options
 
|----
 
! scope="row"| defName
 
|Internal ID of the thing. Does not appear in-game.
 
|String (Can't end with number)
 
|----
 
! scope="row"| label
 
|In-game name of the Thing
 
|String
 
|----
 
! scope="row"| description
 
|In-game description of the Thing
 
|String
 
|----
 
! scope="row"| thingClass
 
|Provides an attachment to an internal class in the code.
 
|Class name
 
|----
 
! scope="row"| category
 
|Designates a category to be used internally.
 
|*
 
|----
 
! scope="row"| eType
 
|Provides a more specific description of an object. This may be equal to the category's name.
 
|*
 
|----
 
! scope="row"| selectable
 
|Specifies whether or not the item can be selected in the atlas.
 
|Boolean
 
|----
 
! scope="row"| graphicPath
 
|Texture the Thing will use
 
|File path
 
|----
 
! scope="row"| graphicClass
 
|How the texture will be drawn
 
|Class name
 
|----
 
! scope="row"| shaderType
 
|Defines shader it's drawer will use.
 
|*
 
|----
 
! scope="row"| blueprintgraphicPath
 
|What texture it will use when it is blueprint.
 
|File path
 
|----
 
! scope="row"| blueprintgraphicClass
 
|How the texture of the thing’s blueprint will be drawn.
 
|Class name
 
|----
 
! scope="row"| uiIconPath
 
|What texture it will use as its icon.
 
|File path
 
|----
 
! scope="row"| equippedTexturePath
 
|What texture this item will use when it is equipped by pawn.
 
|File path
 
|----
 
! scope="row"| equippedAngleOffset
 
|How much the equipped texture will be rotated.
 
|Float value
 
|----
 
! scope="row"| drawerType
 
|Unsure
 
|None, RealtimeOnly, MepMeshOnly, MapMeshAndRealTime
 
|----
 
! scope="row"| drawOffscreen
 
|Whether to draw the thing when its center is offscreen?
 
|Boolean
 
|----
 
! scope="row"| drawGUIOverlay
 
|Whether to draw GUI overlay on this or not.
 
|Boolean
 
|----
 
! scope="row"| linkDrawerType
 
|What drawer will be used when the building can be “linked” with adjacent buildings with same link flag.
 
|None, Basic, CornerFiller, Transmitter, TransmitterOverlay
 
|----
 
! scope="row"| drawGUIOverlay
 
|Whether to draw GUI overlay on this or not.
 
|Boolean
 
|----
 
! scope="row"| linkFlags
 
|What the building can be linked with.
 
|*
 
|----
 
! scope="row"| tickerType
 
|Decides the tick type.
 
|Never, Normal(1 per 1 tick), Rare(1 per 250 tick)
 
|----
 
! scope="row"| inspectorTabs
 
|What tabs it has.
 
|Class name
 
|----
 
! scope="row"| costList
 
|How much resources the building will take to be built.
 
|ThingDefs (item) with integer
 
|----
 
! scope="row"| costStuffCount
 
|How much stuff the building will need to be built.
 
|Integer
 
|----
 
! scope="row"| stuffCategories
 
|What kind of stuffs the building will use.
 
|StuffCategoryDefs
 
|----
 
! scope="row"| recipeMaker
 
|Defines recipe to make it in ThingDef directly.
 
|(Recipe)
 
|----
 
! scope="row"| terrainAffordanceNeeded
 
|Where the thing can be built.
 
|Any, Light, Heavy, GrowSoil, Diggable, SmoothHard, SmoothableStone
 
|----
 
! scope="row"| constructEffect
 
|Effect when the building is being constructed.
 
|EffectDefs
 
|----
 
! scope="row"| repairEffect
 
|Effect when the building is being repaired.
 
|EffectDefs
 
|----
 
! scope="row"| leaveResourceWhenKilled
 
|Whether it leaves part of its resource cost when killed.
 
|Boolean
 
|----
 
! scope="row"| filthLeaving
 
|What filth will be there when the thing gets destroyed.
 
|ThingDefs (filth)
 
|----
 
! scope="row"| stackLimit
 
|How much this item can be stacked.
 
|Integer over 0
 
|----
 
! scope="row"| onGroundRandomRotateAngle
 
|How much it can rotate when on gound.
 
|Integer
 
|----
 
! scope="row"| altitudeLayer
 
|The location of the layer on which the object will be placed.
 
| Terrain, TerrainScatter, Floor, FloorEmplacement, Filth, Zone, SmallWire, LowPlant, MoteLow, Shadows, DoorMoveable, Building, Item, ItemImportant, LayingPawn, Projectile, Pawn, PawnUnused, PawnState, Blueprint, MoteOverhead, FlyingItem, Weather, LightingOverlay, VisEffects, FogOfWar, WorldClipper, WorldDataOverlay, MetaOverlays
 
|----
 
! scope="row"| pathCost
 
|How much speed is lost when pawn walks over it.
 
|Integer
 
|----
 
! scope="row"| passability
 
|Whether it’s traversable or not.
 
|Standable, PassThroughOnly, Impassable
 
|----
 
! scope="row"| useStandardHealth
 
|Determines whether or not health will be calculated normally. (?)
 
|Boolean
 
|----
 
! scope="row"| fillPercent
 
|How much cover it will provide.
 
|Float value from 0.0 to 1.0
 
|----
 
! scope="row"| statBases
 
|The thing’s stats.
 
|StatDefs
 
|----
 
! scope="row"| size
 
|This building’s size.
 
|Two integers: (x,y)
 
|----
 
! scope="row"| hasInteractionCell
 
|Whether the building has a interaction cell or not.
 
|Boolean
 
|----
 
! scope="row"| interactionSquareOffset
 
|Where the interaction cell is located.
 
|Two integers: (x, 0, y)
 
|----
 
! scope="row"| surfaceType
 
|What kind of object can be placed on building?
 
|eType?Category?
 
|----
 
! scope="row"| recipes
 
|What recipes the building has.
 
|RecipeDefs
 
|----
 
! scope="row"| comps
 
|What ThingComps the building has.
 
|*
 
|----
 
! scope="row"| building
 
|This building’s properties.
 
|*
 
|----
 
! scope="row"| verbs
 
|This item’s verbs.
 
|*
 
|----
 
! scope="row"| fertility
 
|This building’s fertility.
 
|Float
 
|----
 
! scope="row"| designationCategory
 
|What category under architecture menu it should be in.
 
|DesignationCategoryDefs
 
|----
 
! scope="row"| designationHotKey
 
|What key to press when choosing this building at architecture menu.
 
|Key
 
|----
 
! scope="row"| holdsRoof
 
|Whether this building can hold room on top of it or not.
 
|Boolean
 
|----
 
! scope="row"| combatTargetBuilding
 
|Whether raiders will attack this building automatically or not.
 
|Boolean
 
|----
 
! scope="row"| blockLight
 
|Whether this building can block light or not.
 
|Boolean
 
|----
 
! scope="row"| coversFloor
 
|Whether this building covers whole floor it is on or not.
 
|Boolean
 
|----
 
! scope="row"| isBodyPart
 
|Whether this item is a body part or not.
 
|Boolean
 
|----
 
! scope="row"| researchPrerequisite
 
|What research should be finished to build this building.
 
|ResearchProjectDefs
 
|----
 
! scope="row"| tradeability
 
|How this item is treated by traders.
 
|Never, Sellable, Stockable
 
|----
 
! scope="row"| rotatable
 
|Whether the building can be rotated or not.
 
|Boolean
 
|----
 
! scope="row"| specialDisplayRadius
 
|How much radius it should display when selected.
 
|Float
 
|----
 
! scope="row"| placeWorkers
 
|Restrictor when placing the building.
 
|Class name
 
|----
 
! scope="row"| destroyable
 
|Whether it can be destroyed or not.
 
|Boolean
 
|----
 
! scope="row"| killedLeavings
 
|What to spawn when it is killed.
 
|ThingDefs (item) with integer
 
|----
 
! scope="row"| butcherProducts
 
|What to spawn when it is butchered.
 
|ThingDefs (item) with integer
 
|----
 
! scope="row"| smeltProducts
 
|What to spawn when it is smelted.
 
|ThingDefs (item) with integer
 
|----
 
! scope="row"| destroyOnDrop
 
|Whether destroy this when pawn dropped this or not.
 
|Boolean
 
|----
 
! scope="row"| targetHitChanceFactor
 
|Chance multiplier for being hit.
 
|Float value from? 0
 
|----
 
! scope="row"| weaponTags
 
|Defines tags of this weapon so that pawns or traders can spawn with this weapon.
 
|String
 
|----
 
! scope="row"| artificialBodyPartsTags
 
|Defines tags of this item so that pawns can spawn with this body part.
 
|String
 
|----
 
! scope="row"| canBeSpawningInventory
 
|Whether this item can be spawned in pawn’s inventory.
 
|Boolean
 
|----
 
! scope="row"| techLevel
 
|Defines tech level of this item so that pawns can spawn with this item.
 
|Undefined, Animal, Neolithic, Medieval, Midworld, Spacer, Ultra, Transcendent
 
|----
 
! scope="row"| flammability
 
|Influences how likely it is for the Thing to catch fire and take damage.
 
|0 to 1.0
 
|----
 
! scope="row"| maxHealth
 
|Sets the maximum health of the Thing (if applicable).
 
|Any value above 0
 
|----
 
|}
 
  
===List of <Category>===
+
Take your favourite [[Modding Tutorials/Decompiling source code|decompiler]] and search for ''intricate''. Now right-click the result and hit ''analyze''. The analyzer in my decompiler shows it's read in three places, and assigned nowhere. The decompiler doesn't show any assigning of this value because it's set in the XML. We can see it's read by ''PlayerItemAccessibilityUtility.CacheAccessibleThings'' and twice by ''Thing.SmeltProducts''. Taking a closer look at the ''Thing+<SmeltProducts>c__Iterator4.MoveNext'', this is an inner method for the enumerator<ref>The what? An enumerable is a fancy type of list and the MoveNext means "go to the next item on the list". Apologies to those who have a background in computer science.</ref>. That in itself doesn't do much, so let's take a look at ''SmeltProducts'' itself.
Undefined, Pawn, Item, Plant, Building, Mote, Attachment, Projectile, Ethereal, Filth, Terrain, Roof
 
  
===List of <eType>===
+
[[File:SmeltProducts.PNG|300px|thumb|right|The view for SmeltProducts.]]
Undefined, Pawn, Item, Chunk, Apparel, Equipment, Filth, Fire, Corpse, Puddle, DropPod, Medicine, Plant, Floor, Roof, Mote, Blueprint, Projectile, ItemSkyFalling, Ethereal, Rock, SteamGeyser, BuildingComplex, BuildingInert, Frame, Wall, Door, Bed, Building_Table, Building_PowerPlantGeothermal, Building_PowerConduit, Building_Battery, Building_ResearchBench, Building_Turret, Building_Chair, Building_Cryptosleepcasket, Building_TempController
 
  
===List of <shaderType>===
+
We can see here that ''SmeltProducts'' in turn is used for some economy related DebugOutput, and by MakeRecipeProducts. We can dive further down the rabbithole, but by now it is a reasonable assumption that ''SmeltProducts'' is used to determine what products you get from smelting. But what's the ''intricate'' tag? Well, ''SmeltProducts'' loops over the ingredients in the costList (i.e. the required ingredients to make an item) and checks if it's ''intricate''. If it's not intricate, it will return the ingredient.
None, Cutout, CutoutFlying, CutoutPlant, CutoutComplex, CutoutSkin, Transparent, TransparentPostLight, MetaOverlay, Mote, MoteGlow.
 
  
===List of <linkFlags>===
+
In other words, the ''intricate'' tag means that ThingDef won't survive a trip to the smelter. You don't get your components back if you smelt down an [[Assault rifle]].
None, MapEdge, Rock, Wall, Sandbags, PowerConduit, Custom1, Custom2, … Custom10
 
  
===List of <altitudeLayer>===
+
'''You can find the meaning of every XML tag this way.''' Some might be easier than others, but you can find (or make an educated guess) to the meaning of every XML tag.
Terrain, TerrainScatter, Floor, FloorEmplacement, Filth, Zone, SmallWire, LowPlant, MoteLow, Shadows, DoorMoveable, Building, BuildingOnTop, Item, ItemImportant, LayingPawn, Projectile, Pawn, PawnUnused, PawnState, Blueprint, MoteOverhead, FlyingItem, Gas, Weather, LightingOverlay, VisEffects, FogOfWar, WorldClipper, WorldDataOverlay, MetaOverlays
 
  
===<comps>===
+
=Adding more tags=
{| class="wikitable sortable"
+
This requires C#. The current recommended way for maximum compatibility is by using a [[Modding_Tutorials/DefModExtension|DefModExtension]].
! scope="col"| Tags
 
! scope="col"| Description
 
! scope="col"| Values
 
|----
 
! scope="row"| compClass
 
|What ThingComp it is.  See also [[Custom Comp Classes]] for creating your own.
 
|Class name
 
|----
 
! scope="row"| explosiveRadius
 
|CompExplosive: How far it will explode.
 
|Float value over 0
 
|----
 
! scope="row"| explosiveExpandPerStackCount
 
|CompExplosive: How much further it’s explosion will reach with a stack.
 
|Float value
 
|----
 
! scope="row"| explosiveDamageType
 
|CompExplosive: What type of damage the explosion will deal
 
|DamageDefs
 
|----
 
! scope="row"| startWickHealthpercent
 
|CompExplosive: What health percent its explosion sequence will starts.
 
|Float value from 0.0 to 1.0
 
|----
 
! scope="row"| wickTicks
 
|CompExplosive: How long its explosion sequence will keep.
 
|Integer from 0
 
|----
 
! scope="row"| wickScale
 
|CompExplosive: Its wick sound’s scale?
 
|Float value from 0?
 
|----
 
! scope="row"| glowRadius
 
|CompGlower: Lit radius.
 
|Float value over 0
 
|----
 
! scope="row"| glowColor
 
|CompGlower: Color of light it will emit.
 
|RGBA: (r, g, b, 0)
 
|----
 
! scope="row"| storedEnergyMax
 
|CompPowerBattery: How much energy it can hold.
 
|Float value over 0
 
|----
 
! scope="row"| efficiency
 
|CompPowerBattery: How efficient the battery is.
 
|Float value from 0.0 to 1.0
 
|----
 
! scope="row"| transmitsPower
 
|CompPowerTrader/Transmitter: Whether it transmits electricity or not.
 
|Boolean
 
|----
 
! scope="row"| basePowerConsumption
 
|CompPowerTrader: How much power it requires to work.
 
|Float value
 
|----
 
! scope="row"| startElectricalFires
 
|CompPowerTransmitter?: Whether it will trigger short circuit incident or not?
 
|Boolean
 
|----
 
! scope="row"| shortCircuitInRain
 
|CompPowerTrader?: Whether it will trigger short circuit incident when raining or not?
 
|Boolean
 
|----
 
! scope="row"| powerToggleable
 
|CompPowerTrader: Whether it can be turned on and off.
 
|Boolean
 
|----
 
! scope="row"| soundPowerOn
 
|CompPowerTrader: Sound to play when turning on.
 
|SoundDefs
 
|----
 
! scope="row"| soundPowerOff
 
|CompPowerTrader: Sound to play when turning off.
 
|SoundDefs
 
|----
 
! scope="row"| soundAmbientPowered
 
|CompPowerTrader: Sound to play when running?
 
|SoundDefs
 
|----
 
! scope="row"| heatPerSecond
 
|CompHeatPusher: How much heat it will produce.
 
|Float value
 
|----
 
! scope="row"| heatPushMaxTemperature
 
|CompHeatPusher: How hot its heat is.
 
|Float value
 
|----
 
! scope="row"| nameMaker
 
|CompArt: What rule pack to use when naming.
 
|RulePackDefs
 
|----
 
! scope="row"| descriptionMaker
 
|CompArt: What rule pack to use when writing description.
 
|RulePackDefs
 
|----
 
! scope="row"| minQualityForArtistic
 
|CompArt: How good the item should be to get its unique name and/or description.
 
|Quality
 
|----
 
|}
 
  
===<verbs>===
+
=See also=
{| class="wikitable sortable"
+
* [https://ludeon.com/forums/index.php?topic=21440.0 milon's autodocumentation project]. Note that it only includes tags ''in use by'' RimWorld, not necessarily ''all tags available''
! scope="col"| Tags
+
* [https://github.com/RimWorldMod/RimworldModdingFiles XML Documentation Database]. Last updated for A15.
! scope="col"| Description
 
! scope="col"| Values
 
|----
 
! scope="row"| verbClass
 
|What this verb is.
 
|Class name
 
|----
 
! scope="row"| minRange
 
|How much minimum range is required to fire.
 
|Float value from 0
 
|----
 
! scope="row"| range
 
|How many times this verb will fire in one attack.
 
|Integer from 1
 
|----
 
! scope="row"| ticksBetweenBurstShots
 
|How much it takes to fire another shot right after a shot in a burst.
 
|Integer from 1
 
|----
 
! scope="row"| hasStandardCommand
 
|?
 
|Boolean
 
|----
 
! scope="row"| targetable
 
|Whether this verb can be manually? targeted/target or not.
 
|Boolean
 
|----
 
! scope="row"| requireLineOfSight
 
|Whether this verb requires line of sight to be used.
 
|Boolean
 
|----
 
! scope="row"| forceNormalTimeSpeed
 
|Whether this verb triggers time control to force normal speed.
 
|Boolean
 
|----
 
! scope="row"| onlyManualCast
 
|Whether this verb is not used automatically by pawns and must be ordered or not.
 
|Boolean
 
|----
 
! scope="row"| warmupTicks
 
|Time before this verb is actually used.
 
|Integer from 0
 
|----
 
! scope="row"| soundCast
 
|What sound to play when this verb is used.
 
|SoundDefs
 
|----
 
! scope="row"| soundCastTail
 
|What sound to play when this verb is used at long distance.
 
|SoundDefs
 
|----
 
! scope="row"| linkedBodyPartsGroup
 
|What body part group has this verb.
 
|BodyPartGroupDef
 
|----
 
! scope="row"| meleeDamageDef
 
|What kind of damage this verb will deal on melee.
 
|DamageDefs
 
|----
 
! scope="row"| meleeDamageBaseAmount
 
|How much damage this verb will deal when used on melee.
 
|Integer from? 1?
 
|----
 
! scope="row"| ai_IsBuildingDestroyer
 
|Defines this verb as a building destroyer so AI can use.
 
|Boolean
 
|----
 
! scope="row"| ai_IsWeapon
 
|Defines this verb as a weapon’s verb so AI can use.
 
|Boolean
 
|----
 
! scope="row"| ai_IsIncendiary
 
|Defines this verb as a fire-starter so AI can use.
 
|Boolean
 
|----
 
! scope="row"| projectileDef
 
|What projectile to fire when this verb is used.
 
|ThingDefs (projectile)
 
|----
 
! scope="row"| canMiss
 
|Whether this verb can be miss or not.
 
|Boolean
 
|----
 
! scope="row"| forceMissRadius
 
|How far this verb can miss.
 
|Float value
 
|----
 
|}
 
 
 
==Credits==
 
<!--[https://ludeon.com/forums/index.php?topic=11755.0 Latta's Alpha 9 reference sheet] Couldn't be added due to low edit count-->
 
*Latta's Alpha 9 reference sheet
 
  
 
[[Category:Defs]]
 
[[Category:Defs]]
 +
[[Category:Modding tutorials]]

Latest revision as of 10:30, 11 February 2019

Modding Tutorials

ThingDef is one of the many Defs used in RimWorld. Almost every "tangible" (and some intangible) things you see in RimWorld are backed by a ThingDef.

What you'll learn[edit]

You will learn the structure of ThingDef, how to use a decompiler to learn what a tag does, and along the way you'll learn the meaning of a few select tags.

What you will not learn[edit]

The goal of this tutorial is not to tell you what each XML tag does. ThingDef alone has 200+ valid XML tags, not counting hundreds of subtags. There are simply too many to document, and a lot of them are self-explanatory.

  • If you want a list of all XML tags (not just ThingDef) you'll want milon's autodocumentation project. Note that it only includes tags in use by RimWorld, not necessarily all tags available.
  • If you want to see what an earnest attempt at documenting the XML looks like, you'll want the XML Documentation Database. Last updated for A15.
  • If you want to see what a documentation attempt on this wiki looks like, view the history of this article and see that was last up to date in Alpha 9.

Fact of the matter is this: there is no documentation that will tell you the meaning and usage of every tag. There probably never will. If there is, it will be out-of-date soon enough.

Requirements[edit]

ILSpy v4.0 showing the decompiled ThingDef class, with the analyzer expanded on the smallVolume field. To the left a few of available fields are visible.

Introduction[edit]

There are hundreds of XML tags. Some of them are rudimentary tags required for basic operation. Most of them are self-explanatory, and you can always use the Find In Files functionality of your favourite text editor to see what it is used by, and what values already exist. Sometimes, this does not suffice. This tutorial is for those times.

An example[edit]

Let's take a look at the intricate tag. This tag serves as an example because unlike "DeteriorationRate" or "stackLimit" it's not immediately obvious what it does. This tutorial assumed you just used the Find In Files functionality of your favourite text editor and learned just one thing: Only the Component and Advanced component have this tag, and it's set to true.

<Defs>
    <ThingDef>
        <defName>ComponentIndustrial</defName>
        <intricate>true</intricate>
    </ThingDef>
</Defs>
The search result for intricate.

Take your favourite decompiler and search for intricate. Now right-click the result and hit analyze. The analyzer in my decompiler shows it's read in three places, and assigned nowhere. The decompiler doesn't show any assigning of this value because it's set in the XML. We can see it's read by PlayerItemAccessibilityUtility.CacheAccessibleThings and twice by Thing.SmeltProducts. Taking a closer look at the Thing+<SmeltProducts>c__Iterator4.MoveNext, this is an inner method for the enumerator[1]. That in itself doesn't do much, so let's take a look at SmeltProducts itself.

The view for SmeltProducts.

We can see here that SmeltProducts in turn is used for some economy related DebugOutput, and by MakeRecipeProducts. We can dive further down the rabbithole, but by now it is a reasonable assumption that SmeltProducts is used to determine what products you get from smelting. But what's the intricate tag? Well, SmeltProducts loops over the ingredients in the costList (i.e. the required ingredients to make an item) and checks if it's intricate. If it's not intricate, it will return the ingredient.

In other words, the intricate tag means that ThingDef won't survive a trip to the smelter. You don't get your components back if you smelt down an Assault rifle.

You can find the meaning of every XML tag this way. Some might be easier than others, but you can find (or make an educated guess) to the meaning of every XML tag.

Adding more tags[edit]

This requires C#. The current recommended way for maximum compatibility is by using a DefModExtension.

See also[edit]

  1. The what? An enumerable is a fancy type of list and the MoveNext means "go to the next item on the list". Apologies to those who have a background in computer science.